Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.
Button
Used to trigger an in-page action such as submitting a form or showing/hiding an interface component.
styleKeys: button
Use Button...
- To trigger an in-page action such as submitting a form or showing/hiding an interface component.
Don't use Button...
- To link to another page. Use Link instead, or render the Button as a link.
Skin
Use skin to choose a style of button based on the use case. Refer to guidelines on which skin to use.
Size
size is deprecated in SWAN v3.3
The component now automatically handles sizing based on the selected mode(standardMode/compactMode). Please update your implementation to rely on the new mode-based sizing.
Use size="mini" to reduce the size of a Button.
Width
Use width="full-width" to grow a Button to fill its container.
Disabled
Use disabled when a Button’s action is unavailable. Refer to guidelines.
Use the attribute aria-disabled="true" if the HTML tag does not support the disabled attribute. Notably this applies to span.
Icons
An Icon can be placed inside Buttons. Use buttonShape="round" for icon only buttons. Use objectFit to accommodate different sized custom icons.
If the Button has no text you must include accessible text via aria-label on Button or with an alt attribute on Icon.
Spinner
A Spinner can be placed inside a disabled Button to show that an action is still in progress. Use a size tiny Spinner for this.
You can also set the Spinner position by adding the iconPosition prop on the Button.
Design Path
Use specialVariant="design-path" for Buttons in the design path flow that require a second line for a description.
Clear Selection
Use skin="clear-selection" for Buttons that show user selections.
These Buttons require visually hidden text inside them which must be localized, to make it clear to assistive technologies what the action of clicking on the button will do.
Button as a Link
Use render for Buttons with the behavior of a Link. Refer to render prop guidelines.
Buttons that take users to a new page should render an <a> instead of a <button> for accessibility requirements.
Link as a Button
Use render for Links with the behavior of a Button. Refer to render prop guidelines.
Links that perform an action on the current page should render a <button> instead of an <a> for accessibility requirements.
Unstyled
Use skin="unstyled" for Buttons with no styling.
This variant provides no affordance on touch devices and little affordance on desktops, so should only be used to wrap a component that provides its own affordance.
Buttons in Banner
When used inside Banner, Buttons have a different styling to make them more neutral. This allows them to sit on a wide range of colors often used as Banner backgrounds without clashing.
Skin
- Use
secondaryfor all Buttons by default. Multiple secondary actions can be displayed on a page. - Use
primaryfor the main action of the page.- Limit to a single
primaryButton per page if possible to guide users through the purchasing flow and help them easily get to the cart. - Multiple primary buttons can be used for upsell (adding extra items to checkout).
- Limit to a single
- Use
tertiarywhen a more subtle Button is required.
Content
- Use clear, concise labels to describe the action being performed by the Button.
- Use sentence case.
- Do not use punctuation.
- Buttons will grow wide enough to accommodate their content. If there is not enough room for the Button to grow, the text will wrap to the next line.
Placement
- Place Buttons in flow near relevant content, with negative space to call the maximum amount of attention to the action.
- Align Buttons accordingly with the content grouping for visual consistency. For example, left-aligned typography includes a left-aligned Button.
Disabled
- Disabling Buttons can confuse users since they afford little feedback. Users may not understand why the Button can’t be clicked, and be blocked progressing through the flow. It is often better to allow a Button to be clicked, then communicate to the user what is blocking them from progressing.
Button vs Link
- Use Buttons to perform an action on the current page. Use links to take users to a new page.
- Buttons can be styled to appear as a link. Links can be styled to appear as a Button.
Accessibility
- Ensure Buttons have appropriate contrast when placed on busy backgrounds.
Props
Button
This component is implemented using the
<button /> as the root element. You can utilize the native attributes supported by <button /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.See core props for additional props that can be applied to this component.
| prop | type | required | description | default |
|---|---|---|---|---|
| width | "standard" | "full-width" | "wide" | null | false | The width variation | null |
| size | "standard" | "mini" | null | false | ⚠️ Deprecated - This is deprecated without a replacement.
The size variation | null |
| skin | "link" | "primary" | "secondary" | "unstyled" | "tertiary" | "clear-selection" | null | false | The visual style of the Button | secondary |
| specialVariant | "standard" | "design-path" | null | false | Variations for special cases | standard |
| iconPosition | "left" | "right" | null | false | The position of the icon in the Button | null |
| buttonShape | "standard" | "round" | null | false | The shape of the Button | standard |
ButtonDescription
This component is implemented using the
<span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.See core props for additional props that can be applied to this component.
ClearSelectionButtons
This component is implemented using the
<div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.See core props for additional props that can be applied to this component.
ClearAllButton
This component is implemented using the
<button /> as the root element. You can utilize the native attributes supported by <button /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.See core props for additional props that can be applied to this component.
Related
How does Button meet your needs?
