Token field
ds-token-field holds a native input, ds-token values and an optional
Select of suggestions. The native input and the choices stay in light DOM, preserving labels, native
forms, validation, refs and combobox ARIA references. DS1 owns layout, chip faces,
field focus, editing gestures and suggestion navigation. Products own candidate
matching, parsing, validation messages and accepted values.
<label for="people">People</label><ds-token-field choose-label="Choose people" separators=",;"> <ds-token value="one" label="First person" remove-label="Remove first person"></ds-token> <input id="people" type="text" autocomplete="off" /> <ds-select slot="suggestions" role="listbox" aria-label="Choose people"> <ds-button control="slotted"><button type="button" role="option">Second person</button></ds-button> </ds-select></ds-token-field>The field assigns stable option IDs, one active descendant and selected state. The Select keeps focus on the input during pointer selection and handles arrows, Enter, Escape, scrolling and viewport placement. Escape closes suggestions before a containing overlay. Home, End and text selection remain native editing keys. Without suggestions, the field leaves the native input role unchanged.
Listen for ds-token-commit with {text, reason} (enter, separator, input,
blur) and ds-token-remove with {value}. These are requests: neither event
changes product data or clears the native input. Empty-field Backspace requests
removal of the last removable token. IME composition and modified editing keys
are ignored. A separators string defaults to comma and semicolon; pasted input
containing a separator requests commit after controlled values settle.
Tokens accept label, optional detail and a leading slot for a shared Avatar.
remove-label supplies the accessible name and enables removal. Omit it for a
fixed token. Disabled fields, read-only inputs and native disabled fieldsets
block editing and removal. Chips and field rows are one square high; the field
wraps tokens on whole rows and follows the containing or independent DS1 scale.
Keep product rules in the commit and remove events. Classes and styles place the
host; do not rebuild its face. Call refresh() after programmatic changes to children.
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);