Button

Usage

When to use

• Submit a form, save changes, apply filters, or confirm data.
• Open UI like modals, drawers, popovers, or side panels.
• Trigger operations such as edit, duplicate, export, delete.
• Control UI states like expand, collapse, start, stop.
• Wrap anything that has to be keyboard reachable but is not a control of its own: an avatar used as a menu trigger, a card that is really one action.

Do not use when

• The text belongs in a sentence. Use a link inside the prose.
• You are displaying status or metadata. That is a Tag.
• You need too many equal priority actions in one place.

Hierarchy: color and variant

• solid is the main call to action. One per section where possible, usually with color="primary".
• filled is a tinted background and medium emphasis: stronger than outlined, quieter than solid.
• outlined is the standard secondary action, and what a bare Button already is.
• dashed reads as contextual or additive. Use it for “add another”, not as a third emphasis step.
• text and link are the two lowest steps. link looks like a link but is still a button unless you give it an href.

Choosing a color

• primary for the action the surface exists to perform.
• default for everything secondary, and for any gray button. The neutral palettes work too, but white text on their middle shade fails contrast on a solid button.
• danger for destructive actions only, and the variant carries how destructive: filled for reversible, outlined for consequential, solid for the one that cannot be undone.
• Use color="danger" rather than danger. The danger boolean is dropped as soon as you set color and variant, and on its own it only gives an outlined button.
• A preset or one of your theme's palettes when the button carries a category rather than a priority: a status filter, a brand action, a label color. Not as a second way to say “important”.

Shape

• Pick one shape per surface and keep it. Shape is brand, not hierarchy: a squircle button is not more important than a default one.
• squircle is progressive enhancement. Browsers without corner-shape render it exactly like default, so never let it be the only thing telling two buttons apart.
• circle is for icon-only controls. A circle with a label in it is a pill, which is round. For a rounded-square icon button, use shape="circle" with className="corner-squircle".
• square draws the same as default.

Button groups

• One solid button per group.
• Pair it with outlined or filled, never with a second solid.
• For equal choices, use the same variant for all of them.
• Separate destructive actions from constructive ones.
• Past three operations, fold the extras into a Dropdown. A button group that ends in a menu (Space.Compact + Dropdown + Button) keeps the primary action one click away while the rest stay one click deeper.
• Button.Group and Dropdown.Button are deprecated, so use Space.Compact to join buttons.

Order rules

• In horizontal groups, place the primary action at the end (the right in LTR, the left in RTL). Use logical properties so it mirrors on its own.
• In vertical stacks, place the primary action first.
• Keep spacing consistent across layouts.

Placement

• Place buttons close to the content they affect.
• Keep consistent positioning across modals and panels.
• Avoid scattering actions across unrelated areas.

Labels

• Use sentence case.
• Avoid vague labels like “OK” or “Yes”.
• Keep labels on one line when possible.
• Include the outcome for destructive actions.
• An icon-only button still needs a name: give it an aria-label and, where the meaning is not obvious, a Tooltip beside it.

Icons

• Ask for a semantic role (plus, download), never a library glyph by name. The role is what lets a whole product swap icon packs without touching a call site.
• A leading glyph labels the action, and a trailing one points at what happens next (arrow-right for continue, chevron-down for a menu).
• Use iconPlacement, not iconPosition. iconPosition is deprecated and warns at runtime. iconPlacement takes start or end and mirrors in right-to-left layouts.
• Use avatar for a face. It sizes the image from the button and keeps the same gap to the edge, the top and the bottom at every size and shape, where an image in icon sits too far from the edge. An explicit icon wins over it, and loading still shows the spinner.
• Do not use the icon to carry a state the label does not. Swapping the icon role, not the color, is what keeps a row from reflowing.

States and feedback

• Use loading to prevent repeated actions. Pass { delay: 300 } when the work is usually fast, so a quick response does not flash a spinner.
• A loading delay needs its own icon. loading={{ delay }} shows antd's spinner, not your icon pack's. Pass { delay, icon } to get both.
• Use disabled only when the action is truly unavailable. A disabled button is not focusable, so it cannot explain itself.
• A disabled link cannot be followed. A disabled button with an href renders an <a> with no href, so it cannot be focused or followed.
• Do not block the primary path without explanation.
• The spinner replaces whatever is in the icon slot, so a button with a glyph loses it while busy. Keep the label stable so the width does not jump.

Full width usage

• Use block in narrow layouts: mobile sheets, form footers, single-column cards.
• Keep the primary action at the top of stacked layouts.
• Avoid stacking more than three full width actions.

Styling and theming

• Your classes win. Button adds no colors of its own, so a class in className overrides antd's styles without !important.
• Put ghost buttons on a contrasting surface. ghost drops the background and keeps the border and text color, so use it over a photo or a dark panel, not a primary background. A ghost solid button renders as outlined.
• Keep the border on a gradient button. Use border-transparent with a gradient background. border-none removes the border box, so the button shrinks by the border width.
• Your classNames.icon adds to the kit's. AntuikitProvider sets an icon class that evens out the gap to the label, and yours is merged with it rather than replacing it.
• Change the disabled fill with tokens. defaultBgDisabled and dashedBgDisabled set the disabled background of default and dashed buttons. Pass var(--ant-*) values so one setting works in light and dark mode. Solid buttons read another token.
• Theme a region with ThemeScope. A nested ConfigProvider re-themes antd's components but not the plain elements beside them. ThemeScope themes both.
• Change the ripple on a ThemeScope. wave is a provider setting, not a Button prop. Pass wave={{ disabled: true }} to turn it off, or showEffect to replace it.