Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve MultiSelector docs page and block examples (#1593)

Ted McDonald57e157bb2275
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjs
index 258e5b50cf..3e17eb6570 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjs
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'MultiSelector — Column Visibility',
description:
- 'Table column visibility toggle with hidden label, search, select-all, and count display.',
+ 'Column visibility toggle with hidden label, search, select-all, and selection count.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['MultiSelector'],
+ componentsUsed: ['MultiSelector', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsx
index 213e9d5885..9694c8d801 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsx
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsx
@@ -2,6 +2,7 @@
import {useState} from 'react';
import {XDSMultiSelector} from '@xds/core/MultiSelector';
+import {XDSCenter} from '@xds/core/Center';
const allColumns = [
{value: 'name', label: 'Name'},
@@ -21,7 +22,7 @@ export default function MultiSelectorColumnVisibilitySelector() {
'status',
]);
return (
- <div style={{width: 300}}>
+ <XDSCenter width={300}>
<XDSMultiSelector
label="Columns"
isLabelHidden
@@ -33,6 +34,6 @@ export default function MultiSelectorColumnVisibilitySelector() {
triggerDisplay="count"
placeholder="Columns"
/>
- </div>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjs
index 194709067a..ab37fdea7c 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjs
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'MultiSelector — Form Composition',
description:
- 'Two multi-selectors in a form layout with labels, badges, and required/optional states.',
+ 'Two multi-selectors in a form with required/optional states.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['MultiSelector'],
+ componentsUsed: ['MultiSelector', 'Center', 'VStack'],
};
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsx
index 640d1818b8..ae4e64aaa2 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsx
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsx
@@ -2,38 +2,42 @@
import {useState} from 'react';
import {XDSMultiSelector} from '@xds/core/MultiSelector';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSCenter} from '@xds/core/Center';
export default function MultiSelectorForm() {
const [columns, setColumns] = useState<string[]>(['name', 'email']);
const [filters, setFilters] = useState<string[]>([]);
return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>
- <XDSMultiSelector
- label="Visible columns"
- description="Choose which columns to display in the table"
- options={[
- {value: 'name', label: 'Name'},
- {value: 'email', label: 'Email'},
- {value: 'role', label: 'Role'},
- {value: 'status', label: 'Status'},
- {value: 'created', label: 'Created at'},
- ]}
- value={columns}
- onChange={setColumns}
- hasSelectAll
- isRequired
- triggerDisplay="labels"
- />
- <XDSMultiSelector
- label="Status filter"
- description="Filter by status"
- options={['Active', 'Inactive', 'Pending', 'Archived']}
- value={filters}
- onChange={setFilters}
- isOptional
- triggerDisplay="badges"
- placeholder="All statuses"
- />
- </div>
+ <XDSCenter width={300}>
+ <XDSVStack gap={4}>
+ <XDSMultiSelector
+ label="Visible columns"
+ description="Choose which columns to display in the table"
+ options={[
+ {value: 'name', label: 'Name'},
+ {value: 'email', label: 'Email'},
+ {value: 'role', label: 'Role'},
+ {value: 'status', label: 'Status'},
+ {value: 'created', label: 'Created at'},
+ ]}
+ value={columns}
+ onChange={setColumns}
+ hasSelectAll
+ isRequired
+ triggerDisplay="labels"
+ />
+ <XDSMultiSelector
+ label="Status filter"
+ description="Filter by status"
+ options={['Active', 'Inactive', 'Pending', 'Archived']}
+ value={filters}
+ onChange={setFilters}
+ isOptional
+ triggerDisplay="badges"
+ placeholder="All statuses"
+ />
+ </XDSVStack>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjs
index ed2040416d..218c29be2a 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjs
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'MultiSelector — Searchable',
description:
- 'Multi-select with search filtering and select-all for long option lists.',
+ 'Multi-select with search filtering and select-all.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['MultiSelector'],
+ componentsUsed: ['MultiSelector', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsx
index c6c366f3ac..8e8d27f245 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsx
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsx
@@ -2,6 +2,7 @@
import {useState} from 'react';
import {XDSMultiSelector} from '@xds/core/MultiSelector';
+import {XDSCenter} from '@xds/core/Center';
const countries = [
'United States',
@@ -19,7 +20,7 @@ const countries = [
export default function MultiSelectorSearchableMultiSelector() {
const [value, setValue] = useState<string[]>([]);
return (
- <div style={{width: 300}}>
+ <XDSCenter width={300}>
<XDSMultiSelector
label="Countries"
options={countries}
@@ -29,6 +30,6 @@ export default function MultiSelectorSearchableMultiSelector() {
hasSelectAll
placeholder="Select countries..."
/>
- </div>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjs
index 94429299d2..1b2a07fd95 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjs
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'MultiSelector — Sectioned Permissions',
description:
- 'Multi-select with options organized into labeled sections for grouped selection.',
+ 'Multi-select with options grouped into labeled sections.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['MultiSelector'],
+ componentsUsed: ['MultiSelector', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsx
index c404027470..ea02e232d4 100644
--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsx
+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsx
@@ -2,11 +2,12 @@
import {useState} from 'react';
import {XDSMultiSelector} from '@xds/core/MultiSelector';
+import {XDSCenter} from '@xds/core/Center';
export default function MultiSelectorSectionedMultiSelector() {
const [value, setValue] = useState<string[]>([]);
return (
- <div style={{width: 300}}>
+ <XDSCenter width={300}>
<XDSMultiSelector
label="Permissions"
options={[
@@ -32,6 +33,6 @@ export default function MultiSelectorSectionedMultiSelector() {
onChange={setValue}
placeholder="Select permissions..."
/>
- </div>
+ </XDSCenter>
);
}
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 3c017d415b..75fbb39a8b 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -141,12 +141,13 @@ export const docs = {
],
usage: {
description:
- 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',
+ 'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',
bestPractices: [
- { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },
- { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },
- { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },
- { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },
+ { guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },
+ { guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },
+ { guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },
+ { guidance: false, description: 'Use for single-value selection — use Selector instead.' },
+ { guidance: false, description: 'Show more than ~20 options without enabling search.' },
],
},
};
@@ -185,12 +186,13 @@ export const docsZh = {
],
usage: {
description:
- 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',
+ 'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',
bestPractices: [
- { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },
- { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },
- { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },
- { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },
+ { guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },
+ { guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },
+ { guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },
+ { guidance: false, description: 'Use for single-value selection — use Selector instead.' },
+ { guidance: false, description: 'Show more than ~20 options without enabling search.' },
],
},
};
@@ -200,12 +202,13 @@ export const docsDense = {
description: 'checkbox multi-select dropdown for finite sets like column toggles or filter facets',
usage: {
description:
- 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',
+ 'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',
bestPractices: [
- { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },
- { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },
- { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },
- { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },
+ { guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },
+ { guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },
+ { guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },
+ { guidance: false, description: 'Use for single-value selection — use Selector instead.' },
+ { guidance: false, description: 'Show more than ~20 options without enabling search.' },
],
},
components: [