Button <va-button>
Starts an action, or submits or resets the form it is in.
When to use it
- Use it
- For an action on the current page (Save, Delete, Open dialog) or to submit a form.
- Don't use it
- For navigation to another page or URL.
- Use instead
- A link (
<a href>) for navigation.
Examples
Variants
One primary action per view; secondary and ghost for the rest; danger for destructive actions.
<va-button>Save changes</va-button>
<va-button variant="secondary">Cancel</va-button>
<va-button variant="ghost">Learn more</va-button>
<va-button variant="danger">Delete project</va-button>Sizes
Every size meets the WCAG 2.2 target size of 24 by 24 pixels.
<va-button size="sm">Small</va-button>
<va-button size="md">Medium</va-button>
<va-button size="lg">Large</va-button>Disabled and loading
Disabled buttons can't be focused. Loading buttons stay focusable, so the user keeps their place.
<va-button disabled>Disabled</va-button>
<va-button loading>Saving</va-button>
<va-button variant="secondary" disabled>Disabled</va-button>With icons
Decorative icons are aria-hidden. An icon-only button needs label.
<va-button variant="secondary">
<svg slot="start" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"/></svg>
New article
</va-button>
<va-button variant="ghost" label="Close">
<svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6L6 18"/></svg>
</va-button>In a form
type="submit" submits the form with name=value; the default type="button" never submits.
<form>
<va-text-field label="Email" name="email" type="email" value="ada@example.com"></va-text-field>
<va-button type="submit" name="intent" value="subscribe">Subscribe</va-button>
<va-button type="reset" variant="secondary">Reset</va-button>
</form>Install and import
npm install @firstprateek/vastu @firstprateek/vastu-tokensimport '@firstprateek/vastu-tokens/lekha.css'; // once per page
import '@firstprateek/vastu/button';API
Attributes and properties
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
variant | variant | 'primary' | 'secondary' | 'ghost' | 'danger' | 'primary' | Visual emphasis. Use one primary button per view. |
size | size | 'sm' | 'md' | 'lg' | 'md' | Height and text size. Every size meets the 24px WCAG 2.2 target size. |
type | type | 'button' | 'submit' | 'reset' | 'button' | What the button does in a form. Defaults to button, unlike the native <button>,
so a button never submits a form by accident. Set type="submit" to submit. |
disabled | disabled | boolean | false | Disables the button. It cannot be focused or activated. |
loading | loading | boolean | false | Shows a spinner and blocks activation, but keeps the button focusable. |
name | name | string | '' | Submitted with the form as name=value when this button submits it. |
value | value | string | '' | Submitted with name when this button submits the form. |
label | label | string | '' | Accessible name. Required when the button has no text, such as an icon-only button. |
commandfor | commandfor | string | '' | The id of the element this button sends command to, as with the native Invoker Commands API.
For example commandfor="confirm" command="--show" opens <va-dialog id="confirm">. |
command | command | string | '' | The command sent to the commandfor element on click, such as --show or --close. |
| — | form (read-only) | HTMLFormElement | null | — | The form this button belongs to, if any. |
Events
| Event | Description |
|---|---|
click | The native click event. Not fired while disabled or loading. |
Slots
| Slot | Description |
|---|---|
| (default) | The button's text. This is its accessible name unless label is set. |
start | An icon before the text. Mark decorative icons aria-hidden="true". |
end | An icon after the text. |
Styling
Components read the brand's tokens. To adjust one component, set its custom properties or style its parts.
| Custom property | Type | Description |
|---|---|---|
--va-button-bg | <color> | Background colour. |
--va-button-bg-hover | <color> | Background colour on hover. |
--va-button-fg | <color> | Text and icon colour. |
--va-button-border | <color> | Border colour. |
--va-button-radius | <length> | Corner radius. |
--va-button-height | <length> | Minimum height. |
--va-button-padding-inline | <length> | Space before and after the text. |
--va-button-font-size | <length> | Text size. |
| Part | Description |
|---|---|
::part(control) | The native button inside. |
::part(label) | The wrapper around the text. |
Accessibility
- Role
button- Accessible name
- The slotted text, or the
labelattribute. A button with only an icon must havelabel. - Note
loadingkeeps the button focusable, setsaria-disabledandaria-busy, and adds "Loading" to its name.
Keyboard
| Key | Does |
|---|---|
| Enter | Activates the button. |
| Space | Activates the button. |
| Tab | Moves focus to the next control. A disabled button is skipped. |
Every row on this page is checked by contract tests generated from the same manifest, in Chromium, Firefox and WebKit. Read the manifest.