Variants and states
Add, hide, rename and remove shadcn/ui variants, sizes and axes in DS Manager, and style hover, focus, pressed, disabled and other component 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.
- Open the Variant menu. The value the component falls back to is marked "default".
- Pick a value. The ring on the canvas moves to a specimen with that value, and the controls below show what it renders.
- Do the same in Size.
An edit changes only the variant, size and state you have picked. Colors, borders and radius go to the picked variant, and height, padding and text size go to the picked size. With Variant on outline, a new background or radius changes only outline buttons. Clicking a matrix cell or ⌘-clicking a specimen sets the menus for you. See Editing components for more on selecting parts.
Adding a variant

- Open the Variant menu and pick Add new… at the bottom.
- Type a Name in kebab-case, such as
brandorbrand-subtle. - In Clone from, pick the value to start from. The new value copies its current classes, including your edits, so it renders right away.
- Click Add variant.
The menus switch to the new value, the canvas selects it, and you style it like any other. It is exported as a real cva key, so in your project you write <Button variant="brand">.
On a custom component, the Size menu's Add new… opens this same dialog for a size.
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, and axes you create (see Adding an axis), 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…".
Adding a size
On a built-in component, you add a size by picking a size to start from and a scale. This works on the components that already have a Size menu, such as Button, Toggle and Item. Input, Textarea, Badge and Kbd can get sizes too, and once you add one, the installed component takes a real size prop.
- Pick Add new… in the Size menu of the Style tab. The Add size to Button dialog opens, named after the component. Input, Textarea, Badge and Kbd have no Size menu before their first size: press ⌘K and run "Add a size to Input…", or click Add axis and name the axis
size, as in Adding an axis. - Choose how to add it:
- Controls sizes, on Button, Toggle and Input: tick sm, lg or both. Each one takes its height from the Controls page and keeps following it when you change Controls later. Only the Controls sizes the component doesn't have yet are listed.
- Or add one size: type a Name, pick the size to Start from (each one shows its height in px), and pick a Scale: 0.75×, 0.875×, 1.25×, 1.5× (the default), 2× or Custom.
- Check Values. It lists what the new size will write, Height, Padding x, Padding y, Text size and Icon size, each with a checkbox. Untick any you want to leave as they are. Custom turns the new values into fields you type in. When the new height matches a Controls size, Height says "Follows Controls" and the size name.
- Click Add with the size's name, such as Add xl, or Add sm and lg.

The canvas then selects the new size and scrolls it into view. Adding both Controls sizes at once is one undo step.
The command menu has "Add a size to Button…" for the same dialog. Custom components keep the dialog from Adding a variant, with Clone from.
Adding an axis
Button, Toggle, Input, Textarea, Badge, Kbd and Avatar can take an axis the kit doesn't ship, such as shape on Avatar.
- In the Style tab, click Add axis in the Axis row under State. Or press ⌘K and run "Add an axis to Avatar…".
- Type a Name, such as
shape. It must be one lowercase word of up to 24 characters, because it becomes a prop. - Type a New value, such as
square. - Click Add shape. The button carries the name you typed.
Today's look becomes the axis's default value. The new value starts with no classes of its own and draws like the default until you style it, the same way as an added variant. The axis then has its own menu under State, whose Add new… adds more values, and its own group in the matrix, named in the plural, such as "Shapes". On Avatar, a value's radius also reaches the ring, the image, the fallback and the group count.
The axis is exported as a real cva key and installs as a prop, so in your project you write <Avatar shape="square">.
A component takes up to 3 axes of its own, a size included. The dialog explains a name it refuses, for example "Avatar already has a shape axis. Add a value from Add new… in its menu." or a name the installed component already uses as a prop. On Input, Textarea, Badge and Kbd, an axis named size adds their first size, worked out the way Adding a size works one out. Other components have no Axis row, and ⌘K reads, for example, "Card takes no new axis".
Rename or delete an axis in Manage variants. Custom components don't take new axes.
Hiding a built-in variant or size
A built-in value you don't want in your system, such as Button's outline, can be hidden without breaking code that still uses it.
- Click Manage variants under the menus in the Style tab. The dialog lists every variant and size of the component, and the axes you created.
- Click the eye-off button on a built-in value, Hide outline from this system. The value marked "default" in the menu can't be hidden.
- In Use instead, pick the value that takes its place.
- Click Done.

A hidden value leaves the menus and the matrix. Anything that still uses it draws as its replacement: the other components, Pro Blocks, your custom components and the installed code. In your project, variant="outline" keeps working and looks like the value you picked. A line under the menus, such as "1 variant hidden" or "2 sizes hidden", opens the dialog again.
To bring a value back, open Manage variants and click Show beside its name. Hiding, showing and changing Use instead are each one undo step.
Custom components don't have hiding.
Renaming and removing values
Values you added sit in the menus next to the built-in ones, and Manage variants lists them with a Custom tag. On an axis you created, the default value has a Default tag. You can rename it, but not delete it, and the default of a size added through Add axis keeps its name.
An axis you created has a header in Manage variants with two buttons: Rename the shape axis and Delete the shape axis. Deleting the axis removes all its values.
- Click Manage variants.
- Click the pencil to rename a value, type the new name and confirm. The rule is renamed with it. A name that another part of the component already uses on that axis is refused, with the reason under the field.
- Click the trash icon to remove a value. Press ⌘Z if you removed the wrong one.
- Click Done.
A rename changes the cva key. Code in your project that still uses the old name has to be updated by hand.
When a custom component uses a value you added, its row in Manage variants says so, such as "Used in Rating's code.", with the file and line on hover. After a rename or removal that leaves a custom component on the old name, a warning names it and ends "Ask the agent to update it."
The built-in shadcn/ui variants can't be renamed or removed, because components in your project rely on them. Restyle them, or hide 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
- Pick the variant, size and state, in any order. The state stays when you change Variant or Size. ⌘-clicking an element that is checked, open, disabled or invalid sets the State menu to that state.
- Change any control. The edit is written for that state only, such as
hover:bg-primary/80ordisabled: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.