Skip to content

x-button.md

Latest commit

 

History

History
995 lines (661 loc) · 15.1 KB

x-button.md

File metadata and controls

995 lines (661 loc) · 15.1 KB

x-button

Accessible, themeable button web component built on Custom Elements V1.

  • Stateless at render time
  • Framework-free
  • Themeable via semantic CSS custom properties
  • Accessible by default through a native internal <button>

Tag

<x-button>Save</x-button>

Purpose

x-button provides a reusable action control for user-triggered operations such as submit, reset, confirm, cancel, toggle, and destructive actions.

It supports:

  • disabled state
  • loading state
  • pressed/toggled state
  • semantic button types
  • visual variants
  • multiple sizes
  • optional leading and trailing icons
  • optional spinner content
  • accessible keyboard and focus behavior

Installation / Registration

import { init } from '@vanelsas/baredom/x-button';
init();

Registration is idempotent — calling init() on an already-registered element is a no-op.

Basic Usage

Default button

<x-button>Save</x-button>

Submit button

<x-button type="submit">Create account</x-button>

Disabled button

<x-button disabled>Unavailable</x-button>

Loading button

<x-button loading label="Saving">
  Saving
  <span slot="spinner" aria-hidden="true"></span>
</x-button>

Pressed / toggle button

<x-button pressed>Bold</x-button>

Icon-only button

<x-button label="Close">
  <svg slot="icon-start" aria-hidden="true" viewBox="0 0 24 24"></svg>
</x-button>

Button with start and end icons

<x-button>
  <svg slot="icon-start" aria-hidden="true" viewBox="0 0 24 24"></svg>
  Next
  <svg slot="icon-end" aria-hidden="true" viewBox="0 0 24 24"></svg>
</x-button>

Public API

Tag name

x-button

Attributes

disabled

Boolean attribute.

When present, the button is disabled and cannot be activated.

<x-button disabled>Disabled</x-button>

Behavior:

  • blocks pointer interaction
  • blocks keyboard activation
  • suppresses press lifecycle events
  • suppresses hover lifecycle events
  • disables the internal native <button>

loading

Boolean attribute.

When present, the button enters a busy/loading state and prevents duplicate activation.

<x-button loading label="Saving">
  Save
  <span slot="spinner" aria-hidden="true"></span>
</x-button>

Behavior:

  • disables the internal native <button>
  • sets aria-busy="true"
  • prevents duplicate activation
  • suppresses interaction lifecycle events
  • allows loading visuals to be shown

pressed

Boolean attribute.

When present, the button is treated as pressed/toggled.

<x-button pressed>Bold</x-button>

Behavior:

  • sets aria-pressed="true"
  • enables pressed styling

When absent:

  • aria-pressed is removed — the button is not treated as a toggle control

type

Enum attribute.

Allowed values:

  • button
  • submit
  • reset

Default:

button

Examples:

<x-button type="button">Open</x-button>
<x-button type="submit">Submit</x-button>
<x-button type="reset">Reset</x-button>

Invalid values normalize to button.

variant

Enum attribute.

Allowed values:

  • primary
  • secondary
  • tertiary
  • ghost
  • danger

Default:

primary

Examples:

<x-button variant="primary">Save</x-button>
<x-button variant="secondary">Cancel</x-button>
<x-button variant="tertiary">Learn more</x-button>
<x-button variant="ghost">More</x-button>
<x-button variant="danger">Delete</x-button>

Invalid values normalize to primary.

size

Enum attribute.

Allowed values:

  • sm
  • md
  • lg

Default:

md

Examples:

<x-button size="sm">Small</x-button>
<x-button size="md">Medium</x-button>
<x-button size="lg">Large</x-button>

Invalid values normalize to md.

label

String attribute.

Used as the accessible name fallback when the default slot does not contain meaningful text.

<x-button label="Close">
  <svg slot="icon-start" aria-hidden="true"></svg>
</x-button>

Behavior:

  • if the default slot has meaningful text, label is not needed for naming
  • if the default slot does not provide meaningful text, label is used as aria-label
  • if neither visible text nor label is present, the component is accessible-name invalid

Properties

These properties reflect boolean attributes.

disabled

Type:

boolean

Reflects:

disabled

Example:

const el = document.querySelector("x-button");
el.disabled = true;

loading

Type:

boolean

Reflects:

loading

Example:

const el = document.querySelector("x-button");
el.loading = true;

pressed

Type:

boolean

Reflects:

pressed

Example:

const el = document.querySelector("x-button");
el.pressed = false;

Slots

Default slot

Used for the button label/content.

<x-button>Save changes</x-button>

icon-start

Optional leading icon slot.

<x-button>
  <svg slot="icon-start" aria-hidden="true"></svg>
  Download
</x-button>

icon-end

Optional trailing icon slot.

<x-button>
  Next
  <svg slot="icon-end" aria-hidden="true"></svg>
</x-button>

spinner

Optional loading indicator slot.

<x-button loading label="Saving">
  Save
  <span slot="spinner" aria-hidden="true"></span>
</x-button>

By default, spinner content is treated as decorative and should usually be marked aria-hidden="true" unless explicitly intended to be announced.

Events

All custom events:

  • bubble
  • are composed
  • are dispatched from the host x-button element

press

Emitted when activation succeeds.

Detail shape:

{ source: "pointer" | "keyboard" | "programmatic" }

Example:

button.addEventListener("press", (event) => {
  console.log(event.detail.source);
});

Notes:

  • not emitted when disabled
  • not emitted when loading

press-start

Emitted when a valid press interaction begins.

Detail shape:

{ source: "pointer" | "keyboard" }

Example:

button.addEventListener("press-start", (event) => {
  console.log(event.detail.source);
});

press-end

Emitted when a valid press interaction ends or is canceled.

Detail shape:

{ source: "pointer" | "keyboard" }

Example:

button.addEventListener("press-end", (event) => {
  console.log(event.detail.source);
});

hover-start

Emitted when an interactive pointer enters the button.

Detail shape:

{}

Example:

button.addEventListener("hover-start", () => {
  console.log("hover start");
});

hover-end

Emitted when an interactive pointer leaves the button.

Detail shape:

{}

Example:

button.addEventListener("hover-end", () => {
  console.log("hover end");
});

focus-visible

Emitted when the internal native button enters visible keyboard focus state.

Detail shape:

{}

Example:

button.addEventListener("focus-visible", () => {
  console.log("keyboard focus visible");
});

Accessibility

x-button uses a native internal <button> inside Shadow DOM.

This gives it:

  • native button semantics
  • native keyboard behavior
  • predictable disabled behavior
  • proper focus participation

Form submission and reset are handled explicitly via ElementInternals — see Form Behavior.

Disabled behavior

When disabled is present:

  • the internal button is disabled
  • the control cannot be focused or activated through normal interaction
  • press and hover lifecycle events are suppressed

Loading behavior

When loading is present:

  • the internal button is disabled
  • aria-busy="true" is applied
  • duplicate activation is blocked

Pressed behavior

When pressed is present:

  • aria-pressed="true" is set

When pressed is absent:

  • aria-pressed is removed (the button is treated as a regular action button, not a toggle)

Accessible name rules

Preferred name sources:

  1. meaningful text in the default slot
  2. label attribute as fallback

Good:

<x-button>Save</x-button>

Good:

<x-button label="Close">
  <svg slot="icon-start" aria-hidden="true"></svg>
</x-button>

Invalid authoring:

<x-button></x-button>

Invalid authoring with only decorative content:

<x-button>
  <svg slot="icon-start" aria-hidden="true"></svg>
</x-button>

Unless label is provided.

Keyboard activation

Because the internal control is a native button, it supports:

  • Enter
  • Space
  • focus via keyboard navigation
  • submit/reset behavior where applicable

Focus indicator

The component includes a visible focus style for keyboard-visible focus.

Spinner accessibility

The spinner region is decorative by default. Authors should avoid allowing spinner visuals to replace the accessible name.

Recommended:

<x-button loading label="Saving">
  Saving
  <span slot="spinner" aria-hidden="true"></span>
</x-button>

Styling

The component is styled via semantic CSS custom properties defined on the host.

You can override these variables from outside the component.

CSS custom properties

Shape and layout

  • --x-button-radius
  • --x-button-gap
  • --x-button-padding-inline
  • --x-button-height-sm
  • --x-button-height-md
  • --x-button-height-lg
  • --x-button-font-size-sm
  • --x-button-font-size-md
  • --x-button-font-size-lg
  • --x-button-font-weight
  • --x-button-icon-size-sm
  • --x-button-icon-size-md
  • --x-button-icon-size-lg
  • --x-button-spinner-size
  • --x-button-spinner-stroke

Colors — primary variant

  • --x-button-bg
  • --x-button-bg-hover
  • --x-button-bg-active
  • --x-button-bg-disabled
  • --x-button-fg
  • --x-button-fg-disabled
  • --x-button-border
  • --x-button-border-hover
  • --x-button-border-active
  • --x-button-focus-ring

Colors — secondary variant

  • --x-button-secondary-bg
  • --x-button-secondary-bg-hover
  • --x-button-secondary-bg-active
  • --x-button-secondary-fg
  • --x-button-secondary-border

Colors — tertiary variant

  • --x-button-tertiary-bg
  • --x-button-tertiary-bg-hover
  • --x-button-tertiary-bg-active
  • --x-button-tertiary-fg

Colors — ghost variant

  • --x-button-ghost-bg
  • --x-button-ghost-bg-hover
  • --x-button-ghost-bg-active
  • --x-button-ghost-fg

Colors — danger variant

  • --x-button-danger-bg
  • --x-button-danger-bg-hover
  • --x-button-danger-bg-active
  • --x-button-danger-fg

Shadows

  • --x-button-shadow
  • --x-button-shadow-hover
  • --x-button-shadow-active

Motion

  • --x-button-transition-duration
  • --x-button-transition-easing

Shadow Parts

The following shadow parts are exposed:

  • button
  • inner
  • label
  • icon-start
  • icon-end
  • spinner
  • spinner-slot
  • spinner-fallback

Example:

x-button::part(button) {
  font-weight: 600;
}

x-button::part(label) {
  letter-spacing: 0.01em;
}

Theming Example

x-button.brand {
  --x-button-bg: #2563eb;
  --x-button-bg-hover: #1d4ed8;
  --x-button-bg-active: #1e40af;
  --x-button-focus-ring: #93c5fd;
}
<x-button class="brand">Continue</x-button>

Light / Dark Theme Behavior

The component provides default theme-aware values using prefers-color-scheme.

Host-level CSS variable overrides take precedence over defaults.

Motion

The component uses minimal CSS-based motion for:

  • hover state
  • press state
  • focus indication
  • loading affordance

It respects:

@media (prefers-reduced-motion: reduce)

In reduced motion environments, transitions are removed.

Form Behavior

x-button sets static formAssociated = true so the browser tracks form association. The internal shadow DOM <button> cannot submit or reset a light DOM form on its own (shadow DOM is a separate tree), so form participation is implemented explicitly in the click handler.

The host element is searched for a form owner using the standard HTML algorithm:

  1. If the form attribute is present, the form with that id is used.
  2. Otherwise, the nearest ancestor <form> is used.
  • type="submit" → calls form.requestSubmit(), which runs constraint validation and fires the submit event
  • type="reset" → calls form.reset()
  • type="button" → no form interaction

type="button"

No form submission.

type="submit"

Submits the nearest ancestor form, running constraint validation.

type="reset"

Resets the nearest ancestor form.

Example:

<form>
  <input type="text" required />
  <x-button type="submit">Submit</x-button>
  <x-button type="reset" variant="secondary">Reset</x-button>
</form>

Normalization Rules

type

Invalid or missing values normalize to:

button

variant

Invalid or missing values normalize to:

primary

size

Invalid or missing values normalize to:

md

Examples:

<x-button type="oops">Save</x-button>
<x-button variant="unknown">Save</x-button>
<x-button size="xl">Save</x-button>

These behave as if written:

<x-button type="button" variant="primary" size="md">Save</x-button>

Demo Example

<x-button id="save-btn" variant="primary">Save</x-button>

<script>
  const btn = document.getElementById("save-btn");

  btn.addEventListener("press", (event) => {
    console.log("press", event.detail);
  });

  btn.addEventListener("press-start", (event) => {
    console.log("press-start", event.detail);
  });

  btn.addEventListener("press-end", (event) => {
    console.log("press-end", event.detail);
  });

  btn.addEventListener("hover-start", () => {
    console.log("hover-start");
  });

  btn.addEventListener("hover-end", () => {
    console.log("hover-end");
  });

  btn.addEventListener("focus-visible", () => {
    console.log("focus-visible");
  });
</script>

Authoring Recommendations

Prefer visible label text

Best:

<x-button>Save</x-button>

Use label for icon-only cases

Best:

<x-button label="Close">
  <svg slot="icon-start" aria-hidden="true"></svg>
</x-button>

Mark decorative icons as hidden

Recommended:

<svg slot="icon-start" aria-hidden="true"></svg>

Keep spinner decorative unless intentional

Recommended:

<span slot="spinner" aria-hidden="true"></span>

Avoid unlabeled controls

Avoid:

<x-button></x-button>

Non-Goals

x-button does not include:

  • framework adapters
  • internal async state management
  • virtual DOM
  • reactive runtime
  • toggle-group coordination
  • icon library integration
  • imperative animation system

Summary

x-button is a platform-native button component that provides:

  • native button semantics
  • accessible interaction
  • boolean reflection for disabled, loading, and pressed
  • normalized enums for type, variant, and size
  • slot-based icon and spinner composition
  • host-variable theming
  • reduced-motion support
  • stable exported metadata through public-api

It is intended to be a simple, robust foundation for action controls in any web application.