Button
<cs-button>
Buttons represent actions the user can take, such as submitting a form, opening a dialog, or navigating to another page.
Examples
Variant
Use the variant attribute to set the button’s semantic variant.
Appearance
Use the appearance attribute to change the button’s visual appearance. Pair it with any variant for the full matrix.
Size
Use the size attribute to change a button’s size.
Pill
Use the pill attribute to give buttons rounded edges.
Link Button
Set the href attribute to render the button as an <a> under the hood. Provides all the browser’s native link behavior (e.g. CMD/CTRL/SHIFT + CLICK) plus the rel, target, and download attributes.
Icon Button
When an icon is the only thing slotted into the label, the button becomes an icon button. Icon buttons work with any appearance or variant.
Give icon-only buttons a label.
With no text to announce, a screen reader has nothing to read. Add label to the icon (<cs-icon name="home" label="Home">) so the button has an accessible name.
Icon Button With a Badge
To show a badge on an icon button, such as an unread count, put the badge in the end slot. The button pins a badge to its top corner from any slot, but only the default slot decides whether it is an icon button: a badge there counts as content beside the icon, so the button loses its square icon-button shape. The start slot keeps the shape too, but its spacing pushes the badge in from the corner.
A bare number does not say what it counts, so put the count and what it counts in the icon’s label, and add aria-hidden="true" to the badge so it is not read twice. Update both when the count changes.
This pattern does not announce a new count. To announce one, follow Badge’s Accessibility Considerations.
Start & End Decorations
Use the start and end slots to add presentational elements like <cs-icon> beside the button label.
Stacked
Set orientation="vertical" to stack a button’s content in a column: the start slot above the label, and the end slot and the caret below it. Use it for an icon with a caption, as in a bottom navigation bar or a toolbar with captions.
Only the slots stack, so put the icon in start. An icon beside text in the label stays in the row. Don’t put anything in end but a badge, which pins to the button’s top corner. Anything else lands under the label, and the button logs a console warning, unless a caret hides it. An icon-only button ignores orientation and, outside a group, keeps its square shape.
A stacked button is never shorter or narrower than a one-row button, and it grows to fit its content. Its label wraps instead of spilling out, so the button still fits a narrow bar when text is zoomed or spaced out.
To tune a stacked button’s spacing, set --cs-button-stacked-gap for the space between the icon, the label and anything below it, and --cs-button-stacked-padding-block and --cs-button-stacked-padding-inline for its padding. Set them on a section, such as a bar, and every stacked button inside follows them.
Leave the start icon’s label off. The icon is decorative, so the button is named by its text alone. Give the icon a label only when it says something the text does not, and know that the button’s name will then read the icon’s label first.
Buttons in a horizontal button group share one height, so a stacked toolbar can end with a one-row or icon-only button, which grows taller to match. An icon-only button keeps its width, so it becomes a tall rectangle. Outside a group, such as the navigation bar below, a one-row button keeps its fixed height so it lines up with form fields. It won’t match the stacked buttons beside it, so keep every item in such a bar stacked. A pill stacked button is drawn as a capsule, since pill rounds every corner fully.
Navigation Bar
A bar of stacked items that changes the page is navigation, not tabs. Use cs-button links (href) inside a <nav> with an aria-label, and don’t give them tab roles. Keep at least 4px between items, which is how far the focus ring reaches, or join them in a button group.
The bar cuts the side padding to 4px with --cs-button-stacked-padding-inline. On a narrow screen the default padding breaks every label mid-word, and 4px keeps short labels such as “Home” on one line.
- Leave room for the focus ring. A container that clips its content, such as one with
overflow: hidden, needs at least 4px of padding inside it, or it cuts the ring off. - Keep focus out from under a fixed bar. A bar fixed to the bottom of the screen covers whatever scrolls beneath it. Set
scroll-padding-block-endon the scrolling element to the bar’s height, so a focused control is never hidden behind it. - Render one navigation the same way twice. If the same navigation shows as a side rail on wide screens and a bottom bar on narrow ones, give both the same links in the same order, and add
hiddento the copy that isn’t showing so it leaves the tab order and the accessibility tree. - Mark the current page with more than colour. Changing the current item from
plaintofilledis not enough on its own: the two differ by only 1.25:1 to 1.48:1, and forced colours mode drops the fill altogether. Add a cue that isn’t colour, such as a bar under the item. Settingaria-currenton acs-buttondoes not reach the link inside it.
Caret
Use the with-caret attribute to add a dropdown indicator when a button triggers a dropdown, menu, or popover. The caret takes the place of anything in the end slot. A badge there still shows, pinned to the button’s top corner. Its text joins the button’s accessible name, as on any button. On an icon-only button, follow Icon Button With a Badge.
Loading
Use the loading attribute to put a button in a busy state. Its width stays the same, so adjacent elements don’t shift.
Disabled
Use the disabled attribute to disable a button. It works on link buttons too.
Custom Width
Give a button a custom width to size it independently of its content — useful for making buttons span their container on smaller screens.
Content Alignment
A button centers its content. Set --cs-button-justify-content to place it elsewhere along the row, such as at the start of a full-width button in a menu or sidebar. It takes any justify-content value. Set it on a section and every button inside follows it, including buttons inside other components. Icon-only and stacked buttons ignore it and stay centered.
start keeps the end slot beside the label. To push it to the far end, as a menu row does with a trailing arrow, give the end part an automatic start margin.
Customizing
Target the button part to restyle a button from the outside. Use a custom class when you’re adding a new variation; to retheme an existing one, target its variant attribute instead (e.g. cs-button[variant="brand"]).
Build the override out of design tokens rather than literal values, as below — a hue’s tint scale gives you coordinated light and dark edges for free, and the radius, border width and spacing all have a step on the scale. Tokens are also what keeps a customization working across themes and colour schemes.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick this component, use one of the following snippets.
import '@cruglobal/cornerstone-components/components/button/button.js';
import './cornerstone/components/button/button.js';
import CsButton from '@cruglobal/cornerstone-components/react/button/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
| (default) | The button's label. |
end | An element, such as <cs-icon>, placed after the label. |
start | An element, such as <cs-icon>, placed before the label. |
Attributes & Properties
Learn more about attributes and properties.
| Property | Attribute | Description | Type | Default | Reflects |
|---|---|---|---|---|---|
appearance | appearance | The button's visual appearance. | 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' | 'accent' | Yes |
disabled | disabled | Disables the button. | boolean | false | — |
download | download | Tells the browser to download the linked file as this filename. Only used when href is present. | string | undefined | — | — |
form | — | By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work. | HTMLFormElement | null | — | — |
formAction | formaction | Used to override the form owner's action attribute. | string | — | — |
formEnctype | formenctype | Used to override the form owner's enctype attribute. | 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain' | — | — |
formMethod | formmethod | Used to override the form owner's method attribute. | 'post' | 'get' | — | — |
formNoValidate | formnovalidate | Used to override the form owner's novalidate attribute. | boolean | — | — |
formTarget | formtarget | Used to override the form owner's target attribute. | '_self' | '_blank' | '_parent' | '_top' | string | — | — |
href | href | When set, the underlying button will be rendered as an <a> with this href instead of a <button>. | string | — | Yes |
loading | loading | Draws the button in a loading state. | boolean | false | Yes |
name | name | The name of the button, submitted as a name/value pair with form data, but only when this button is the submitter. This attribute is ignored when href is present. | string | null | null | Yes |
orientation | orientation | Lays the button's content out in a row, or stacks it in a column: start above the label, end and the caret below it. An icon-only button ignores it. When vertical, only a <cs-badge> belongs in end. | 'horizontal' | 'vertical' | 'horizontal' | Yes |
pill | pill | Draws a pill-style button with rounded edges. | boolean | false | Yes |
rel | rel | When using href, this attribute will map to the underlying link's rel attribute. | string | undefined | — | — |
size | size | The button's size. | 'xs' | 's' | 'm' | 'l' | 'xl' | 'm' | Yes |
target | target | Tells the browser where to open the link. Only used when href is present. | '_blank' | '_parent' | '_self' | '_top' | — | — |
type | type | The type of button. Note that the default value is button instead of submit, which is opposite of how native <button> elements behave. When the type is submit, the button will submit the surrounding form. | 'button' | 'submit' | 'reset' | 'button' | — |
validationTarget | — | Override this to change where constraint validation popups are anchored. | undefined | HTMLElement | — | — |
validators | — | Validators are static because they have observedAttributes, essentially attributes to "watch" for changes. Whenever these attributes change, we want to be notified and update the validator. | Validator[] | [] | — |
value | value | The value of the button, submitted as a pair with the button's name as part of the form data, but only when this button is the submitter. This attribute is ignored when href is present. | string | — | Yes |
variant | variant | The button's theme variant. Defaults to neutral if not within another element with a variant. | 'neutral' | 'brand' | 'highlight' | 'information' | 'success' | 'warning' | 'danger' | 'neutral' | Yes |
withCaret | with-caret | Draws the button with a caret. Used to indicate that the button triggers a dropdown menu or similar behavior. The caret hides anything in end except a <cs-badge>. | boolean | false | Yes |
Methods
Learn more about methods.
| Name | Description | Arguments |
|---|---|---|
blur() | Removes focus from the button. | — |
click() | Simulates a click on the button. | — |
focus() | Sets focus on the button. | options: FocusOptions |
formStateRestoreCallback() | Called when the browser is trying to restore element’s state to state in which case reason is "restore", or when the browser is trying to fulfill autofill on behalf of user in which case reason is "autocomplete". In the case of "restore", state is a string, File, or FormData object previously set as the second argument to setFormValue. | state: string | File | FormData | null, reason: 'autocomplete' | 'restore' |
resetValidity() | Reset validity is a way of removing manual custom errors and native validation. | — |
setCustomValidity() | Do not use this when creating a "Validator". This is intended for end users of components. We track manually defined custom errors so we don't clear them on accident in our validators. | message: string |
Events
Learn more about events.
| Name | Description |
|---|---|
blur | Emitted when the button loses focus. |
cs-invalid | Emitted when the form control has been checked for validity and its constraints aren't satisfied. |
focus | Emitted when the button gains focus. |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description | Default |
|---|---|---|
--cs-button-justify-content | Where a one-row button places its content along the row, as a justify-content value. Icon-only and vertical buttons ignore it. | center |
--cs-button-stacked-gap | The space between start, the label, and end or the caret in a stacked button. Applies only to a vertical button that isn't icon-only. | 0.25em |
--cs-button-stacked-padding-block | A stacked button's block padding. Applies only to a vertical button that isn't icon-only. | var(--cs-form-control-padding-block) |
--cs-button-stacked-padding-inline | A stacked button's inline padding. Applies only to a vertical button that isn't icon-only. | var(--cs-form-control-padding-inline) |
Custom States
Learn more about custom states.
| Name | Description | CSS selector |
|---|---|---|
disabled | Applied when the button is disabled. | :state(disabled) |
icon-button | Applied when the button contains only a <cs-icon> with no other content. | :state(icon-button) |
link | Applied when the button is rendered as a link (i.e. href is set). | :state(link) |
loading | Applied when the button is in the loading state. | :state(loading) |
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
button | The component's outer wrapper. | ::part(button) |
caret | The button's caret icon, a <cs-icon> element. | ::part(caret) |
end | The container that wraps the end slot. | ::part(end) |
label | The button's label. | ::part(label) |
spinner | The spinner that shows when the button is in the loading state. | ::part(spinner) |
start | The container that wraps the start slot. | ::part(start) |
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, are included in this list.