Button

Runs a single command when activated — form submits, dialog confirmations, toolbar actions, and inline commands.

Pick ButtonAppearance::Primary for the one main action on a surface. Wire async work with loading and on_click. For navigation, use Link instead.

  • Submitting forms, confirming dialogs, or firing one-off commands
  • Toolbar and card actions where a single clear primary action is needed
  • Icon-only affordances when space is tight (pair with aria-label on a wrapper)
  • Pick an ButtonAppearance — Primary for the main action, Secondary for alternatives.
  • Wire on_click with Callback when the button should run logic (not submit a native form).
  • Set loading while async work runs; disable the control when input is invalid or work is in-flight.
  • For E2E hooks, wrap the button in a native element with data-testid (see project UI rules).
Primary button

Default call-to-action on a form or dialog footer.

Secondary outline

Secondary actions beside the primary—cancel, back, or low-commit choices. Outline styling keeps emphasis below Primary without blending into the surface.

Subtle and transparent

Low-emphasis actions that blend into the surface until hovered.

With icon

Leading icon reinforces the action (save, add, search) while the text label keeps meaning clear for sighted users and screen readers.

Icon-only

Compact affordance when toolbar space is tight. Wrap with aria-label in app code—the button has no visible text for assistive technologies.

Sizes

Small fits toolbars and dense rows; medium is the default; large suits prominent mobile CTAs or hero actions. Set each with size=ButtonSize::….

Block (full width)

Stretches to the full container width—common for mobile form footers, stacked dialog actions, and narrow layouts.

Loading state

Spinner replaces the icon slot and blocks clicks while async work runs. Pair with disabled form controls to prevent double submission.

Shapes

Rounded is the default for labeled buttons. Circular and square fit icon-only controls in toolbars, floating actions, and compact settings grids.

Disabled

Unavailable actions stay visibly disabled and ignore clicks. disabled_focusable keeps the button in tab order for tooltips or custom disabled messaging.

Theme: primary uses brand token

Wrap in OrbitalThemeProvider with a custom brand palette so primary buttons use the theme's brand color token.