Cycle

A button that advances through a built-in setting or a list of its own.

Design examples

Cycle through print formats

Example Code

A small set of choices beside the label it changes.

Language in a text row

Example Code

The language control occupies the same baseline as its label.

Try it

Cycle through a setting

Example Code

Click to switch light and dark inside this preview.

Available settings

type	Values
theme	Light, dark and system, which follows the system’s appearance as it changes.
shape	Square, rounded and circular: the corners every component draws, remembered and put on the page before it paints (see Shape).
language	The product’s languages, each by its own name: the language picker.
accent-color	The system’s eight accent colours.

The language picker

Choose a language

Example Code

Click to cycle through the configured languages. Each choice is saved automatically.

type="language" is the language picker. It cycles through the languages supplied to configureI18n, each shown by its own name (Dansk, 日本語), sets the language on a press, remembers it and follows it when something else changes it. It is announced as “Language: Dansk”.

import { configureI18n } from './DS1/0-face/i18n';
configureI18n({ languages: ['en', 'da', 'ja'], sharedWords: true });

The language picker is a normal button that fits its language’s name, with the same height, padding and corners as Button. Use primary or secondary for its appearance. The legacy compact and chip attributes remain accepted but no longer change its width:

<ds-cycle type="language"></ds-cycle>
<ds-cycle type="language" secondary></ds-cycle>
<ds-cycle type="language" primary></ds-cycle>

All variants use a native button, follow a disabled fieldset, and announce one language change per activation. disabled prevents changes.

Your own values

Leave out type and give values instead, as a JSON array in the attribute or an array property. The cycle shows each value as its label, starts on value when that is one of them and otherwise on the first, and on each click moves to the next and emits a change event whose detail.value is the new one. Setting value from a script moves the cycle without an event. Nothing is remembered. The Chart page uses one to step through the chart types.

<ds-cycle values='["Line","Area","Bars"]'></ds-cycle>

Name the setting

When the face shows only a value, give the cycle a label: the setting’s name as a translation key. The face still shows the value alone, and the button is announced with the name before it, as “Size: 40”. Without a label the button is named by its face.

<ds-cycle label="Size" values='["20","40","60"]' value="40"></ds-cycle>

Use a label rather than writing the name into every value (“Size 40”). A built-in setting takes one too: <ds-cycle type="theme" label="Theme"> is announced as “Theme: Dark”.

Behaviour

These settings use the shared preferences module. Clicking a theme or accent cycle changes that setting for the document and remembers it in the browser. The preview above contains its own document, so trying a theme does not repaint the surrounding example list.

Set disabled to prevent cycling. Each setting emits the corresponding window event, such as theme-changed, language-changed or accent-color-changed.

Use primary or secondary to choose the shared button face. The older variant attribute remains supported. Language and theme cycles default to secondary; other built-in settings default to primary. Disabled fieldsets also disable a cycle. A language cycle with only one available language does not write or emit a redundant change.

Products retaining existing browser storage names set window.DS_ONE_PREFERENCES before importing these modules. storageKey names the merged preference object and themeStorageKey names the saved light, dark or system choice. Defaults remain ds-one:preferences and ds-one:theme; the language runtime’s storageKey is configured separately through configureI18n.

Languages · Theming · Preferences