HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
ButtonView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorTriggers an action, submits a form, or navigates.StableSince 0.1.0ActionsUsageimport'@fusion.dev/helix/button'import'@fusion.dev/helix-headless/button'Preview
API ReferenceRoothelix-buttonTriggers an action, submits a form, or navigates.
PropTypeDescriptioncommandstringDefault""What to send when the button is activated, and what to send it to.commandForstringDefault""The id of the element the command is sent to.commandForElementElement|nullThe element this button's command is sent to, resolved.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.emphasis"ghost"|"outlined"|"solid"|"subtle"How much fill the control is drawn with.expandedbooleanWhether this button is a disclosure trigger, and whether its panel is open.focusablebooleanDefaulttrueWhether the button holds its group's tab stop.formActionstringDefault""Where this button's submission goes, overriding the form's own.formEnctypestringDefault""How the submission is encoded, overriding the form's own.formMethodstringDefault""Which HTTP method the submission uses, overriding the form's own.formNoValidatebooleanDefaultfalseWhether this submission skips the form's validation.formTargetstringDefault""Which browsing context the response lands in, overriding the form's own.labelstringThe button's name, read by screen readers, for a button whose content is
not text.namestringDefault""The name the control's value is submitted under.pendingbooleanDefaultfalseWhether the action the button started is still running.pendingLabelstringDefault"Loading"What a reader hears when the button becomes pending while it has focus.popup"dialog"|"grid"|"listbox"|"menu"|"tree"What kind of panel this button opens, where it opens one: menu for a
Menu.tone"accent"|"danger"|"neutral"|"primary"Which color the control is drawn in, by what it means.type"button"|"submit"|"reset"Default"button"What activating the button does to its form.valuestringDefault""The value this button submits under its own name, as a native submit
button does.width"auto"|"full"How much of the available width the button takes.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The button's label.endContent after the label.startContent before the label, usually an icon.
EventTypeDescriptionhelix-pressHelixPressEventFired when a press acts, with detail.pointerType saying what pressed the button.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.click() => voidPresses the button, as click() presses a native one: the command is sent,
the form submits or resets, and helix-press says virtual.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionbuttonThe inner control.liveThe live region that says pending-label when the button becomes pending under focus. It is clipped out of view and still read.spinnerThe ring a pending button turns over its words, sized and colored by the --button-spinner-* hooks.textThe button's words, which the styled button trims to their capitals and baseline so the letters sit at the middle in any font.
CSS PropertyDescription--button-background-colorFill behind the button, in every state.--button-background-color-hoverFill behind the button under the pointer. Without it, --button-background-color also applies on hover.--button-border-colorEdge color of an outlined button. The other emphases draw no edge.--button-foreground-colorLabel and icon color.--button-gapSpace between the label and the content on either side of it.--button-inline-sizeMinimum width. It inherits, so you can set it once on a section for every button inside it.--button-padding-inlineInline padding, for a container with spacing of its own.--button-radiusCorner radius of the control.--button-radius-endTrailing corners, which a group flattens.--button-radius-end-endThe bottom trailing corner, for a group stacking down.--button-radius-end-startThe bottom leading corner, for a group stacking down.--button-radius-startLeading corners, which a group flattens.--button-radius-start-endThe top trailing corner, for a group stacking down.--button-radius-start-startThe top leading corner, for a group stacking down.--button-sizeHeight of the control, for a row height outside the density steps.--button-spinner-colorColor of the ring a pending button turns. It follows the label's color.--button-spinner-durationHow long the ring takes to turn once.--button-spinner-sizeSize of the ring a pending button turns. Defaults to the size of its icons.
Custom stateDescriptionpendingThe button is pending: pending is set. A ring turns over its hidden words.pressedA Button Group in a selection mode has this button pressed.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-buttonTriggers an action, submits a form, or navigates.
PropTypeDescriptioncommandstringDefault""What to send when the button is activated, and what to send it to.commandForstringDefault""The id of the element the command is sent to.commandForElementElement|nullThe element this button's command is sent to, resolved.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.expandedbooleanWhether this button is a disclosure trigger, and whether its panel is open.focusablebooleanDefaulttrueWhether the button holds its group's tab stop.formActionstringDefault""Where this button's submission goes, overriding the form's own.formEnctypestringDefault""How the submission is encoded, overriding the form's own.formMethodstringDefault""Which HTTP method the submission uses, overriding the form's own.formNoValidatebooleanDefaultfalseWhether this submission skips the form's validation.formTargetstringDefault""Which browsing context the response lands in, overriding the form's own.labelstringThe button's name, read by screen readers, for a button whose content is
not text.namestringDefault""The name the control's value is submitted under.pendingbooleanDefaultfalseWhether the action the button started is still running.pendingLabelstringDefault"Loading"What a reader hears when the button becomes pending while it has focus.popup"dialog"|"grid"|"listbox"|"menu"|"tree"What kind of panel this button opens, where it opens one: menu for a
Menu.type"button"|"submit"|"reset"Default"button"What activating the button does to its form.valuestringDefault""The value this button submits under its own name, as a native submit
button does.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The button's label.endContent after the label.startContent before the label, usually an icon.
EventTypeDescriptionhelix-pressHelixPressEventFired when a press acts, with detail.pointerType saying what pressed the button.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.click() => voidPresses the button, as click() presses a native one: the command is sent,
the form submits or resets, and helix-press says virtual.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionbuttonThe inner control.liveThe live region that says pending-label when the button becomes pending under focus. It is rendered from the first time the button is pending, and the styled button clips it out of view.spinnerThe ring a pending button turns, an empty element the styled button draws over the words. It is rendered only while the button is pending.textThe button's words, which the styled button trims to their capitals and baseline so the letters sit at the middle in any font.
Custom stateDescriptionpendingThe button is pending: pending is set.pressedA Button Group in a selection mode has this button pressed.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionAccentThe accent tone, a second emphasis derived from your brand color.As LinkA button that navigates, rendered as an anchor.DisabledDisabled buttons in several appearances, including one disabled by its fieldset.EmphasisEach emphasis in the neutral, primary, and danger tones.Form OverridesThree submit buttons on one form, each setting where and how its own submission goes.HuggingButtons in a narrow column, one as wide as the column and one as wide as its label.PendingA button that waits after a press: it keeps focus, refuses another press, and says Saving to a screen reader.PreviewButtons in each appearance and tone, the two settings that style a button.PreviewButtons in each appearance and tone, the two settings that style a button.TonesThe four tones, which mark what an action means.WidthButtons at their own width, at a standard width set by --button-inline-size, and at full width with width.With SlotsIcons at either end of the label, placed in the start and end slots.