Button

Material Design 3 button component for triggering single, immediate actions. Not intended for option selection, navigation containers, or long-form input flows.

Basic Usage

Use the default filled button for the primary action in a view. It is the recommended baseline because it has the strongest emphasis and predictable keyboard behavior.

Click me 
<ds-button>Click me</ds-button>

Variants

Buttons come in six variants to support different levels of emphasis

Filled

High emphasis, primary actions.

  • Use when: There is one clear primary action.
  • Avoid when: Several actions compete for top priority.
Filled Disabled 
<ds-button variant="filled">Filled</ds-button>

Filled Tonal

Medium emphasis, secondary actions.

  • Use when: A supporting action should remain prominent.
  • Avoid when: You need the visual priority of a primary action.
Filled Tonal Disabled 
<ds-button variant="filled-tonal">Filled Tonal</ds-button>

Outlined

Medium emphasis with visible stroke.

  • Use when: Actions should be visible but subordinate to a filled action.
  • Avoid when: The action is destructive or critical and needs stronger emphasis.
Outlined Disabled 
<ds-button variant="outlined">Outlined</ds-button>

Elevated

Elevated appearance with shadow.

  • Use when: You need a button to stand out on busy or tonal surfaces.
  • Avoid when: Flat hierarchy is required for visual calm.
Elevated Disabled 
<ds-button variant="elevated">Elevated</ds-button>

Text

Low emphasis, tertiary actions.

  • Use when: Action should be available but subtle.
  • Avoid when: Users may miss the action in dense layouts.
Text Disabled 
<ds-button variant="text">Text</ds-button>

Danger

Destructive or warning actions.

  • Use when: The action is irreversible, such as delete or reset.
  • Avoid when: The action is neutral and can be represented by a standard variant.
Delete Disabled 
<ds-button variant="danger">Delete</ds-button>

Sizes

Three size options for different contexts

Small Medium Large 
<ds-button size="small">Small</ds-button>
<ds-button size="medium">Medium</ds-button>
<ds-button size="large">Large</ds-button>

Ripple Effect

Add Material Design 3 ripple animation with the ripple attribute

Click Me Click Me Click Me 
<ds-button variant="filled" ripple>Click Me</ds-button>

States

Button behavior changes by state. Disabled and loading states both block activation, while loading additionally communicates progress.

Default Disabled Loading 
<ds-button>Default</ds-button>
<ds-button disabled>Disabled</ds-button>
<ds-button loading>Loading</ds-button>

API

Attributes

Attribute Type Default Description
variant string 'filled' Button style: 'filled', 'filled-tonal', 'outlined', 'elevated', 'text', 'danger'
size string 'medium' Button size: 'small', 'medium', 'large'
disabled boolean false Disables the button and prevents interaction
loading boolean false Shows loading state with spinner
ripple boolean false Enables MD3 ripple animation on click
type string 'button' Button type: 'button', 'submit', 'reset'

Events

Event Detail Description
ds-click { originalEvent: MouseEvent } Fired on activation when not disabled or loading. Bubbles and is composed.
ds-button-content-change {} Fired when light DOM label or slotted content changes. Bubbles and is composed.

Slots

Slot Description
(default) Main button text content
icon-left Icon element before text
icon-right Icon element after text

CSS Custom Properties

Property Description
--md-sys-color-primary Primary color for filled variant
--md-sys-color-secondary-container Background color for filled-tonal variant
--md-sys-shape-corner-full Border radius (default: 100px)

CSS Parts

Part Description
button The internal button element
label The button text container

Accessibility

Keyboard Map

Key Context Expected Result
Tab Button not focused Moves focus to the internal button.
Enter / Space Focused and enabled Activates the button and emits ds-click.
Enter / Space Focused and disabled/loading No activation occurs.

Semantics

  • Uses a native internal <button> element for platform semantics.
  • Disabled state maps to the internal button disabled behavior.
  • Provide accessible labeling when icon-only content is used.

Screen Reader Notes

  • ✅ Announces button label and variant
  • ✅ Announces disabled state
  • ✅ Announces loading state when active
  • ✅ Semantic <button> element

Visual Indicators

  • ✅ Visible focus ring with 2px outline
  • ✅ Meets WCAG 2.2 focus visible requirements
  • ✅ High contrast mode support
  • ✅ Sufficient color contrast ratio (4.5:1 minimum)

Usage Guidelines

  • When to use: Single, immediate actions such as submit, save, continue, or delete.
  • When not to use: Option selection (use chips, radios, or toggles) and persistent navigation (use tabs or nav components).
  • Composition: Pair primary and secondary button variants to establish action hierarchy.
  • Common mistake: Marking multiple actions as filled; keep only one primary per context.