# Plan Selector

A selectable plan or tier picker for checkout and subscription flows. Configure up to 10 plans with title, price, subtitle, and a hidden price code -- perfect for connecting to Stripe or custom payment actions. Add a billing toggle to let users switch between Monthly and Yearly pricing.

## Getting Started

1. Add the Plan Selector component to your screen from the Marketplace.
2. By default, 3 plans appear (Basic, Pro, Enterprise) with the first plan pre-selected.
3. Set each plan's **Title**, **Price**, and **Subtitle** in the property panel.
4. Use the **On Plan Selected** action to trigger navigation, data updates, or payment flows.
5. Access the selected plan's details via Magic Text: **Selected Plan Title**, **Selected Plan Price**, **Selected Price Code**, and **Selected Plan Index**.

## Settings

### Number of Plans

Controls how many plan cards are shown. Use the slider to set between 1 and 10 plans (default: 3). Each plan appears as a separate section in the property panel.

### Show Billing Toggle

Enables a tab bar above the plans for switching between billing periods (default: off). When enabled, you can set per-tab pricing for each plan.

### Number of Tabs

How many tabs appear in the billing toggle (default: 2). Currently supports 2 tabs.

### Tab 1 Label

The label for the first tab (default: "Monthly"). Only visible when **Show Billing Toggle** is on.

### Tab 2 Label

The label for the second tab (default: "Yearly"). Only visible when **Show Billing Toggle** is on.

### Default Tab

Which tab is selected when the component loads (default: 1). Only visible when **Show Billing Toggle** is on.

### Default Selected Plan

Which plan is pre-selected on load (default: 1). Set to 0 for no plan selected by default.

### On Plan Selected

An action that fires every time a user taps a plan card. Use this to navigate to a checkout screen, update a database record, or trigger a Stripe payment.

## Plan Settings (Plan 1 -- Plan 10)

Each plan has the following settings. Plans 4--10 use generic defaults ("Plan 4", "$99", etc.).

### Title (Tab 1)

The plan name shown to users (e.g., "Basic", "Pro", "Enterprise"). Supports Magic Text.

### Icon

An optional icon displayed next to the plan title. Set **Icon Position** in Appearance to "Left" or "Right" to show it. Uses Material Icons.

### Price (Tab 1)

The price displayed on the plan card (e.g., "$9", "$19/mo"). Supports Magic Text.

### Subtitle (Tab 1)

A secondary line of text below the price (e.g., "Billed Monthly", "Best Value"). Supports Magic Text.

### Price Code (Tab 1)

A hidden value not shown to users -- use this for Stripe price IDs or internal codes (e.g., "price\_1234abc"). Available via Magic Text as **Selected Price Code**.

### Title (Tab 2)

The plan title when the second tab is active. Leave empty to use the same title for both tabs.

### Price (Tab 2)

The price when the second tab is active (e.g., "$90/yr" vs "$9/mo").

### Subtitle (Tab 2)

The subtitle when the second tab is active.

### Price Code (Tab 2)

The price code when the second tab is active -- use a different Stripe price ID for yearly billing.

## Appearance

### Selection Style

How the selected plan card looks (default: Outline).

* **Outline** -- selected plan gets a colored border only
* **Fill** -- selected plan gets a colored background only
* **Outline + Fill** -- selected plan gets both a colored border and background

### Selected Border Color

The border color for the selected plan (default: #D4A843, gold).

### Selected Border Width

The thickness of the selected plan's border, 1--6px (default: 3).

### Selected Background Color

The fill color for the selected plan when using Fill or Outline + Fill style (default: rgba(212,168,67,0.1)).

### Unselected Border Color

The border color for unselected plans (default: #444444).

### Unselected Border Width

The thickness of unselected plan borders, 0--4px (default: 1).

### Unselected Background Color

The background color for unselected plans (default: transparent).

### Border Radius

The corner rounding of plan cards, 0--24px (default: 12).

### Gap Between Plans

Vertical spacing between plan cards, 0--24px (default: 12).

### Inner Padding

The padding inside each plan card, 8--32px (default: 16).

### Icon Position

Where to show the plan icon (default: None).

* **None** -- no icon shown
* **Left** -- icon appears to the left of the title
* **Right** -- icon appears to the right of the price

### Icon Size

The size of the plan icon, 16--48px (default: 24). Only visible when Icon Position is Left or Right.

### Icon Color

The color of the plan icon (default: #FFFFFF). Only visible when Icon Position is Left or Right.

### Tab Bar Background

The background color of the billing toggle bar (default: #F0F0F0).

### Active Tab Color

The background color of the active tab pill (default: #FFFFFF).

### Active Tab Text Color

The text color of the active tab label (default: #333333).

### Inactive Tab Text Color

The text color of inactive tab labels (default: #999999).

### Tab Border Radius

The corner rounding of tab pills, 0--20px (default: 8).

### Tab Font Size

The font size of tab labels, 10--20px (default: 14).

### Tab Font Weight

The font weight of the active tab label (default: Semi Bold). Options: Regular, Medium, Semi Bold, Bold.

### Tab Padding

The vertical padding inside each tab pill, 4--20px (default: 10).

## Text Formatting

### Title Font Size

The font size of plan titles, 12--28px (default: 18).

### Title Font Weight

The font weight of plan titles (default: Semi Bold). Options: Light, Regular, Medium, Semi Bold, Bold.

### Title Color

The color of plan titles (default: #FFFFFF).

### Subtitle Font Size

The font size of plan subtitles, 10--20px (default: 13).

### Subtitle Color

The color of plan subtitles (default: #AAAAAA).

### Price Font Size

The font size of plan prices, 14--36px (default: 22).

### Price Font Weight

The font weight of plan prices (default: Bold). Options: Regular, Medium, Semi Bold, Bold.

### Price Color

The color of plan prices (default: #FFFFFF).

## Magic Text Outputs

The Plan Selector outputs 6 values available as Magic Text anywhere on the same screen:

* **Selected Plan Title** -- the title of the currently selected plan (updates when switching tabs)
* **Selected Plan Price** -- the price of the currently selected plan
* **Selected Price Code** -- the hidden price code (great for passing Stripe price IDs to custom actions)
* **Selected Plan Index** -- the index of the selected plan (1-based)
* **Active Tab Label** -- the label of the currently active billing tab (e.g., "Monthly" or "Yearly")
* **Active Tab Index** -- the index of the active tab (1-based)

## Tips & Best Practices

* Use the **Price Code** field to store Stripe price IDs (e.g., "price\_1O2abc") -- this keeps internal identifiers hidden from users while making them available via Magic Text for payment actions.
* When using the billing toggle, always set both Tab 1 and Tab 2 prices for each plan. If you leave Tab 2 Price empty, it falls back to the Tab 1 price.
* Set **Default Selected Plan** to 0 if you want users to actively choose a plan before proceeding. Combine with a conditional action that checks if Selected Plan Index > 0.
* The **On Plan Selected** action fires on every tap, even if the user taps the already-selected plan. Use this to navigate to a checkout screen or update a record.
* For dark-themed apps, the default colors (white text, gold borders, dark backgrounds) work well out of the box. For light themes, adjust the Title Color, Price Color, and border colors.
* The billing toggle tab labels support Magic Text -- you can bind them to database values if your pricing periods are dynamic.
* Plan titles support Magic Text too, so you can pull plan names from your database instead of hardcoding them.

## Example Use Cases

* **SaaS Subscription Checkout** -- Show 3 tiers (Free, Pro, Enterprise) with Monthly/Yearly toggle. Pass the Selected Price Code to a Stripe payment action on the next screen.
* **Event Ticket Selection** -- Configure 4 plans (General Admission, VIP, Backstage, Group) without the billing toggle. Use the Selected Plan Title and Price to populate a confirmation screen.
* **Meal Plan Picker** -- Show 3 options (Basic, Standard, Premium) with Weekly/Monthly toggle. Use different price codes per tab to handle different subscription intervals.
* **Membership Tiers** -- Display up to 10 membership levels with icons (star, diamond, crown). Use the Icon Position and Icon Color settings to match your brand.
* **Service Package Quote** -- Show packages with prices pulled from your database via Magic Text. Use the Selected Plan Index to filter related features on the same screen.