The command component provides an accessible dropdown menu for presenting users with a list of actionable commands or selectable options. It combines the functionality of a popup with structured menu items and groups, making it ideal for command palettes, context menus, and option selectors.
✅ Use command components when:
- Creating command palettes or quick action menus
- Presenting contextual actions for specific items
- Building dropdown menus with grouped options
- Implementing selectable option lists with categories
❌ Don't use command components for:
- Simple navigation menus (use navigation components)
- Form input selection (use select or combobox)
- Primary page actions (use buttons directly)
- Toggle switches or binary choices
A simple command dropdown with multiple action items. The component provides built-in keyboard navigation and accessibility features.
Organize related commands into logical groups for better user experience and visual hierarchy.
Command items can be made selectable to show the current selection state with visual indicators.
Use exclusive groups when only one option should be selected at a time, similar to radio button behavior.
For mobile interfaces or special contexts, commands can take the full width of the screen.
Commands can use any element as a trigger, not just buttons.
Implement context menus for table rows or content items.
Provide bulk operations for selected items in lists or tables.
- Full keyboard navigation with Arrow keys, Home, End, Enter, and Escape
- Screen reader support with proper ARIA roles and live announcements
- Focus management with roving tabindex pattern
- Selection announcements with position and total count
- Arrow Down/Up: Navigate through command items
- Home/End: Jump to first/last item
- Enter/Space: Activate the focused command item
- Escape: Close the command menu
- Tab: Move focus to/from the trigger element
The component automatically provides:
role="menu"for the command containerrole="menuitem"for each command itemaria-selectedstates for selectable itemsaria-expandedon the trigger element- Live region announcements for navigation
The command component is built on top of the popup component, inheriting all its positioning and interaction capabilities while adding specialized menu behavior and accessibility features.
import { DapDSCommand } from 'dap-design-system'
import { DapDSCommandReact } from 'dap-design-system/react'
For optimal bundle sizes, use the tree-shakeable import syntax:
import { DapDSCommand } from 'dap-design-system/components'
| Property | Type | Default | Description |
|---|---|---|---|
value | string, null | null | The value of the command. |
fullWidth | boolean | false | Whether the command popup should take full width of the screen. |
ariaLabelledBy | string, undefined | ID of element that labels the command dropdown. | |
placement | 'top', 'right' , 'bottom' , 'left' , 'top-start' , 'top-end' , 'bottom-start' , 'bottom-end' , 'left-start' , 'left-end' , 'right-start' , 'right-end' | 'bottom-start' | The placement of the popup. |
overflow | boolean | true | Whether the popup should overflow. |
size | 'xs', 'sm' , 'lg' | The size of the popup. | |
disabled | boolean | The disabled state of the popup. | |
opened | boolean | The open state of the popup. | |
floatingStrategy | 'absolute', 'fixed' | The floating strategy of the popup. | |
offset | number | The offset of the popup. | |
sync | boolean | Whether the popup should sync its width with the trigger. | |
maxHeight | number, 'auto' | The maximum height of the popup. | |
maxWidth | number, 'auto' | The maximum width of the popup. | |
hasArrow | boolean | Whether the popup has an arrow. |
| Name | Description |
|---|---|
trigger | The trigger element for the command dropdown. |
(default) | The command items. |
| Event Name | Description | Type |
|---|---|---|
dds-change | Fired when the command value changes. | {value: string } |
dds-opened | Fired when the popup is opened. | {void } |
dds-closed | Fired when the popup is closed. | {void } |
dds-close | Fired when the popup should be closed. | {void } |
| Part Name | Description |
|---|---|
popup | The main popup container. |
arrow | The arrow of the popup. |
You can style CSS parts using the ::part() pseudo-element selector:
/* Target a specific part */
.my-custom-dap-ds-command::part(popup) {
/* Your custom styles */
}
/* Target multiple parts */
.my-custom-dap-ds-command::part(popup),
.my-custom-dap-ds-command::part(arrow) {
/* Shared styles */
}
Example usage:
<dap-ds-command class="my-custom-dap-ds-command">
Command
</dap-ds-command>
.my-custom-dap-ds-command::part(popup) {
border-radius: 12px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.
| Property Name | Description |
|---|---|
--dds-popup-z-index | Z-index of the popup (default: var(--dds-z-index-20)) |
--dds-popup-padding | Default padding of the popup (default: var(--dds-spacing-400)) |
--dds-popup-padding-xs | Padding of the popup when size is xs (default: var(--dds-spacing-200)) |
--dds-popup-padding-lg | Padding of the popup when size is lg (default: var(--dds-spacing-500)) |
--dds-popup-border-width | Border width of the popup (default: var(--dds-border-width-base)) |
--dds-popup-border-radius | Border radius of the popup (default: var(--dds-radius-base)) |
--dds-popup-border-color | Border color of the popup (default: var(--dds-border-neutral-subtle)) |
--dds-popup-background | Background color of the popup (default: var(--dds-background-neutral-base)) |
--dds-popup-color | Text color of the popup (default: var(--dds-text-neutral-base)) |
--dds-popup-arrow-size | Size of the popup arrow (default: var(--dds-tooltip-arrow-size)) |
CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:
Method 1: Inline styles (Quick customization)
<dap-ds-command
style="--dds-popup-z-index: value; --dds-popup-padding: value;">
Command
</dap-ds-command>
Method 2: CSS classes (Reusable styles)
.my-custom-dap-ds-command {
--dds-popup-z-index: value;
--dds-popup-padding: value;
--dds-popup-padding-xs: value;
}
<dap-ds-command class="my-custom-dap-ds-command">
Command
</dap-ds-command>
Method 3: Global theme customization
/* Apply to all instances */
dap-ds-command {
--dds-popup-z-index: value;
--dds-popup-padding: value;
}
CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.
| Property | Type | Default | Description |
|---|---|---|---|
label | string, undefined | The label of the command group. | |
exclusive | boolean | false | Whether the command group is exclusive, only one item can be selected at a time. |
| Name | Description |
|---|---|
(default) | The default slot for the command group. |
No custom events available.
| Part Name | Description |
|---|---|
base | The base part of the command group. |
label | The label part of the command group. |
items | The items part of the command group. |
| Property Name | Description |
|---|---|
--dds-command-group-gap | The gap between command group elements. (default: var(--dds-spacing-100)) |
--dds-command-group-margin-bottom | The bottom margin of the command group. (default: var(--dds-spacing-200)) |
--dds-command-group-border-radius | The border radius of the command group. (default: var(--dds-radius-small)) |
--dds-command-group-label-font-weight | The font weight of the command group label. (default: var(--dds-font-weight-bold)) |
--dds-command-group-items-gap | The gap between command items. (default: var(--dds-spacing-100)) |
| Property | Type | Default | Description |
|---|---|---|---|
value | string, undefined | The value of the command item. | |
disabled | boolean | false | Whether the command item is disabled. |
name | string | The name of the button | |
href | string | The Href of the button. If this present the button will be rendered as an anchor <a></a> element. | |
target | '_blank', '_self' , '_parent' , '_top' | '_self' | The target of the button |
rel | string | 'noreferrer noopener' | The rel of the button link. Default is noreferrer noopener. |
selectable | boolean | false | Whether the command item is selectable. |
selected | boolean | false | Whether the command item is selected. |
closeOnSelect | string | 'true' | Whether the command item should close the command when selected. |
| Name | Description |
|---|---|
(default) | The label of the command item. |
check | The check of the command item. |
| Event Name | Description | Type |
|---|---|---|
dds-command-item-click | Fired when the command item is clicked. | {value: string, closeOnSelect: boolean } |
| Part Name | Description |
|---|---|
base | The base part of the command item. |
content | The content part of the command item. |
label | The label part of the command item. |
| Property Name | Description |
|---|---|
--dds-command-item-padding | The padding of the command item (default: var(--dds-spacing-100) var(--dds-spacing-200)) |
--dds-command-item-background | The background color of the command item (default: none) |
--dds-command-item-color | The text color of the command item (default: var(--dds-text-primary-base)) |
--dds-command-item-hover-background | The background color of the command item on hover (default: var(--dds-transparent-black-subtle)) |
--dds-command-item-selected-background | The background color of the selected command item (default: var(--dds-transparent-black-subtle)) |
