Preview

Usage

<cs-toggle-button>Favorite</cs-toggle-button>
<cs-toggle-button pressed>Pressed</cs-toggle-button>
<cs-toggle-button icon-name="star">Star</cs-toggle-button>

Properties

aria-controlsstring | undefined

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

aria-describedbystring | undefined

Adds aria-describedby to the button.

aria-labelstring | undefined 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.

childrenunknown

Text displayed in the button element.

disabledboolean | undefined default: false

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 only for the normal variant.

externalboolean | undefined

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

i18n-stringsimport("/Users/piwit/GIT/@cumulus-ui/components/src/button/interfaces").ButtonProps.I18nStrings | undefined

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-nameIconProps.Name

Displays an icon next to the text.

icon-svgunknown

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.

icon-urlstring | undefined

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 | undefined

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 | undefined

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

pressedbooleanrequired

Sets the toggle button to pressed state.

pressed-icon-nameIconProps.Name

Displays an icon next to the text in pressed state.

pressed-icon-urlstring

Specifies the URL of a custom icon in pressed state. Use this property if the icon needed for your use case isn't available.

pressedIconSvg will take precedence if you set both pressedIconUrl and pressedIconSvg.

variantToggleButtonProps.Variant default: 'normal'

Determines the general styling of the toggle button as follows:

• normal for secondary buttons.
• icon to display an icon only (no text).

Defaults to normal if not specified.

wrap-textboolean | undefined

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

Slots

pressedIconSvg

Specifies the SVG of a custom icon in pressed state.

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 pressedIconUrl and pressedIconSvg, pressedIconSvg 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

changeCustomEvent<ToggleButtonProps.ChangeDetail>

Called when the user changes their selection. The event detail contains the current value for the pressed property.