Token
Represents compact selected values and supports choosing multiple values.
On this page
This docs is LLM-friendly and available as clean Markdown.
Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more
Usage
import { GlToken } from "gitlab-ui-react/token";
import { GlTokenSelector } from "gitlab-ui-react/token-selector";<GlToken viewOnly>Documentation</GlToken>Token
Use GlToken to display a compact value. When it is removable, update the parent state through onRemove; otherwise set viewOnly to hide the remove control.
import { useState } from "react";
import { GlToken } from "gitlab-ui-react/token";
const initialTokens = ["documentation", "accessibility", "react"];
export default function TokenExample() {
const [tokens, setTokens] = useState(initialTokens);
return (
<div className="flex flex-wrap gap-3">
{tokens.map((token) => (
<GlToken
key={token}
removeLabel={`Remove ${token}`}
onRemove={() => setTokens((current) => current.filter((item) => item !== token))}>
{token}
</GlToken>
))}
</div>
);
}
Token variants and view-only state
Use search variants to distinguish a filter type from its value. Set viewOnly when a token communicates a value that cannot be removed in the current context.
import { GlToken } from "gitlab-ui-react/token";
export default function TokenVariantsExample() {
return (
<div className="flex flex-wrap gap-3">
<GlToken>Default</GlToken>
<GlToken variant="search-type">Author</GlToken>
<GlToken variant="search-value">Norcleeh</GlToken>
<GlToken viewOnly>View only</GlToken>
</div>
);
}
Token selector
Use GlTokenSelector to choose multiple values from a searchable list. Candidate filtering is controlled by the parent through onInputValueChange, while selected items can be controlled with value and onValueChange.
import { useState } from "react";
import { GlFormField, GlFormFieldLabel } from "gitlab-ui-react/form-field";
import {
GlTokenSelector,
type GlTokenSelectorItem,
} from "gitlab-ui-react/token-selector";
const availableItems: GlTokenSelectorItem[] = [
{ id: "norcleeh", name: "Norcleeh" },
{ id: "nriothrreion", name: "NriotHrreion" },
{ id: "nocpiun", name: "Nocpiun" },
];
export default function TokenSelectorExample() {
const [query, setQuery] = useState("");
const [value, setValue] = useState<GlTokenSelectorItem[]>([availableItems[0]]);
const items = availableItems.filter((item) => (
item.name?.toLocaleLowerCase().includes(query.toLocaleLowerCase())
));
return (
<GlFormField className="max-w-lg">
<GlFormFieldLabel htmlFor="reviewers">Reviewers</GlFormFieldLabel>
<GlTokenSelector
allowClearAll
id="reviewers"
items={items}
onInputValueChange={setQuery}
onValueChange={setValue}
placeholder="Search users"
value={value} />
</GlFormField>
);
}
User-defined tokens
Enable allowUserDefinedTokens when users may add a value that is not present in the available items. Use renderUserDefinedToken to make the create action distinct from existing options.
import { GlFormField, GlFormFieldLabel } from "gitlab-ui-react/form-field";
import { GlTokenSelector } from "gitlab-ui-react/token-selector";
export default function TokenSelectorCustomExample() {
return (
<GlFormField className="max-w-lg">
<GlFormFieldLabel htmlFor="custom-topics">Custom topics</GlFormFieldLabel>
<GlTokenSelector
allowUserDefinedTokens
id="custom-topics"
items={[]}
placeholder="Enter a topic"
renderToken={(item) => <span>{item.name}</span>}
renderUserDefinedToken={(inputValue) => <span>Add “{inputValue}”</span>} />
</GlFormField>
);
}
Accessibility
- Give every token selector a
GlFormFieldLabelconnected byhtmlForandid, or providearia-labeloraria-labelledby. - Keep item names unique and meaningful. Do not rely on token color alone.
- Give standalone token remove buttons a specific
removeLabelwhen several tokens appear together. - The selector supports arrow-key navigation, Enter to select, and Backspace or Delete to move to and remove tokens.
API
GlToken
| Prop | Description | Default |
|---|---|---|
children |
Supplies the token content. | — |
variant |
Sets default, search-type, or search-value styling. |
"default" |
viewOnly |
Hides the remove button. | false |
removeLabel |
Sets the remove button’s accessible name. | "Remove" |
onRemove |
Runs when the remove button is activated. | — |
GlTokenSelector
| Prop | Description | Default |
|---|---|---|
items |
Supplies available items with unique string or number IDs. | [] |
defaultValue |
Sets the initial uncontrolled selected items. | [] |
value |
Controls the selected items. | — |
onValueChange |
Reports the complete selected-item array. | — |
onInputValueChange |
Reports input changes so the parent can filter or fetch items. | — |
allowClearAll |
Shows a button that clears all selected items. | false |
allowUserDefinedTokens |
Allows a non-empty input to become a new token. | false |
showAddNewAlways |
Offers the user-defined option while candidates remain. | false |
loading |
Shows loading content in the dropdown. | false |
hideDropdownWithNoItems |
Hides the dropdown when no candidate is available. | false |
state |
Sets valid (true), invalid (false), or neutral (null) styling. |
null |
viewOnly |
Disables editing and token removal. | false |