> For the complete documentation index, see [llms.txt](https://docs.devlaunchers.org/dl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devlaunchers.org/dl-docs/universal-design-system/universal-design-system/components/uds-components/button.md).

# Button

## Overview

A flexible button component that serves as the primary interactive element for user actions throughout the system. Supports multiple visual styles, states, and configurations to accommodate various use cases from primary actions to secondary controls.

### Usage Guidelines

Use buttons for triggering actions, submitting forms, and navigating between states. Choose the appropriate priority level (primary, secondary, tertiary) based on the action's importance in the user flow. Primary buttons should be used sparingly for the most important action on a page, while secondary and tertiary buttons support less critical actions.

### Component Properties

**status** (enum: default, hover, focus, active):

* Purpose: Controls the interactive state of the button
* Usage: Automatically managed by user interactions (hover, focus, click)
* Context: Provides visual feedback for user interactions

**icon-placement** (enum: right, left, center, none):

* Purpose: Determines the position of the icon relative to the button text
* Usage: Set to "none" for text-only buttons, or specify placement for icon + text combinations
* Context: "center" is typically used for icon-only buttons

**priority** (enum: primary, secondary, tertiary):

* Purpose: Establishes visual hierarchy and importance level
* Usage: Primary for main actions, secondary for supporting actions, tertiary for subtle controls
* Context: Affects color scheme, prominence, and visual weight

**style** (enum: grey, alert, cta):

* Purpose: Applies semantic styling based on button function
* Usage: "grey" for neutral actions, "alert" for destructive actions, "cta" for call-to-action emphasis
* Context: Works in conjunction with priority to determine final appearance

**sub-style** (enum: eclipse, warning, success, error, cosmic, nebula):

* Purpose: Provides additional stylistic variations within the main style categories
* Usage: Use to create visual distinction between buttons of the same style/priority
* Context: Extends the base styling system with thematic variations

**is-disabled** (boolean: false, true):

* Purpose: Controls whether the button is interactive and accessible
* Usage: Set to "true" to prevent user interaction and apply disabled styling
* Context: Disabled buttons should maintain visual hierarchy while clearly indicating unavailability

**size** (enum: base):

* Purpose: Controls button dimensions and spacing
* Usage: Currently only supports "base" size through this property
* Context: Additional sizes available through appearance modes (see Known Issues)

**icon-type** (string: ArrowCircleLeft):

* Purpose: Specifies which icon to display in the button
* Usage: Reference icon names from the design system's icon library
* Context: Must be used in conjunction with appropriate icon-placement setting

**text** (string: "Button Text"):

* Purpose: Sets the button's text content
* Usage: Provide clear, action-oriented text that describes what the button does
* Context: Should be concise and descriptive

### Appearance Modes

Supports the following variable collections:

**theme:** The component adapts between light and dark themes, maintaining appropriate contrast ratios and visual hierarchy across both modes.

**status:** Provides visual feedback for user interactions including default, hover, focus, and active states. Each state offers distinct visual cues while maintaining accessibility standards.

**device:** Responsive behavior adjusts button sizing, spacing, and touch targets across desktop, tablet, and mobile contexts to ensure optimal usability on all devices.

ℹ️ Note: Size variations are currently managed through appearance modes rather than the size property due to component optimizations.

### Nested Components

* **Icon**: Displays when icon-type is specified and icon-placement is not "none"
* **Text Label**: Contains the button's text content with appropriate typography scaling

### ♿ Accessibility Considerations

* **Contrast:** Meets WCAG AA standards in all supported themes and states
* **Keyboard navigation:** Fully keyboard accessible with standard tab order and Enter/Space activation
* **Screen reader support:** Uses semantic button element with proper ARIA attributes for state changes
* **Semantic tags:** Implements native `<button>` element for proper semantic meaning and browser behavior

### 🧠 Developer Notes

Maps to native `<button>` element with comprehensive styling system. Icon integration requires coordination with the design system's icon library. State management handles both controlled and uncontrolled usage patterns.

### Known Issues

* **Size Property Limitation:** The `size` property currently only supports "base" value. Additional button sizes (small, large, etc.) must be controlled through appearance modes rather than the component property due to ongoing component size optimizations.

### Reference Links

* Design specifications available in component library
* Accessibility guidelines follow WCAG 2.1 AA standards
* Icon library reference for available icon-type values


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devlaunchers.org/dl-docs/universal-design-system/universal-design-system/components/uds-components/button.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.