Button
Buttons trigger explicit product actions. Choose a clear label and the least visual emphasis that still matches the decision.
Overview and decision boundary
Use Button for explicit product actions that submit, save, create, continue, or trigger a workflow.
Do not use a button render target when the interaction navigates to a destination.
import { ArrowUp } from "@nerio-ui/adapters/icons";import { Button } from "@nerio-ui/ui/client";<Button>Button</Button><Button icon={ArrowUp} aria-label="Move up" tooltip="Move up" />Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add buttonimport { Save, Settings } from '@nerio-ui/adapters/icons';import { Badge, Kbd } from '@nerio-ui/ui';import { Button } from '@nerio-ui/ui/client';Usage
import { Save, Settings } from '@nerio-ui/adapters/icons';import { Badge, Kbd } from '@nerio-ui/ui';import { Button } from '@nerio-ui/ui/client';<Button leadingIcon={Save} badge={<Badge size="sm" tone="info">24</Badge>} kbd={<Kbd>⌘S</Kbd>}>Save project</Button><Button icon={Settings} aria-label="Workspace settings" tooltip="Workspace settings" />Variants
| Variant | Use |
|---|---|
primary | Lead one clear local decision. |
secondary | Support the primary action without competing with it. |
outline | Offer a bounded secondary action on a quiet surface. |
ghost | Keep repeated or low-emphasis actions visually calm. |
link | Use for navigation with an anchor render target; it has no control padding and underlines on hover or focus-visible. |
danger | Signal a destructive action that needs explicit intent. |
Anatomy
| Slot | Purpose |
|---|---|
button | Base UI button primitive with variant, size, disabled, loading, and focus states. |
button-icon | Optional leading or trailing icon rendered through the Nerio icon adapter. |
button-label | Visible action text that remains available while loading. |
button-badge | Optional Badge count or status placed after the visible action label. |
button-kbd | Optional quiet keyboard shortcut hint placed between the label and trailing icon. |
States
| State | Behavior |
|---|---|
Default, hover, and active | Variant tokens control interaction feedback. |
Focus | Focus-visible uses the shared Nerio focus ring. |
Loading | Disables repeat activation and exposes aria-busy. |
Disabled | Prevents activation while preserving layout. |
Motion
- Hover transitions background, border, color, and opacity through motion tokens.
- Press uses a subtle tokenized scale transform and is removed for reduced motion.
- Focus-visible animates the shared focus ring without moving layout.
Accessibility
- Uses the Base UI Button primitive and renders a native button by default.
- For navigation, set nativeButton={false} and render Button as a native anchor with variant link; it has no control padding and underlines on hover or focus-visible.
- Custom render elements receive Button-owned content, state hooks, caller props, event handlers, classes, and refs without losing their chosen native semantics; function renders retain the Base UI button interaction contract.
- Provide concise visible text or an accessible name.
- Loading preserves the action name, disables repeat activation, and exposes aria-busy.
- Disabled and loading states prevent repeat activation.
- Icons render through the Nerio icon adapter and remain decorative by default.
- For an icon-only Button, provide icon and an aria-label; Button uses that accessible name as the Tooltip label unless an explicit tooltip is provided.
- Shortcut display is supplemental; add aria-keyshortcuts yourself when a keyboard shortcut is functional.
- Badge content remains part of the Button accessible name; use a concise count or status that refines the action.
- Keep the visible focus treatment enabled.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Values | Purpose |
|---|---|---|
variant | primary | secondary | outline | ghost | link | danger | Sets action emphasis. |
size | sm | md | lg | Uses density-aware height tokens. |
leadingIcon / trailingIcon | IconComponent | Places a decorative icon before or after the label. |
icon + aria-label | IconComponent + string | Creates an accessible icon-only action. |
badge | <Badge> | Adds a concise count or status after the visible label at sm size. |
kbd | <Kbd> | Displays a quiet shortcut hint after the label. |
tooltip | ReactNode | Adds supplemental hover and focus help. |
loading | boolean | Shows Spinner, disables activation, and sets aria-busy. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | button installs Button with its Badge, Kbd, and Tooltip dependencies. |
Base UI | button |
Registry dependencies | badge, tooltip, kbd |
Package dependencies | @base-ui/react, @nerio-ui/adapters, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use one primary Button per local decision.
- Use danger for destructive actions and pair it with explicit copy.
- Use the link variant with a native anchor render target for navigation.
Do / do not
Do
Use one primary action per local decision and keep labels action-oriented.
Do not
Use the link variant with an anchor render target for a destination.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Sizing | --n-button-height-sm / md / lg | Control heights across density modes. |
Shape | --n-button-radius | Corner radius for text and icon-only Buttons. |
Primary | --n-button-background-primary / hover / active | Primary action surface. |
Secondary | --n-button-background-secondary / hover / border / foreground | Supporting action treatment. |
Ghost | --n-button-background-ghost / hover / foreground | Low-emphasis action treatment. |
Link | --n-link-color / hover / underline-offset / underline-thickness | Text-level navigation with an underline on hover and focus-visible. |
Danger | --n-button-background-destructive / foreground-destructive | Destructive action treatment. |
Button Kbd | --n-button-kbd-background / border-color / foreground / opacity | Quiet shortcut treatment inside a Button. |
Button Badge | --n-badge-height-sm / radius / padding-inline-sm | Compact count or status treatment inside a Button. |
Icon-only | --n-icon-button-size-sm / md / lg / radius | Square Button sizing when icon is used. |
Interaction | --n-motion-hover-duration / --n-motion-press-duration / --n-focus-ring | Motion and focus feedback. |