Variants and states

Variants, sizes and states are dropdowns at the top of a component's Style tab. Each menu picks which specimen you edit, and the Variant and Size menus are also where you add values of your own.

Picking a variant and size

On a component page, the Style tab opens with the root part selected and every menu on its default. The rows depend on the component: a Button has Variant and Size, an Avatar has Size, a Separator has Orientation, and a component with no variants has none.

1. Open the Variant menu. The value the component falls back to is marked "default".
2. Pick a value. The ring on the canvas moves to a specimen with that value, and the controls below show what it renders.
3. Do the same in Size.

An edit goes to the rule that sets the property. If you change the background with Variant on outline, only outline buttons change. If you change the radius, which the base rule sets, every variant changes. Clicking a matrix cell or ⌘-clicking a specimen sets the menus for you. See Editing components for more on selecting parts.

Adding a variant or size

1. Open the Variant or Size menu and pick Add new… at the bottom.
2. Type a Name in kebab-case, such as brand or brand-subtle.
3. In Clone from, pick the value to start from. The new value copies its current classes, including your edits, so it renders right away.
4. Click Add variant (or Add size).

The menus switch to the new value, and you style it like any other. It is exported as a real cva key, so in your project you write <Button variant="brand">.

The dialog explains a name it refuses, for example "Variant name is required." or "Brand" must be kebab-case, e.g. "brand" or "brand-subtle". A name the axis already has is refused too.

Only the Variant and Size axes take new values. Axes like Orientation have no Add new… row. You can also start from the command menu: press ⌘K and run "Add a variant to Button…".

Renaming and removing values

Values you added sit in the menus next to the built-in ones. When a component has any, a Manage custom variants button appears under the menus.

1. Click Manage custom variants. The dialog lists your values by axis.
2. Click the pencil to rename a value, type the new name and confirm. The rule is renamed with it.
3. Click the trash icon to remove a value. Press ⌘Z if you removed the wrong one.
4. Click Done.

The built-in shadcn/ui variants can't be renamed or removed, because components in your project rely on them. Restyle them instead.

States

The State menu lists Default, then only the states that the component's rules already style:

• Hover
• Focus
• Pressed
• Selected (named Checked on some components)
• Open
• Disabled
• Invalid

You can't add a state that the component does not have. A component with no states shows no State menu.

Under a divider, the same menu lists parts drawn with ::before and ::after, such as Underline and Marker, when the component has them.

Editing a state

1. Pick the variant and size first, then pick the state.
2. Change any control. The edit is written for that state only, such as hover:bg-primary/80 or disabled:opacity-50.

DS Manager shows Selected, Open, Disabled and Invalid on the canvas while you edit them. Hover and focus can't be held on, so the rail tells you to "Hover the element on the canvas to see this state." or "Tab to the element on the canvas to see this state."

A control whose value comes from the resting element is dimmed. It is still editable: typing a value gives the state its own.

To see or add the raw classes for a state, open the Utilities tab. Classes are grouped by state there, and + Add in a state group writes the prefix for you.