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.
Start & End Decorations
Use the start and end slots to add presentational elements like <cs-icon> beside the button label.
Caret
Use the with-caret attribute to add a dropdown indicator when a button triggers a dropdown, menu, or popover.
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.
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 |
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. | 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. |
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.