Options

Basic usage

There are 3x basic button styles, ds-button, ds-button --primary and ds-button --plain, which can be applied to either <button> or <a> elements.

The primary button should be used once per component to indicate the most important or primary action. For example in a dialog that has two actions ‘Update’ and ‘Cancel’, it’s likely that ‘Update’ is the primary action and therefore should use the primary button style.

Using <a> elements

In addition to standard html buttons, a elements can be presented visually as buttons with the same options. See When to use a button vs a text link

When applying button styles to anchor links <a>, the disabled state is displayed when there is no href attribute, or by adding the class --disabled.

Visual states

All 3x buttons styles (default, primary and plain) adhere to 4x preset visual states - alert, warning, success and info.

Component colors

Icons

Add an additional class such as --icon-online from the available icon modifier list. Alternatively you can use an inline icon.

Icon position

Adding the class --right-icon will show the button on the right of the button.

Inline icons

Alternatively ds-icon can be used inside ds-button if necessary. This can be used when more than one icon is required, or if more control over the icon is required.

Inline icon animation

Using inline icons allows you to use all the icon animation options. To animate the entire button, or animate a button not using inline icons see Animation below.

Inline icon colors

Using inline icons allows applying color to just the icon.

Inline icon size

Using inline icons allows you to vary the size of the icon

Size

xxsmall, xsmall, small, default, large

mid, wide

By default, ds-button will be a minimum of 40px wide. --mid has a minimum width of 80px, and --wide has a minimum width of 160px;

Hiding the label

By default a button shows the label text (the contents inside the span). This can be hidden using the --hide-label option. For accessibility purposes it’s preferable to have a descriptive label hidden using this method, rather than omitting the label text.

Tip Position

By adding the appropriate --tip-* class, the position of the tip can be changed.

Animation

Animation states for buttons should only be used sparingly to indicate temporary states (such as uploading/downloading a file, sending/receiving data or waiting for a server side process to complete).

--spin works with any icon on the available icon modifier list. This option will animate the icon in-place (and requires an existing --icon-* class to exist on the button).

Also see Inline icon animation for examples of other animations that can be applied to an inline icon.

Loading state

A button can be triggered to display a loading state - where the button contents are hidden, and the replaced by a centered spinning loading icon – without affecting the dimensions of the button. Currently there are two loading state icons available, --loading or --loading-refresh. Buttons in the loading state currently have a common look, regardless of the button style.

Notification indicator

A ds-button can be trigger to display a notification indicator (dot) by adding the class --notification. The notification indicator works with all button styles and visual states.

Notification indicators adhere to 4x preset visual states - alert, warning, success and info.

Additionally, if the button has an attribute data-notification-counter set to a non-empty value, that value will be shown in the indicator. If the attribute is set to empty data-notification-counter="" the indicator dot will be hidden.

Text addon inside buttons

ds-text can be used inside ds-button. See ds-text for further examples.

ds-button can also act as an addon to a field, see below.

Buttons inside other components

When ds-button is used inside ds-select, ds-input, or ds-range it will be displayed next to the element and will not wrap when the window is scaled.

Addon button

The --addon styles slightly modify the button to ‘join’ the containing component.

Addon default style

Styles

Custom styles exist for specific use cases. See also the basic buttons styles.

Link style

Buttons can be styled as links.

Label style

Buttons can be styled as labels. A common usage would be in ds-datatable th headers for sorting columns.

Menu style

Feature style

Close style

in-place

--in-place is a shortcut class, often used in a datatable, when a button needs to sit adjacent to text for editing purposes. It is equivilent to ds-button.--xxsmall.--plain.--hide-label.

Tests

ds-tag inside ds-button

<button>

<a>

<ui-button>

Recommendations

Styling of delete buttons

All delete buttons should use the .--alert visual state and --icon-delete icon, with the appropriate buttons style (default, primary or plain).

When to use a button vs a text link

Buttons should be used when performing an action such as confirming or canceling a dialog, submitting a form or triggering a UI component.

Links should be preferred when performing an adjacent task such as navigating to a new page, opening a help document in a new window.

Manifest

The component manifest describes this component's API — its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.

Latest version: https://assets.soracom.io/sds/latest/ds-button/index.mjs