Vastu

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.

Save changes Cancel Learn more Delete project
<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.

Small Medium Large
<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.

Disabled Saving Disabled
<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.

New article
<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.

Subscribe Reset
<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-tokens
import '@firstprateek/vastu-tokens/lekha.css'; // once per page
import '@firstprateek/vastu/button';

API

Attributes and properties

AttributePropertyTypeDefaultDescription
variantvariant'primary' | 'secondary' | 'ghost' | 'danger''primary'Visual emphasis. Use one primary button per view.
sizesize'sm' | 'md' | 'lg''md'Height and text size. Every size meets the 24px WCAG 2.2 target size.
typetype'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.
disableddisabledbooleanfalseDisables the button. It cannot be focused or activated.
loadingloadingbooleanfalseShows a spinner and blocks activation, but keeps the button focusable.
namenamestring''Submitted with the form as name=value when this button submits it.
valuevaluestring''Submitted with name when this button submits the form.
labellabelstring''Accessible name. Required when the button has no text, such as an icon-only button.
commandforcommandforstring''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">.
commandcommandstring''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

EventDescription
clickThe native click event. Not fired while disabled or loading.

Slots

SlotDescription
(default)The button's text. This is its accessible name unless label is set.
startAn icon before the text. Mark decorative icons aria-hidden="true".
endAn icon after the text.

Styling

Components read the brand's tokens. To adjust one component, set its custom properties or style its parts.

Custom propertyTypeDescription
--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.
PartDescription
::part(control)The native button inside.
::part(label)The wrapper around the text.

Accessibility

Role
button
Accessible name
The slotted text, or the label attribute. A button with only an icon must have label.
Note
loading keeps the button focusable, sets aria-disabled and aria-busy, and adds "Loading" to its name.

Keyboard

KeyDoes
EnterActivates the button.
SpaceActivates the button.
TabMoves 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.