Buttons are used for interface actions. They default to appearance that has dark text with gray border. Primary style should be used only once per view for main call-to-action.
Users generally expect buttons to submit data or take action, and for links to navigate. If navigation is required for the button, use the url prop. The control will then output an anchor styled as a button, instead of an HTML button.
| || ||Indicates the id of a related component’s visually focused element.|| || |
| || ||Use this property to add an aria-controls attribute to the button. Use the attribute to point to the unique id of the content that the button manages.|| || |
| || ||Indicates the id of a component that describes the button.|| || |
| || ||If a button expands or collapses adjacent content, then use the ariaExpanded prop to add the aria-expanded attribute to the button. Set the value to convey the current expanded (true) or collapsed (false) state of the content.|| || |
| || ||Adds accessible label for the button that is only shown for screen readers. Typically, this label text replaces the visible text on the button for users who use assistive technology.|| || |
| || ||Adds accessible label for tooltip that is shown in external link (url & external have both been set)|| || |
| ||--||Property to change accessibleLabelExternal defaults on the component. normally you would handle these strings on an application level and override @accessibleLabelExternal when needed|| || |
| || ||Indicates the id of a component owned by the button.|| || |
| || ||Tells screen reader the element is pressed.|| || |
| || ||Custom color to be used for text, as a design token entered in camelCase or kebab-case. Example: "color-primary".|| || |
| || ||Makes the button component disabled. This prevents users from being able to interact with the button, and conveys its inactive state to assistive technologies.|| || |
| || ||Expands the button to fill 100% of the container width.|| || |
| || ||Forces URL to open in a new browser tab. Used together with URL prop.|| || |
| || ||Keep the button fixed width even on mobile viewports.|| || |
| || ||Icon to display to the left of the button content. This is ignored/overridden when button is used as an external link.|| || |
| || ||Whether this button should use styles meant for displaying just an icon.|| || |
| || ||Show icon on the right side of the button content.|| || |
| || ||Icon size.|| || |
| || ||Adds a unique identifier for the button. Please note that with this particular component this id is added inside Shadow DOM. If you need an id on the html element, use regular id attribute instead.|| || |
| || ||[DEPRECATED] this is now handled via the html lang tag, and is no longer used - kept to avoid breaking changes and ease unit testing || || |
| || ||Loading state of the button|| || |
| || ||Controls the margin of the component.|| || |
| || ||The name of the button, which gets paired with the button's value when submitted as part of a form. Corresponds with the native HTML name attribute.|| || |
| || ||Negative variation, can be combined with Variation to produce negative versions|| || |
| || ||Controls the padding of the component.|| || |
| || ||Button’s size.|| || |
| || ||Allows the button to submit a form.|| || |
| || ||Theme of the button.|| || |
| || ||A destination to link to, rendered in the href attribute of a link.|| || |
| || ||The value of the button, which gets paired with the button's name when submitted as part of a form. Corresponds with the native HTML value attribute.|| || |
| || ||Style variation of the button.|| || |
| || ||Controls the text wrapping.|| || |
| ||Emitted when the button loses focus.|| |
| ||Emitted when the button has focus.|| |
setFocus(options?: FocusOptions) => Promise<void> #
Sets focus on the specified
duet-button. Use this method instead of the global
This section includes guidelines for designers and developers about the usage of this component in different contexts.
When to use #
- In general, buttons should be used for all interface actions that aren’t links to other views in the app.
- When you need to provide a call-to-action for the user.
- For form submit, cancel, edit, save and opening a modal.
- Plain buttons, which look similar to links, are used for less commonly used actions such as “view settings.”
When not to use #
- Avoid using buttons as links to other pages. Use Link component instead.
- For navigation where the link often appears within or following a sentence.
This section describes the different component variations, their purpose, and when to use each variation.
| ||Default style is the most common button variation. Only switch to another variation if you need to adjust the visual weight of the element. Please note that the default style uses transparent background so that it works nicely on Duet’s light background gradients.|
| ||Primary style is reserved for the view’s main call-to-action. Should be used only once per view, e.g. for a submit action at the end of a form. This style also works on top of dark background or images.|
| ||Secondary style should be used for secondary actions in a view. Most commonly used when there is already a primary action and we want to highlight another action with a different style.|
| ||Negative style is meant for dark backgrounds and to be used on top of illustrations.|
| ||Destructive style should be used for actions that delete data or otherwise make it hard to revert the action.|
| ||Used for less important or less common actions.|
| ||Used for actions that aren’t currently available or not available anymore.|
| ||Used to indicate progress when a button has been pressed and the action is still processing.|
This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. You can find additional information regarding accessibility of this component below.
- Users of assistive technology expect a button to submit data or do an action. If you need the button to navigate into another view, use the
urlproperty which will then output
<a>tag instead of a
- You can use
accessibleControlsproperty to add an aria-controls attribute to the button. Use the attribute to point to the unique id of the content that the button manages.
accessibleActiveDescendantproperty can be used to indicate the id of a related component’s visually focused element.
accessibleOwnsproperty can be used to indicate the id of a component owned by the button.
accessibleDescribedByproperty can be used to indicate the id of a component which contains descriptive/help text related to the button.
- If a button expands or collapses adjacent content, then use the
ariaExpandedproperty to add the aria-expanded attribute to the button. Set the value to convey the current expanded (true) or collapsed (false) state of the content.
accessibleLabelproperty to create a label for the button that is only shown for screen readers. Typically, this label text replaces the visible text on the button for users who use assistive technology.
accessiblePressedproperty can be used to tell the screen reader that this element is pressed.
- When you need to disable a button, use
disabledproperty as it conveys this information correctly to assistive technologies as well.
- When the button opens a new browser tab, visually hidden text gets automatically added to the button to indicate to screen reader users that a new tab will be opened.
Additional considerations #
Follow these practical tutorials to learn how to build simple page layouts using Duet’s CSS Framework, Web Components and other features:
Using CLI ToolsTutorials
Creating Custom PatternsTutorials
Server Side RenderingTutorials
Usage With MarkdownTutorials
If you experience any issues while using a component, please head over to the Support page for more guidelines and help.