TokenPicker

Select dynamic tokens for template strings

Overview

TokenPicker provides a popover interface for selecting dynamic tokens to insert into template strings. Tokens are displayed grouped by category (user, program, project, etc.) with search filtering. Selected tokens are returned as paths (e.g., "user.name") which can be wrapped in {{}} syntax for template resolution.

Key Features

Grouped token display with collapsible sections
Search filtering across all tokens
Copy-to-clipboard for individual tokens
PII indicator for sensitive fields
Syntax help tooltip in footer
Custom trigger button support

Interactive Examples

Button-Based Token Picker

Template

Click "Token Picker" button to browse and insert tokens.

Inline Autocomplete (type {"{{"})

Template with Autocomplete

Type {{ to trigger autocomplete. Use ↑↓ to navigate, Enter to insert, Esc to close.

Detected Tokens

{{user.name}}{{program.name}}

Interfaces

TokenGroup

Prop	Type	Description
`id`	`string`	Unique identifier for the group
`name`	`string`	Display name for the group header
`icon`	`IconDefinition?`	Optional icon for the group header
`items`	`TokenItem[]`	Array of tokens within this group

TokenItem

Prop	Type	Description
`path`	`string`	Token path (e.g., "user.name")
`label`	`string`	Human-readable label
`category`	`string`	Category for grouping
`description`	`string?`	Optional description text
`isPII`	`boolean?`	Whether this is a PII field (shows warning)

Props Reference

Prop	Type	Default	Description
`groups`	`TokenGroup[]`	`required`	Array of token groups to display
`onSelect`	`(token: string) => void`	`required`	Callback when a token is selected (returns path)
`trigger`	`ReactNode`	`-`	Custom trigger element (defaults to button)
`searchPlaceholder`	`string`	`-`	Override default search placeholder text
`disabled`	`boolean`	`false`	Disable the picker
`className`	`string`	`-`	Additional CSS classes for the trigger
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Popover position relative to trigger
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Popover alignment

Usage

import { TokenPicker, type TokenGroup } from '@/ui/components/token-picker';
import { faUser, faGrid2 } from '@fortawesome/duotone-regular-svg-icons';

// Define token groups
const groups: TokenGroup[] = [
  {
    id: 'user',
    name: 'User',
    icon: faUser,
    items: [
      { path: 'user.name', label: 'Name', category: 'user' },
      { path: 'user.email', label: 'Email', category: 'user', isPII: true },
    ],
  },
  {
    id: 'program',
    name: 'Program',
    icon: faGrid2,
    items: [
      { path: 'program.name', label: 'Program Name', category: 'program' },
    ],
  },
];

// Usage in component
<TokenPicker
  groups={groups}
  onSelect={(path) => {
    // Insert token at cursor: `{{${path}}}`
    insertAtCursor(`{{${path}}}`);
  }}
/>

Prop

Type

Description

id

string

Unique identifier for the group

name

string

Display name for the group header

icon

IconDefinition?

Optional icon for the group header

items

TokenItem[]

Array of tokens within this group

Prop

Type

Description

path

string

Token path (e.g., "user.name")

label

string

Human-readable label

category

string

Category for grouping

description

string?

Optional description text

isPII

boolean?

Whether this is a PII field (shows warning)

Prop

Type

Default

Description

groups

TokenGroup[]

required

Array of token groups to display

onSelect

(token: string) => void

required

Callback when a token is selected (returns path)

trigger

ReactNode

-

Custom trigger element (defaults to button)

searchPlaceholder

string

-

Override default search placeholder text

disabled

boolean

false

Disable the picker

className

string

-

Additional CSS classes for the trigger

side

'top' | 'right' | 'bottom' | 'left'

'bottom'

Popover position relative to trigger

align

'start' | 'center' | 'end'

'start'

Popover alignment

import { TokenPicker, type TokenGroup } from '@/ui/components/token-picker'; import { faUser, faGrid2 } from '@fortawesome/duotone-regular-svg-icons'; // Define token groups const groups: TokenGroup[] = [ { id: 'user', name: 'User', icon: faUser, items: [ { path: 'user.name', label: 'Name', category: 'user' }, { path: 'user.email', label: 'Email', category: 'user', isPII: true }, ], }, { id: 'program', name: 'Program', icon: faGrid2, items: [ { path: 'program.name', label: 'Program Name', category: 'program' }, ], }, ]; // Usage in component <TokenPicker groups={groups} onSelect={(path) => { // Insert token at cursor: `{{${path}}}` insertAtCursor(`{{${path}}}`); }} />