HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Icon ButtonView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA square button whose content is an icon.StableSince 0.1.0ActionsUsageimport'@fusion.dev/helix/icon-button'import'@fusion.dev/helix-headless/icon-button'Preview
API ReferenceRoothelix-icon-buttonA square button whose content is an icon.
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.material"frosted"|"glass"|"transparent"The ground under the button, for one that lies over a busy surface such as
a map or a board. glass lets the surface through under a blur, frosted
turns the pair up for a surface too busy for glass, and transparent draws
no ground at all. Unset, the ground is the emphasis's own.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.raisedbooleanDefaultfalseFloats the button over the page, with the theme's floating edge and shadow,
as a popover floats. A ghost button that floats is drawn on the overlay a
floating panel uses, so its glyph has a ground under it.shape"circle"The button's shape. Leave it unset for a rounded square, or set circle.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.
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 icon.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 button.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 icon, sized and colored by the --icon-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--icon-button-backdropThe filter behind a button with material, which a translucent ground needs to be read.--icon-button-background-colorFill behind the button, in every state.--icon-button-background-color-activeFill behind the button while it is pressed. Without it, a press shows the fill of the state under it.--icon-button-background-color-hoverFill behind the button under the pointer. Without it, --icon-button-background-color also applies on hover.--icon-button-border-colorEdge color of the control, where its emphasis or raised draws an edge.--icon-button-border-widthEdge width of the control, one to four widths as border-width takes them. The theme's floating edge on a raised button, --helix-border-floating.--icon-button-foreground-colorIcon color.--icon-button-foreground-color-activeIcon color while the button is pressed. Without it, a press shows the color of the state under it.--icon-button-radiusCorner radius of the control, which a group flattens through --button-radius-start and --button-radius-end, or a corner at a time through --button-radius-start-start, --button-radius-start-end, --button-radius-end-start and --button-radius-end-end, as Button reads them.--icon-button-shadowShadow of a raised icon button. The theme's floating shadow, --helix-shadow-floating.--icon-button-sizeEdge length of the control.--icon-button-spinner-colorColor of the ring a pending button turns. It follows the icon's color.--icon-button-spinner-durationHow long the ring takes to turn once.--icon-button-spinner-sizeSize of the ring a pending button turns.
Custom stateDescriptionpendingThe button is pending: pending is set. A ring turns over its hidden icon.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-icon-buttonA button whose content is an icon, named by its label.
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 icon.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 button.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
NameDescriptionAppearancesEach emphasis in a few tones, and a disabled icon button.PreviewA button that shows an icon, with a label read by screen readers.PreviewA button that shows an icon, with a label read by screen readers.ShapesSquare and round icon buttons, and a raised one for use over content.TonesThe tones an icon button comes in, including accent.