Token
A token is one value a person has added: a keyword, a recipient, a filter. It is one square high on the fill, with its words 4px in and, when it can be removed, a close button at its end. The product owns the value and decides whether it goes. Tokens usually stand in a Token field, and work alone too.
Design examples
Section titled “Design examples”Removable labels and the native text field share one wrapping line.
<section class="specimen">
<label for="recording-tags">Keywords</label><ds-token-field separators=",;"><ds-token value="rain" label="Rain" remove-label="Remove Rain"></ds-token><ds-token value="courtyard" label="Courtyard" remove-label="Remove Courtyard"></ds-token><input id="recording-tags" placeholder="Add a keyword"></ds-token-field>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> (function mountShowcase(root) {
root.querySelectorAll("[data-showcase-props]").forEach((element) => {
const props = JSON.parse(element.dataset.showcaseProps);
Object.assign(element, props);
if (element.localName === "ds-sidebar") {
let items = props.items;
const render = () => {
let collapsedDepth;
const visible = items.filter((item) => {
const depth = item.depth ?? 0;
if (collapsedDepth !== undefined && depth > collapsedDepth) return false;
collapsedDepth = item.expanded === false ? depth : undefined;
return true;
});
Object.assign(element, { items: visible });
};
element.addEventListener("sidebar-activate", (event) => {
const id = event.detail.id;
items = items.map((item) => ({
...item,
current: item.id === id
}));
render();
});
element.addEventListener("sidebar-toggle", (event) => {
const { id, expanded } = event.detail;
items = items.map((item) => item.id === id ? {
...item,
expanded
} : item);
render();
});
}
});
root.querySelectorAll("ds-token-field").forEach((field) => {
field.addEventListener("ds-token-commit", (event) => {
const { text } = event.detail;
const input = field.querySelector("input");
if (!input || !text.trim()) return;
const token = document.createElement("ds-token");
token.setAttribute("value", text.trim());
token.setAttribute("label", text.trim());
token.setAttribute("remove-label", `Remove ${text.trim()}`);
field.insertBefore(token, input);
input.value = "";
input.dispatchEvent(new Event("input", { bubbles: true }));
});
field.addEventListener("ds-token-remove", (event) => {
const token = event.target;
if (token instanceof Element && token.localName === "ds-token") token.remove();
});
});
window.addEventListener("message", (event) => {
if (event.origin !== location.origin || event.source !== parent || event.data?.type !== "ds1-example-theme") return;
requestAnimationFrame(() => root.querySelectorAll("ds-chart, ds-spark, ds-bars").forEach((chart) => {
chart.refreshTheme?.();
}));
});
})(document); Try it
Section titled “Try it”The close button only asks: the page decides whether a token goes, and nothing is removed in this preview. A token with no remove-label is fixed.
<ds-token value="rain" label="Rain" remove-label="Remove Rain"></ds-token>
<ds-token value="nia" label="Nia Vale" detail="Editor" remove-label="Remove Nia Vale"><ds-avatar slot="leading" initial="N" color="#99ff73"></ds-avatar></ds-token>
<ds-token value="archive" label="Archive"></ds-token>
<ds-token value="draft" label="Draft" remove-label="Remove Draft" disabled></ds-token> <ds-token value="rain" label="Rain" remove-label="Remove Rain"></ds-token><ds-token value="nia" label="Nia Vale" detail="Editor" remove-label="Remove Nia Vale"> <ds-avatar slot="leading" initial="N" color="#99ff73"></ds-avatar></ds-token>Behaviour
Section titled “Behaviour”The close button only asks. Pressing it sends ds-token-remove with the token’s value, and the token stays until the page takes it out. A token with no remove-label has no close button: it is fixed.
label holds the words and detail a second, muted value in small type after them. The default slot adds words of the page’s own after the label. Words that do not fit fade over their last square, never an ellipsis, in both the label and the detail.
disabled disables the close button and stops requestRemove(). A disabled fieldset around the token does the same, and so does a disabled Token field. A token takes part in a form only to follow that state: it sends no value with the form.
Accessibility
Section titled “Accessibility”remove-label is the close button’s accessible name, so write the value into it: “Remove Rain”, not “Remove”. The button is a native button, reached with Tab. Put a picture in leading only where it adds to the words: the token’s name comes from label.
| Attribute | Type | Default | What it does |
|---|---|---|---|
value | string | Empty | The value ds-token-remove reports. |
label | string | Empty | The words shown. |
detail | string | Empty | A second value in small, muted type. |
remove-label | string | Empty | Names the close button and shows it. |
disabled | boolean | false | Disables the close button. |
| Slot | What it holds |
|---|---|
| Default | Words after the label. |
leading | A picture at the start, such as an Avatar. |
| Part | What it is |
|---|---|
frame | The token’s face. |
| Event | Detail | What it means |
|---|---|---|
ds-token-remove | value | Someone asked to remove the token. It bubbles, crosses shadow roots and can be cancelled. |
requestRemove() sends the same request from a script, unless the token is disabled. blocked is true while the token is disabled by itself, its field or a fieldset.
It has no design tokens of its own: its fill is --ds-fill and its corners --ds-radius.
Copy token through Sync 1. On Apple platforms it is DS1Token.
Token field · Tag · Avatar