Button

Installation

Copy editable source into an initialized application:

pnpm dlx @simurgh-ui/cli add button

For package consumption, import from the component subpath and load its optional recipe CSS:

React

import { Button } from '@simurgh-ui/react/button';
import '@simurgh-ui/styles/button.css';

Vue

import { Button } from '@simurgh-ui/vue/button';
import '@simurgh-ui/styles/button.css';

Angular

import { ButtonComponent } from '@simurgh-ui/angular/button';
import '@simurgh-ui/styles/button.css';

Omit the component stylesheet for fully headless styling. CLI-copied components use the local path written to simurgh.json and the copied application styles instead of these package imports.

Purpose

Button defaults to type="button" to avoid accidental form submission. Loading state disables activation and exposes aria-busy while preserving its accessible name.

The default primary action is reserved for the main commitment on a surface. Use secondary for supporting actions, destructive for irreversible or high-risk actions, and quiet for low-emphasis toolbar or inline actions. Prefer one primary action per dialog, card, or form section.

Default presentation: native

The component preserves a familiar native element and browser behavior. The optional recipe harmonizes its appearance without replacing the platform interaction model.

Basic usage

Live component Button ◆

Save changesSaving…

Anatomy

The public component parts are listed in API surface below. Use only the parts needed by the example; compound components depend on their documented parent/child nesting.

State model

This component exposes no public controlled/uncontrolled state pair. Configure it through the props, events, native attributes, or parent-owned state documented in the API tables.

Set type="submit" explicitly for form submission. Loading state intentionally disables the native button, preventing duplicate actions.

Examples

React

<Button variant="primary" loading={saving}>Save changes</Button>
<Button variant="secondary">Preview</Button>
<Button variant="destructive">Delete</Button>
<Button variant="quiet">Cancel</Button>

Vue

<Button variant="primary" :loading="saving">Save changes</Button>

Angular

<simurgh-button variant="primary" [loading]="saving">Save changes</simurgh-button>

Accessibility

Preserve the documented composition and accessible names when wrapping or restyling this component. See accessibility and RTL guidance for keyboard, focus, labeling, and directionality requirements.

API surface

• React exports: Button
• Vue exports: Button
• Angular exports: ButtonComponent

Import these public symbols from the component subpath shown in Installation. Framework-specific props, events, slots, directives, methods, defaults, and native-attribute behavior belong in the API tables on this page; use the linked source only to verify the current implementation.

React API reference

React

An inherited-attributes entry means the component accepts the complete named React native interface, including its event handlers and ARIA and data attributes. Remaining attributes are forwarded to the rendered element unless the component behavior described on this page overrides them.

Button

Inherited attributes: ButtonHTMLAttributes<HTMLButtonElement> & RefAttributes<HTMLButtonElement>.

Prop	Type	Default / requirement
children	ReactNode	undefined
fullWidth	boolean	false
iconOnly	boolean	false
loading	boolean	false
ref	Ref<HTMLButtonElement> | undefined	undefined
size	"sm" | "md" | "lg"	'md'
variant	"primary" | "secondary" | "destructive" | "quiet"	'primary'

Vue API reference

Vue

Boolean props without explicit defaults use Vue’s false default. Undeclared attributes follow the fallthrough behavior stated for each component.

Button

Automatic fallthrough is disabled; attrs are manually forwarded to the rendered root.

Prop	Type	Default / requirement
loading	boolean	false
disabled	boolean	false
type	string	'button'
variant	string	'primary'
size	string	'md'
fullWidth	boolean	false
iconOnly	boolean	false

No emitted events.

Slots: default.

Exposed methods: none.

Angular API reference

Angular

Inputs and outputs use their public template names. Public methods are callable through a template reference or ViewChild. Native attributes apply to the documented template root or directive host; they are not automatically forwarded through component hosts.

ButtonComponent

Component selector: simurgh-button. The template’s first native element is button.

Input	Type	Default / requirement
type	"button" | "submit" | "reset"	'button'
loading	boolean	false
disabled	boolean	false
variant	"primary" | "secondary" | "destructive" | "quiet"	'primary'
size	"sm" | "md" | "lg"	'md'
fullWidth	boolean	false
iconOnly	boolean	false

No outputs.

Content projection: default.

No public methods.

Composition contract

Follow the framework example as a structural contract. Root components own shared state; parts that consume that state must stay under the root (or be attached to projected descendants in Angular). Parts described as conditional are optional until their corresponding interaction or semantic region is used. Do not render a state-consuming part by itself.

Framework	Required parent/child relationship	Conditional parts	Supporting types
React	Button is standalone and required when using this component.	Content is optional unless the API requires a label or value.	None.
Vue	Button is standalone and required when using this component.	Content is optional unless the API requires a label or value.	None.
Angular	ButtonComponent is standalone and required when using this component.	Content is optional unless the API requires a label or value.	None.

Accessible names, descriptions, and form labels remain required whenever the component’s purpose cannot otherwise be determined, even when the corresponding visual part is optional.

Framework parity and differences

The adapters target the same user-visible behavior and accessibility contract. Their public shapes follow each framework’s conventions and are not expected to be symbol-for-symbol identical.

Concern	Contract
Public composition	All adapters export 1 public symbol, with framework-idiomatic names.
State and change events	No controlled state contract; use native attributes, inputs, or events documented above.
Children and content	React uses children; Vue uses the slots listed above; Angular uses the documented content projection selectors.
Native attributes	React forwards the named native interface; Vue follows the stated fallthrough rule; Angular attributes apply to the component host unless an input, directive, or documented native root consumes them.
Imperative access	React forwards native refs; Vue exposes no methods; Angular exposes no public methods.

These differences are intentional adapter design. Behavioral or accessibility differences not stated on this page are parity defects rather than supported variations.

Form integration

This component is not a form control and does not contribute a named value to FormData. Use it to structure or describe a form only when its purpose and accessibility guidance apply.

Supported states

The table distinguishes component behavior from application-owned presentation. “Not supported” means there is no public state contract for that adapter; do not invent one with an undocumented attribute. Keep status and error messages accessible when they are rendered outside the component.

State	React	Vue	Angular
Loading	Supported with loading={true}; the component exposes its busy state and blocks duplicate interaction.	Supported with :loading="true"; the component exposes its busy state and blocks duplicate interaction.	Supported with [loading]="true"; the component exposes its busy state and blocks duplicate interaction.
Empty	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.
Invalid	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.
Read-only	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.
Disabled	Supported with disabled={true} on the documented control or interactive part; its interaction is blocked. Disabled form controls are omitted from submission.	Supported with :disabled="true" on the documented control or interactive part; its interaction is blocked. Disabled form controls are omitted from submission.	Supported with [disabled]="true" on the documented control or interactive part; its interaction is blocked. Disabled form controls are omitted from submission.
Error	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.	Not supported by this component API; handle this state in surrounding application UI.

Styling contract

Styling contract

The selectors below are used by the published component recipe or emitted consistently by an adapter. Treat these as the supported styling surface. Element order, anonymous wrappers, and undocumented descendants are implementation details and should not be targeted.

Surface	Stable hooks
Recipe classes	.simurgh-trigger
Stable DOM parts	[data-slot="button"], [data-slot="checkbox"], [data-slot="input"], [data-slot="input-otp"], [data-slot="native-select"], [data-slot="pagination-link"], [data-slot="select-trigger"], [data-slot="toggle-group-item"], [data-slot="toolbar-button"]
Stable data attributes	[data-density], [data-full-width], [data-icon-only], [data-size], [data-slot], [data-state], [data-variant]
ARIA/state selectors used by the recipe	No ARIA state selector is used by this recipe.
CSS custom properties consumed	--simurgh-border, --simurgh-control-height, --simurgh-control-padding, --simurgh-danger, --simurgh-duration, --simurgh-foreground, --simurgh-muted, --simurgh-primary, --simurgh-primary-foreground, --simurgh-radius, --simurgh-ring, --simurgh-surface

Prefer a semantic token override for theme-wide changes. Use the listed class or part selectors for a component-scoped override. When omitting recipe CSS, preserve state attributes and ARIA semantics even if your replacement styles use different selectors.

Customization

Load the optional component stylesheet for the default recipe, override semantic tokens for broad theme changes, or omit the recipe CSS for headless styling. See theming and styling hooks for import order, selectors, dark mode, RTL, and reduced-motion guidance.

Use size="sm" only in space-constrained toolbars, md for normal interfaces, and lg for prominent calls to action. iconOnly keeps the control square but does not create an accessible name: provide aria-label whenever visible text is absent. fullWidth is intended for narrow layouts and stacked mobile actions.

Last verified on 2026-08-13 against Simurgh registry 0.1.1.

Related components

• Review the shared accessibility and RTL guidance and theming and styling hooks.
• Use the component chooser and component overview to compare related primitives.
• Inspect the registry manifest and framework source for React, Vue, or Angular.