The button component is a versatile interactive element that triggers actions when clicked. It can be used to submit forms, navigate to new pages, open dialogs, or trigger any other action that can be handled by JavaScript. Buttons are fundamental building blocks of user interfaces and should be used for actionable items.
✅ Use buttons when:
- Triggering an action (submit, save, delete)
- Opening modals or dialogs
- Performing in-page operations
- Form submissions
❌ Don't use buttons for:
- Navigation between pages (use links instead)
- Toggling states (use toggle buttons or switches)
- Presenting choices (use radio buttons or checkboxes)
Buttons follow a clear visual hierarchy. Primary buttons should be used sparingly for the most important actions, with outline and subtle variants for secondary actions.
Choose button sizes based on the context and importance of the action. Larger buttons draw more attention and are easier to tap on mobile devices.
Icons can enhance button meaning and improve scannability. Use consistent icon placement and ensure sufficient contrast with the button background.
Button states provide important feedback about the current status and available interactions.
When buttons are used for navigation, they render as anchor elements while maintaining button styling and behavior.
The button component supports extensive customization beyond the default variants. This section demonstrates practical styling techniques and advanced customization patterns.
For simple customizations, use CSS custom properties directly on the component:
Create buttons that automatically adapt to different themes:
Use CSS parts for sophisticated styling that goes beyond color changes:
/* Animated border effect */
.animated-border-button::part(base) {
position: relative;
overflow: hidden;
}
.animated-border-button::part(base)::before {
content: '';
position: absolute;
top: 0;
left: -100%;
width: 100%;
height: 100%;
background: linear-gradient(
90deg,
transparent,
rgba(255, 255, 255, 0.2),
transparent
);
transition: left 0.6s ease;
}
.animated-border-button::part(base):hover::before {
left: 100%;
}
/* Gradient background with animation */
.gradient-button::part(base) {
background: linear-gradient(
135deg,
var(--dds-brand-600),
var(--dds-violet-600)
);
background-size: 200% 200%;
animation: gradient-shift 3s ease infinite;
}
@keyframes gradient-shift {
0% { background-position: 0% 50%; }
50% { background-position: 100% 50%; }
100% { background-position: 0% 50%; }
}
/* Elevated shadow effect */
.elevated-button::part(base) {
box-shadow:
0 4px 8px rgba(0, 0, 0, 0.1),
0 2px 4px rgba(0, 0, 0, 0.06);
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}
.elevated-button::part(base):hover {
box-shadow:
0 8px 16px rgba(0, 0, 0, 0.15),
0 4px 8px rgba(0, 0, 0, 0.1);
transform: translateY(-2px);
}
- Icon-only buttons must include
aria-label
for screen readers - Loading states should announce status changes to assistive technology
- Disabled buttons should not be focusable and should convey their state
- Destructive actions should be clearly labeled and may need confirmation
- Space/Enter: Activates the button
- Tab: Moves focus to/from the button
- Disabled buttons: Are skipped in tab order
- Button text is automatically announced
- Loading state shows spinner with hidden text content
- Danger buttons should have clear, descriptive text
import { DapDSButton } from 'dap-design-system/dist/dds'
import { DapDSButtonReact } from 'dap-design-system/dist/react'
Property | Type | Default | Description |
---|---|---|---|
variant | 'primary' , 'outline' , 'subtle' , 'subtle-neutral' , 'subtle-quiet' , 'subtle-quiet-inverted' , 'clean' , 'primary-inverted' , 'outline-inverted' , 'subtle-inverted' , 'clean-inverted' , 'subtle-menu' , 'subtle-menu-item' | 'primary' | The visual style variant of the button |
size | 'lg' , 'md' , 'sm' , 'xs' | 'md' | The size of the button affecting padding and font size |
loading | boolean | false | Whether the button is in loading state, showing a spinner and disabling interaction |
danger | boolean | false | Whether the button represents a destructive action (applies danger styling) |
shape | 'button' , 'circle' | 'button' | The shape of the button - use 'circle' for icon-only buttons |
htmlType | 'button' , 'submit' , 'reset' | 'button' | The HTML type attribute for form interaction |
href | string , undefined | The URL to navigate to. When present, the button renders as an anchor element | |
target | '_blank' , '_self' , '_parent' , '_top' | '_self' | The target attribute for link navigation |
rel | string , undefined | 'noreferrer noopener' | The rel attribute for link security and behavior |
ariaControls | string , undefined | The ID of the element controlled by this button | |
ariaDescribedBy | string , undefined | The ID of the element that describes the button | |
loadingTimeout | number | 0 | Controls loading timeout in milliseconds |
active | boolean | false | Whether the button is active |
Name | Description |
---|---|
(default) | The content of the button. Can contain text, icons, or other elements. |
Event Name | Description | Type |
---|---|---|
dds-loading-timeout | Emitted when the loading timeout is reached | void |
Part Name | Description |
---|---|
base | The main button container. |
high-contrast | The high contrast part of the button. |
content | The content wrapper inside the button. |
Property Name | Description |
---|---|
--dds-button-padding-x | Horizontal padding of the button (default: var(--dds-spacing-300)) |
--dds-button-padding-y | Vertical padding of the button (default: var(--dds-spacing-300)) |
--dds-button-border-radius | Border radius of the button (default: var(--dds-radius-rounded)) |
--dds-button-font-weight | Font weight of the button (default: 700) |
--dds-button-line-height | Line height of the button (default: var(--dds-font-line-height-large)) |
--dds-button-transition | Transition property of the button (default: all 0.2s ease-in-out) |
--dds-button-disabled-opacity | Opacity of disabled button (default: 0.5) |
--dds-button-size-lg | Size of large button (default: var(--dds-spacing-1200)) |
--dds-button-size-md | Size of medium button (default: var(--dds-spacing-1000)) |
--dds-button-size-sm | Size of small button (default: var(--dds-spacing-800)) |
--dds-button-size-xs | Size of extra small button (default: var(--dds-spacing-600)) |
--dds-button-circle-lg | Size of large circle button (default: var(--dds-spacing-1200)) |
--dds-button-circle-md | Size of medium circle button (default: var(--dds-spacing-1000)) |
--dds-button-circle-sm | Size of small circle button (default: var(--dds-spacing-800)) |
--dds-button-circle-xs | Size of extra small circle button (default: var(--dds-spacing-600)) Primary button properties: |
--dds-button-primary-color-bg | Background color of primary button (default: var(--dds-button-primary-background-enabled)) |
--dds-button-primary-color-bg-hover | Background color of primary button on hover (default: var(--dds-button-primary-background-hover)) |
--dds-button-primary-color-bg-active | Background color of primary button when active (default: var(--dds-button-primary-background-pressed)) |
--dds-button-primary-color-bg-disabled | Background color of disabled primary button (default: var(--dds-button-primary-background-disabled)) |
--dds-button-primary-color-text | Text color of primary button (default: var(--dds-button-primary-text-enabled)) |
--dds-button-primary-color-text-disabled | Text color of disabled primary button (default: var(--dds-button-primary-text-disabled)) Primary inverted button properties: |
--dds-button-primary-inverted-color-bg | Background color of primary inverted button (default: var(--dds-button-primary-background-inverted-enabled)) |
--dds-button-primary-inverted-color-bg-hover | Background color of primary inverted button on hover (default: var(--dds-button-primary-background-inverted-hover)) |
--dds-button-primary-inverted-color-bg-active | Background color of primary inverted button when active (default: var(--dds-button-primary-background-inverted-pressed)) |
--dds-button-primary-inverted-color-bg-disabled | Background color of disabled primary inverted button (default: var(--dds-button-primary-background-inverted-disabled)) |
--dds-button-primary-inverted-color-text | Text color of primary inverted button (default: var(--dds-button-primary-text-inverted)) |
--dds-button-primary-inverted-color-text-disabled | Text color of disabled primary inverted button (default: var(--dds-button-primary-text-inverted-disabled)) Outline button properties: |
--dds-button-outline-color-border | Border color of outline button (default: var(--dds-button-outline-border-enabled)) |
--dds-button-outline-color-border-hover | Border color of outline button on hover (default: var(--dds-button-outline-border-hover)) |
--dds-button-outline-color-border-active | Border color of outline button when active (default: var(--dds-button-outline-border-pressed)) |
--dds-button-outline-color-border-disabled | Border color of disabled outline button (default: var(--dds-button-outline-border-disabled)) |
--dds-button-outline-color-text | Text color of outline button (default: var(--dds-button-outline-text-enabled)) |
--dds-button-outline-color-text-hover | Text color of outline button on hover (default: var(--dds-button-outline-text-hover)) |
--dds-button-outline-color-text-active | Text color of outline button when active (default: var(--dds-button-outline-text-pressed)) |
--dds-button-outline-color-text-disabled | Text color of disabled outline button (default: var(--dds-button-outline-text-disabled)) Outline inverted button properties: |
--dds-button-outline-inverted-color-border | Border color of outline inverted button (default: var(--dds-button-outline-border-inverted-enabled)) |
--dds-button-outline-inverted-color-border-hover | Border color of outline inverted button on hover (default: var(--dds-button-outline-border-inverted-hover)) |
--dds-button-outline-inverted-color-border-active | Border color of outline inverted button when active (default: var(--dds-button-outline-border-inverted-pressed)) |
--dds-button-outline-inverted-color-border-disabled | Border color of disabled outline inverted button (default: var(--dds-button-outline-border-inverted-disabled)) |
--dds-button-outline-inverted-color-text | Text color of outline inverted button (default: var(--dds-button-outline-text-inverted-enabled)) |
--dds-button-outline-inverted-color-text-hover | Text color of outline inverted button on hover (default: var(--dds-button-outline-text-inverted-hover)) |
--dds-button-outline-inverted-color-text-active | Text color of outline inverted button when active (default: var(--dds-button-outline-text-inverted-pressed)) |
--dds-button-outline-inverted-color-text-disabled | Text color of disabled outline inverted button (default: var(--dds-button-outline-text-inverted-disabled)) Subtle button properties: |
--dds-button-subtle-color-bg | Background color of subtle button (default: var(--dds-button-subtle-background-enabled)) |
--dds-button-subtle-color-bg-hover | Background color of subtle button on hover (default: var(--dds-button-subtle-background-hover)) |
--dds-button-subtle-color-bg-active | Background color of subtle button when active (default: var(--dds-button-subtle-background-pressed)) |
--dds-button-subtle-color-bg-disabled | Background color of disabled subtle button (default: var(--dds-button-subtle-background-disabled)) |
--dds-button-subtle-color-border | Border color of subtle button (default: var(--dds-button-subtle-border-enabled)) |
--dds-button-subtle-color-border-hover | Border color of subtle button on hover (default: var(--dds-button-subtle-border-hover)) |
--dds-button-subtle-color-border-active | Border color of subtle button when active (default: var(--dds-button-subtle-border-pressed)) |
--dds-button-subtle-color-border-disabled | Border color of disabled subtle button (default: var(--dds-button-subtle-border-disabled)) |
--dds-button-subtle-color-text | Text color of subtle button (default: var(--dds-button-subtle-text-enabled)) |
--dds-button-subtle-color-text-hover | Text color of subtle button on hover (default: var(--dds-button-subtle-text-hover)) |
--dds-button-subtle-color-text-active | Text color of subtle button when active (default: var(--dds-button-subtle-text-pressed)) |
--dds-button-subtle-color-text-disabled | Text color of disabled subtle button (default: var(--dds-button-subtle-text-disabled)) Clean button properties: |
--dds-button-clean-color-text | Text color of clean button (default: var(--dds-text-link-base)) |
--dds-button-clean-color-text-hover | Text color of clean button on hover (default: var(--dds-text-link-hover)) |
--dds-button-clean-color-text-active | Text color of clean button when active (default: var(--dds-text-link-pressed)) |
--dds-button-clean-color-text-disabled | Text color of disabled clean button (default: var(--dds-text-neutral-disabled)) Clean inverted button properties: |
--dds-button-clean-inverted-color-text | Text color of clean inverted button (default: var(--dds-button-primary-text-inverted)) |
--dds-button-clean-inverted-color-text-hover | Text color of clean inverted button on hover (default: var(--dds-button-primary-text-inverted)) |
--dds-button-clean-inverted-color-text-active | Text color of clean inverted button when active (default: var(--dds-button-primary-text-inverted)) |
--dds-button-clean-inverted-color-text-disabled | Text color of disabled clean inverted button (default: var(--dds-text-neutral-disabled)) Danger button properties: |
--dds-button-danger-color-bg | Background color of danger button (default: var(--dds-button-primary-background-destructive-enabled)) |
--dds-button-danger-color-bg-hover | Background color of danger button on hover (default: var(--dds-button-primary-background-destructive-hover)) |
--dds-button-danger-color-bg-active | Background color of danger button when active (default: var(--dds-button-primary-background-destructive-pressed)) |
--dds-button-danger-color-text | Text color of danger button (default: var(--dds-button-primary-text-enabled)) |
--dds-button-danger-outline-color-border | Border color of danger outline button (default: var(--dds-button-outline-border-destructive-enabled)) |
--dds-button-danger-outline-color-border-hover | Border color of danger outline button on hover (default: var(--dds-button-outline-border-destructive-hover)) |
--dds-button-danger-outline-color-border-active | Border color of danger outline button when active (default: var(--dds-button-outline-border-destructive-pressed)) |
--dds-button-danger-outline-color-text | Text color of danger outline button (default: var(--dds-button-outline-text-destructive-enabled)) |
--dds-button-danger-outline-color-text-hover | Text color of danger outline button on hover (default: var(--dds-button-outline-text-destructive-hover)) |
--dds-button-danger-outline-color-text-active | Text color of danger outline button when active (default: var(--dds-button-outline-text-destructive-pressed)) |
--dds-button-danger-subtle-color-bg | Background color of danger subtle button (default: var(--dds-button-subtle-background-destructive-enabled)) |
--dds-button-danger-subtle-color-bg-hover | Background color of danger subtle button on hover (default: var(--dds-button-subtle-background-destructive-hover)) |
--dds-button-danger-subtle-color-bg-active | Background color of danger subtle button when active (default: var(--dds-button-subtle-background-destructive-pressed)) |
--dds-button-danger-subtle-color-text | Text color of danger subtle button (default: var(--dds-button-subtle-text-destructive-enabled)) |
--dds-button-danger-subtle-color-text-hover | Text color of danger subtle button on hover (default: var(--dds-button-subtle-text-destructive-hover)) |
--dds-button-danger-subtle-color-text-active | Text color of danger subtle button when active (default: var(--dds-button-subtle-text-destructive-pressed)) |
--dds-button-danger-clean-color-text | Text color of danger clean button (default: var(--dds-text-negative-subtle)) |
--dds-button-danger-clean-color-text-hover | Text color of danger clean button on hover (default: var(--dds-text-negative-base)) |
--dds-button-danger-clean-color-text-active | Text color of danger clean button when active (default: var(--dds-text-negative-strong)) |