Preview

Usage

<cs-button variant="primary">Save</cs-button>
<cs-button variant="normal" icon-name="download">Download</cs-button>
<cs-button variant="link" href="/help">Learn more</cs-button>
<cs-button variant="icon" icon-name="close" aria-label="Close"></cs-button>
<cs-button disabled>Disabled</cs-button>
<cs-button loading loading-text="Saving...">Save</cs-button>

Properties

aria-controlsstring default: null

Adds aria-controls to the button. Use when the button controls the contents or presence of an element.

aria-describedbystring default: null

Adds aria-describedby to the button.

aria-expandedboolean default: null

Adds aria-expanded to the button element. Use when the button controls an expandable element.

aria-haspopupboolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog'

Adds aria-haspopup to the button element. Use when the button triggers a popup element such as a menu, listbox, tree, grid, or dialog.

aria-labelstring default: null

Adds aria-label to the button element. Use this to provide an accessible name for buttons that don't have visible text, and to distinguish between multiple buttons with identical visible text. The text will also be added to the title attribute of the button.

disabledboolean

Renders the button as disabled and prevents clicks.

disabled-reasonstring default: ''

Provides a reason why the button is disabled (only when disabled is true). If provided, the button becomes focusable. Applicable for all button variants, except link.

downloadboolean | string

Specifies whether the linked URL, when selected, will prompt the user to download instead of navigate. You can specify a string value that will be suggested as the name of the downloaded file. This property only applies when an href is provided.

externalboolean default: false

Adds an external icon after the button label text. If an href is provided, it opens the link in a new tab.

formstring

The id of the

element to associate with the button. The value of this attribute must be the id of a in the same document. Use when a button is not the descendant of a form element, such as when used in a modal.

form-actionButtonProps.FormAction default: 'submit'

The form action that is performed by a button click.

full-widthboolean default: false

Sets the button width to be 100% of the parent container width. Button content is centered.

hrefstring

Applies button styling to a link. Use this property if you need a link styled as a button (variant=link). For example, if you have a 'help' button that links to a documentation page.

i18n-stringsButtonProps.I18nStrings

An object containing all the necessary localized strings required by the component. The object should contain:

• externalIconAriaLabel - (optional) Specifies the aria-label for the external icon when external is set to true.

icon-alignButtonProps.IconAlign default: 'left'

Specifies the alignment of the icon.

icon-altstring

Specifies alternate text for a custom icon. We recommend that you provide this for accessibility. This property is ignored if you use a predefined icon or if you set your custom icon using the iconSvg slot.

icon-nameIconProps.Name

Displays an icon next to the text. You can use the iconAlign property to position the icon.

icon-urlstring

Specifies the URL of a custom icon. Use this property if the icon you want isn't available.

If you set both iconUrl and iconSvg, iconSvg will take precedence.

loadingboolean default: false

Renders the button as being in a loading state. It takes precedence over the disabled if both are set to true. It prevents users from clicking the button, but it can still be focused.

loading-textstring default: ''

Specifies the text that screen reader announces when the button is in a loading state.

relstring

Adds a rel attribute to the link. By default, the component sets the rel attribute to "noopener noreferrer" when target is "_blank". If the rel property is provided, it overrides the default behavior.

targetstring

Specifies where to open the linked URL (for example, to open in a new browser window or tab use _blank). This property only applies when an href is provided.

variantButtonProps.Variant default: 'normal'

Determines the general styling of the button as follows:

• primary for primary buttons.
• normal for secondary buttons.
• link for tertiary buttons.
• icon to display an icon only (no text).
• inline-icon to display an icon-only (no text) button within a text context.
• inline-link to display a tertiary button with no outer padding.

wrap-textboolean default: true

Specifies if the text content wraps. If you set it to false, it prevents the text from wrapping.

Slots

default

Text displayed in the button element.

iconSvg

Specifies the SVG of a custom icon.

Use this property if you want your custom icon to inherit colors dictated by variant or hover states. When this property is set, the component will be decorated with aria-hidden="true". Ensure that the svg element:

• has attribute focusable="false".
• has viewBox="0 0 16 16".

If you set the svg element as the root node of the slot, the component will automatically

• set stroke="currentColor", fill="none", and vertical-align="top".
• set the stroke width based on the size of the icon.
• set the width and height of the SVG element based on the size of the icon.

If you don't want these styles to be automatically set, wrap the svg element into a span. You can still set the stroke to currentColor to inherit the color of the surrounding elements.

If you set both iconUrl and iconSvg, iconSvg will take precedence.

Note: Remember to remove any additional elements (for example: defs) and related CSS classes from SVG files exported from design software. In most cases, they aren't needed, as the svg element inherits styles from the icon component.

Events

clickCustomEvent<ButtonProps.ClickDetail>

Called when the user clicks on the button and the button is not disabled or in loading state.

followCustomEvent<ButtonProps.FollowDetail>

Called when the user clicks on the button with the left mouse button without pressing modifier keys (that is, CTRL, ALT, SHIFT, META), and the button has an href set.