Skip to content

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

TypeScript

feat(templates): add showcase blocks for data and form sub-components (#1743)

Cindy Zhang430ffdf7a838
diff --git a/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemShowcase.doc.mjs
new file mode 100644
index 0000000000..28c5f10392
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'CheckboxListItem',
+ description:
+ 'Checkbox list items with labels, descriptions, and different states including disabled.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CheckboxList', 'CheckboxListItem'],
+};
diff --git a/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemShowcase.tsx b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemShowcase.tsx
new file mode 100644
index 0000000000..eacfca4e57
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemShowcase.tsx
@@ -0,0 +1,38 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';
+
+export default function CheckboxListItemShowcase() {
+ const [value, setValue] = useState<string[]>(['updates', 'security']);
+
+ return (
+ <XDSCheckboxList
+ label="Email preferences"
+ value={value}
+ onChange={setValue}
+ hasDividers>
+ <XDSCheckboxListItem
+ label="Product updates"
+ value="updates"
+ description="New features and improvements"
+ />
+ <XDSCheckboxListItem
+ label="Security alerts"
+ value="security"
+ description="Important account security notifications"
+ />
+ <XDSCheckboxListItem
+ label="Marketing"
+ value="marketing"
+ description="Tips, offers, and promotions"
+ />
+ <XDSCheckboxListItem
+ label="Beta program"
+ value="beta"
+ description="Currently closed to new members"
+ isDisabled
+ />
+ </XDSCheckboxList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.doc.mjs
new file mode 100644
index 0000000000..ed229bda93
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'DropdownMenuItem',
+ description:
+ 'Dropdown menu with custom-rendered items using XDSDropdownMenuItem for icons and descriptions.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['DropdownMenu', 'DropdownMenuItem'],
+};
diff --git a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
new file mode 100644
index 0000000000..45ba3bb6f9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
@@ -0,0 +1,64 @@
+'use client';
+
+import {XDSDropdownMenu, XDSDropdownMenuItem} from '@xds/core/DropdownMenu';
+
+const PencilIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" {...props}>
+ <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
+ <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
+ </svg>
+);
+
+const CopyIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" {...props}>
+ <rect x="9" y="9" width="13" height="13" rx="2" />
+ <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+ </svg>
+);
+
+const ShareIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" {...props}>
+ <circle cx="18" cy="5" r="3" />
+ <circle cx="6" cy="12" r="3" />
+ <circle cx="18" cy="19" r="3" />
+ <line x1="8.59" y1="13.51" x2="15.42" y2="17.49" />
+ <line x1="15.41" y1="6.51" x2="8.59" y2="10.49" />
+ </svg>
+);
+
+const TrashIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" {...props}>
+ <polyline points="3 6 5 6 21 6" />
+ <path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" />
+ </svg>
+);
+
+export default function DropdownMenuItemShowcase() {
+ return (
+ <XDSDropdownMenu button={{label: 'Actions'}} isMenuOpen onOpenChange={() => {}}>
+ <XDSDropdownMenuItem
+ icon={PencilIcon}
+ label="Edit"
+ description="Modify this item"
+ onClick={() => {}}
+ />
+ <XDSDropdownMenuItem
+ icon={CopyIcon}
+ label="Duplicate"
+ description="Create a copy"
+ onClick={() => {}}
+ />
+ <XDSDropdownMenuItem
+ icon={ShareIcon}
+ label="Share"
+ onClick={() => {}}
+ />
+ <XDSDropdownMenuItem
+ icon={TrashIcon}
+ label="Delete"
+ description="This action cannot be undone"
+ onClick={() => {}}
+ />
+ </XDSDropdownMenu>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/FieldLabel/FieldLabelShowcase.doc.mjs b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelShowcase.doc.mjs
new file mode 100644
index 0000000000..48846a61fd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'FieldLabel',
+ description:
+ 'Standalone field labels demonstrating required, optional, tooltip, and icon variations.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Field', 'FieldLabel'],
+};
diff --git a/packages/cli/templates/blocks/components/FieldLabel/FieldLabelShowcase.tsx b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelShowcase.tsx
new file mode 100644
index 0000000000..41442c9c65
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelShowcase.tsx
@@ -0,0 +1,40 @@
+'use client';
+
+import {XDSFieldLabel} from '@xds/core/Field';
+import {XDSVStack} from '@xds/core/Layout';
+
+const LockIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" {...props}>
+ <rect x="3" y="11" width="18" height="11" rx="2" />
+ <path d="M7 11V7a5 5 0 0 1 10 0v4" />
+ </svg>
+);
+
+export default function FieldLabelShowcase() {
+ return (
+ <XDSVStack gap={4}>
+ <XDSFieldLabel
+ label="Email address"
+ inputID="email-input"
+ isRequired
+ />
+ <XDSFieldLabel
+ label="Phone number"
+ inputID="phone-input"
+ isOptional
+ description="Include country code for international numbers"
+ />
+ <XDSFieldLabel
+ label="API key"
+ inputID="api-input"
+ labelTooltip="Your API key can be found in the developer settings"
+ labelIcon={LockIcon}
+ />
+ <XDSFieldLabel
+ label="Disabled field"
+ inputID="disabled-input"
+ isDisabled
+ />
+ </XDSVStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.doc.mjs b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.doc.mjs
new file mode 100644
index 0000000000..85d0a5e789
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'FieldStatus',
+ description:
+ 'Field status messages in error, warning, and success states with attached and detached variants.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Field', 'FieldStatus'],
+};
diff --git a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.tsx b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.tsx
new file mode 100644
index 0000000000..59888b68d9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.tsx
@@ -0,0 +1,26 @@
+'use client';
+
+import {XDSFieldStatusComponent} from '@xds/core/Field';
+import {XDSVStack} from '@xds/core/Layout';
+
+export default function FieldStatusShowcase() {
+ return (
+ <XDSVStack gap={4}>
+ <XDSFieldStatusComponent
+ type="error"
+ message="This field is required"
+ variant="detached"
+ />
+ <XDSFieldStatusComponent
+ type="warning"
+ message="This username is already taken by another team"
+ variant="detached"
+ />
+ <XDSFieldStatusComponent
+ type="success"
+ message="Your changes have been saved"
+ variant="detached"
+ />
+ </XDSVStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/ListItem/ListItemShowcase.doc.mjs
new file mode 100644
index 0000000000..6fe18ecea0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ListItem',
+ description:
+ 'List items with icons, descriptions, and end content slots demonstrating the full ListItem API.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['List', 'ListItem'],
+};
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemShowcase.tsx b/packages/cli/templates/blocks/components/ListItem/ListItemShowcase.tsx
new file mode 100644
index 0000000000..e63f2e0997
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemShowcase.tsx
@@ -0,0 +1,38 @@
+'use client';
+
+import {XDSList, XDSListItem} from '@xds/core/List';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+
+export default function ListItemShowcase() {
+ return (
+ <XDSList header="Settings" hasDividers>
+ <XDSListItem
+ label="Notifications"
+ description="Push, email, and SMS alerts"
+ startContent={<XDSIcon icon="info" />}
+ endContent={<XDSBadge label="3 new" variant="blue" />}
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Privacy"
+ description="Manage data sharing preferences"
+ startContent={<XDSIcon icon="eyeSlash" />}
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Appearance"
+ description="Theme, font size, and display"
+ startContent={<XDSIcon icon="wrench" />}
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Billing"
+ description="Plans and payment methods"
+ startContent={<XDSIcon icon="copy" />}
+ endContent={<XDSBadge label="Pro" variant="purple" />}
+ onClick={() => {}}
+ />
+ </XDSList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemShowcase.doc.mjs
new file mode 100644
index 0000000000..f6be24f97f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'MetadataListItem',
+ description:
+ 'Metadata list items displaying labeled values in various formats including text, badges, and links.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['MetadataList', 'MetadataListItem'],
+};
diff --git a/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemShowcase.tsx b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemShowcase.tsx
new file mode 100644
index 0000000000..bf6bfb6967
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemShowcase.tsx
@@ -0,0 +1,26 @@
+'use client';
+
+import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSLink} from '@xds/core/Link';
+
+export default function MetadataListItemShowcase() {
+ return (
+ <XDSMetadataList title="Project Details">
+ <XDSMetadataListItem label="Name">Design System v2</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">
+ <XDSBadge label="Active" variant="green" />
+ </XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">
+ <XDSLink label="Alice Johnson" href="#">Alice Johnson</XDSLink>
+ </XDSMetadataListItem>
+ <XDSMetadataListItem label="Created">January 15, 2025</XDSMetadataListItem>
+ <XDSMetadataListItem label="Priority">
+ <XDSBadge label="High" variant="red" />
+ </XDSMetadataListItem>
+ <XDSMetadataListItem label="Repository">
+ <XDSLink label="github.com/org/design-system" href="#">github.com/org/design-system</XDSLink>
+ </XDSMetadataListItem>
+ </XDSMetadataList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/RadioListItem/RadioListItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemShowcase.doc.mjs
new file mode 100644
index 0000000000..58384745a2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'RadioListItem',
+ description:
+ 'Radio list items with labels, descriptions, and different states including disabled.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['RadioList', 'RadioListItem'],
+};
diff --git a/packages/cli/templates/blocks/components/RadioListItem/RadioListItemShowcase.tsx b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemShowcase.tsx
new file mode 100644
index 0000000000..7a27a51e88
--- /dev/null
+++ b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemShowcase.tsx
@@ -0,0 +1,34 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';
+
+export default function RadioListItemShowcase() {
+ const [value, setValue] = useState('standard');
+
+ return (
+ <XDSRadioList label="Shipping method" value={value} onChange={setValue}>
+ <XDSRadioListItem
+ label="Standard"
+ value="standard"
+ description="5–7 business days"
+ />
+ <XDSRadioListItem
+ label="Express"
+ value="express"
+ description="2–3 business days"
+ />
+ <XDSRadioListItem
+ label="Overnight"
+ value="overnight"
+ description="Next business day"
+ />
+ <XDSRadioListItem
+ label="Same day"
+ value="sameday"
+ description="Not available in your area"
+ isDisabled
+ />
+ </XDSRadioList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemShowcase.doc.mjs
new file mode 100644
index 0000000000..98f882033c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'SegmentedControlItem',
+ description:
+ 'Segmented control items with text labels and icons, including a disabled item.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['SegmentedControl', 'SegmentedControlItem'],
+};
diff --git a/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemShowcase.tsx b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemShowcase.tsx
new file mode 100644
index 0000000000..c3b985e893
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemShowcase.tsx
@@ -0,0 +1,41 @@
+'use client';
+
+import {useState} from 'react';
+import {
+ XDSSegmentedControl,
+ XDSSegmentedControlItem,
+} from '@xds/core/SegmentedControl';
+import {XDSCenter} from '@xds/core/Center';
+import {XDSIcon} from '@xds/core/Icon';
+
+export default function SegmentedControlItemShowcase() {
+ const [view, setView] = useState('board');
+
+ return (
+ <XDSCenter>
+ <XDSSegmentedControl value={view} onChange={setView} label="View mode">
+ <XDSSegmentedControlItem
+ value="board"
+ label="Board"
+ icon={<XDSIcon icon="viewColumns" />}
+ />
+ <XDSSegmentedControlItem
+ value="list"
+ label="List"
+ icon={<XDSIcon icon="menu" />}
+ />
+ <XDSSegmentedControlItem
+ value="timeline"
+ label="Timeline"
+ icon={<XDSIcon icon="calendar" />}
+ />
+ <XDSSegmentedControlItem
+ value="chart"
+ label="Chart"
+ icon={<XDSIcon icon="arrowsUpDown" />}
+ isDisabled
+ />
+ </XDSSegmentedControl>
+ </XDSCenter>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionShowcase.doc.mjs b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionShowcase.doc.mjs
new file mode 100644
index 0000000000..40bc915c74
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'SelectorOption',
+ description:
+ 'Selector with custom-rendered options using XDSSelectorOption for icons and descriptions.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Selector', 'SelectorOption'],
+};
diff --git a/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionShowcase.tsx b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionShowcase.tsx
new file mode 100644
index 0000000000..7b72b1dcc4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionShowcase.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSSelector, XDSSelectorOption} from '@xds/core/Selector';
+import {XDSCenter} from '@xds/core/Center';
+
+const UserIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" {...props}>
+ <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" />
+ <circle cx="12" cy="7" r="4" />
+ </svg>
+);
+
+const descriptions: Record<string, string> = {
+ admin: 'Full access to all resources',
+ editor: 'Can edit and publish content',
+ viewer: 'Read-only access',
+ billing: 'Manage plans and payments',
+};
+
+const roles = [
+ {value: 'admin', label: 'Admin'},
+ {value: 'editor', label: 'Editor'},
+ {value: 'viewer', label: 'Viewer'},
+ {value: 'billing', label: 'Billing'},
+];
+
+export default function SelectorOptionShowcase() {
+ const [value, setValue] = useState<string | undefined>('editor');
+
+ return (
+ <XDSCenter width={280}>
+ <XDSSelector
+ label="Role"
+ options={roles}
+ value={value}
+ onChange={setValue}
+ placeholder="Assign a role...">
+ {option => (
+ <XDSSelectorOption
+ icon={UserIcon}
+ label={option.label}
+ description={descriptions[option.value]}
+ />
+ )}
+ </XDSSelector>
+ </XDSCenter>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemShowcase.doc.mjs
new file mode 100644
index 0000000000..26598d2b74
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemShowcase.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TypeaheadItem',
+ description:
+ 'Typeahead with custom item rendering using XDSTypeaheadItem for avatars and descriptions.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Typeahead', 'TypeaheadItem'],
+};
diff --git a/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemShowcase.tsx b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemShowcase.tsx
new file mode 100644
index 0000000000..69003c5ca4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemShowcase.tsx
@@ -0,0 +1,48 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTypeahead, XDSTypeaheadItem} from '@xds/core/Typeahead';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSCenter} from '@xds/core/Center';
+
+interface PersonItem extends XDSSearchableItem {
+ auxiliaryData: {role: string};
+}
+
+const people: PersonItem[] = [
+ {id: '1', label: 'Alice Johnson', auxiliaryData: {role: 'Engineer'}},
+ {id: '2', label: 'Bob Smith', auxiliaryData: {role: 'Designer'}},
+ {id: '3', label: 'Charlie Brown', auxiliaryData: {role: 'Product Manager'}},
+ {id: '4', label: 'Diana Prince', auxiliaryData: {role: 'Data Scientist'}},
+ {id: '5', label: 'Eve Davis', auxiliaryData: {role: 'QA Engineer'}},
+];
+
+const peopleSource: XDSSearchSource<PersonItem> = {
+ search: (query: string) =>
+ people.filter(p => p.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => people.slice(0, 4),
+};
+
+export default function TypeaheadItemShowcase() {
+ const [value, setValue] = useState<PersonItem | null>(null);
+
+ return (
+ <XDSCenter width={320}>
+ <XDSTypeahead
+ label="Assignee"
+ placeholder="Search people..."
+ searchSource={peopleSource}
+ value={value}
+ onChange={setValue}
+ renderItem={(item: PersonItem) => (
+ <XDSTypeaheadItem
+ item={item}
+ icon={<XDSAvatar name={item.label} size="small" />}
+ description={item.auxiliaryData.role}
+ />
+ )}
+ />
+ </XDSCenter>
+ );
+}