Search documentation

Search docs pages and sections

  • Docs home
Figma Kit
  • Getting started
  • Styles
  • Variables
  • Typeset
  • Theming
  • Components
  • Icons
  • Development
  • Updates
Registry
  • Pro Blocks
  • Templates
  • Themes
Plugin
  • Introduction
  • Generate code
  • Manage variables
  • Typeset
  • Select and install Pro Blocks
  • Security
Agent Skills
  • Agent Skills
DS Manager
  • DS Manager
  • Quickstart
  • Interface tour
  • Styles and icons
  • Colors and tokens
  • Typography
  • Radius, spacing and shadow
  • Controls
  • Brand
  • Editing components
  • Variants and states
  • Breakpoints
  • Custom components
  • ProBlocks
  • Design agent
  • MCP server
  • Lint locks
  • Publish and install
  • Share links and forks
  • Comments
  • Plans and limits
Licensing
  • Licensing agreement
  1. Documentation
  2. Variants and states

Menu

HomePreviewPricingRoadmapHelp & Contact

Products

shadcn Componentsshadcn BlocksAgent SkillsDS ManagerNewFigma Pluginshadcn Templates

Resources

shadcn ThemesTheme GeneratorDocsAcademyBlogIcons

Legal

Licensing AgreementTerms & ConditionsPrivacy PolicyCookies

Components

AccordionAlertAlert DialogAspect RatioAttachmentAvatarBadgeBreadcrumbBubbleButtonButton GroupCalendarCardCarouselChartCheckboxCode BlockCollapsibleComboboxCommandContext MenuData TableDate PickerDialogDrawerDropdown MenuEmptyFieldFormHover CardIcons - HugeIconsIcons - Lucide IconsIcons - Phosphor IconsIcons - Remix IconIcons - Tabler IconsInputInput GroupInput OTPItemKbdLabelMenubarMessageMessage ScrollerNavigation MenuPaginationPopoverProgressQuestionnaireRadio GroupResizableScroll-areaSelectSeparatorSheetSidebarSkeletonSliderSonnerSpinnerSwitchTableTabsTextareaToastToggleToggle GroupTooltipTraceTypesetTypography

Landing Page Blocks

404 SectionsBannersBento GridsBlog SectionsCTA SectionsComparison SectionsContact SectionsEmpty LP SectionsFAQ SectionsFeature SectionsFootersGallery SectionsHeader SectionsHero SectionsLP NavbarsLanding Page ExamplesLogo SectionsPatternsPricing SectionsRich Text SectionsStats SectionsTeam SectionsTestimonials Sections

Application Blocks

App ShellsApplication ExamplesButtonsCardsDescription ListsEmpty SectionsNavbarsPage HeadersSection FootersSection HeadersSectionsSettingsSign inSign upTable Headers

E-commerce Blocks

CheckoutsExamplesIncentivesOrder Summary SectionsProduct Category SectionsProduct HeadersProduct List FiltersProduct List SectionsSale SectionsShopping CartsStore Navbars

This project is independent and not affiliated with Figma or shadcn/ui.
Copyright © 2026 Matt Wierzbicki

Variants and states

Add, hide, rename and remove shadcn/ui variants and sizes 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.

  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 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

The Add variant dialog in DS Manager with brand typed in the Name field and a Clone from menu set to default
  1. Open the Variant 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.

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 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.

  1. Pick Add new… in the Size menu of the Style tab. On Input, Textarea, Badge and Kbd, before their first size, the Size row is an Add size button instead. The Add size to Button dialog opens (named after the component).
  2. 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.
  3. 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.
  4. Click Add with the size's name, such as Add xl, or Add sm and lg.
The Add size to Button dialog with xl as the name, lg (40px) in Start from, 1.5× in Scale, and Height, Padding x, Text size and Icon size ticked under Values with their old and new values

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.

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.

  1. Click Manage variants under the menus in the Style tab. The dialog lists every variant and size of the component.
  2. 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.
  3. In Use instead, pick the value that takes its place.
  4. Click Done.
The Manage variants dialog for Button with outline tagged Hidden and secondary picked in Use instead, and the eye-off button on the other variants and sizes

A hidden value leaves the menus and the matrix. Anything that still uses it draws as its replacement: the other components, ProBlocks, 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 outline again on its row. 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.

  1. Click Manage variants.
  2. 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.
  3. Click the trash icon to remove a value. Press ⌘Z if you removed the wrong one.
  4. 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

  1. 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.
  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.