Taxonomy Block

Generic Type → Item hierarchy pattern for User Segments, Traits, and more

Overview

A flexible taxonomy system for managing hierarchical Type → Item relationships. Used for User Segments, Project Traits, and any domain requiring categorization with inheritance.

Features

Two-level hierarchy: Types (categories) and Items (entries)
Source tracking: Platform, Program, or Project level
Visual card grids with counts and source indicators
Multi-select interface with grouped organization
Integrated PrettyDesigner support for rich visual customization

Examples

TaxonomySelector

Multi-select interface with type grouping and source indicators

TaxonomyTypeCardGrid

Visual card grid for taxonomy types with source badges and counts

Industry

Business sectors and verticals

4items

Platform

Role

Job functions and responsibilities

3items

Program

Experience

Skill and experience levels

2items

Program

TaxonomyItemCardGrid

Visual card grid for taxonomy items with source project badges

Healthcare

Medical and healthcare industry professionals

42items

Created from Beta Program 2024

Beta Program 2024

Finance

Banking and financial services

28items

Developer

Software engineers and developers

156items

Designer

UX/UI and product designers

34items

Created from Design System v3

Design System v3

Props

TaxonomyTypeSheet / TaxonomyItemSheet

Prop	Type	Default	Description
`open`	`boolean`	`required`	Whether the sheet is open
`onOpenChange`	`(open: boolean) => void`	`required`	Called when open state changes
`type / item`	`TaxonomyType \| TaxonomyItem \| null`	`-`	Entity to edit (null for create mode)
`onSubmit`	`(data) => Promise<{ success: boolean; error?: string }>`	`required`	Form submission handler
`onSuccess`	`() => void`	`-`	Called after successful submission
`entityName`	`string`	`required`	Display name (e.g., "Segment", "Trait")
`i18nNamespace`	`string`	`'taxonomy'`	Override i18n namespace
`showAiContext`	`boolean`	`true`	Show AI context field (item sheet only)

TaxonomyTypeCardGrid / TaxonomyItemCardGrid

Prop	Type	Default	Description
`types / items`	`TaxonomyType[] \| TaxonomyItem[]`	`required`	Array of entities to display
`onTypeClick / onItemClick`	`(entity) => void`	`-`	Called when card is clicked
`onEditClick`	`(entity) => void`	`-`	Called when edit action is clicked
`onDeleteClick`	`(entity) => void`	`-`	Called when delete action is clicked
`entityName`	`string`	`required`	Display name for empty states
`showCounts`	`boolean`	`true`	Show item/assignment counts
`showSource`	`boolean`	`-`	Show Platform/Program badge (types only)
`showSourceProject`	`boolean`	`-`	Show source project badge (items only)
`currentProjectId`	`string`	`-`	Highlight current project items

TaxonomySelector

Prop	Type	Default	Description
`groups`	`TaxonomySelectorGroup[]`	`required`	Taxonomy types with nested items
`selected`	`string[]`	`required`	Array of selected item IDs
`onChange`	`(ids: string[]) => void`	`required`	Called when selection changes
`entityName`	`string`	`required`	Display name for placeholders
`showSourceIndicators`	`boolean`	`-`	Show Platform/Program badges on types
`showProjectBadges`	`boolean`	`-`	Show project source badges on items
`currentProjectId`	`string`	`-`	Highlight current project items
`disabled`	`boolean`	`false`	Disable the selector

Usage

import {
  TaxonomyTypeSheet,
  TaxonomyItemSheet,
  TaxonomyTypeCardGrid,
  TaxonomyItemCardGrid,
  TaxonomySelector,
  type TaxonomyType,
  type TaxonomyItem,
} from '@/ui/blocks';

// Type Management (Level 1)
<TaxonomyTypeCardGrid
  types={segmentTypes}
  onTypeClick={(type) => router.push(`/segments/${type.slug}`)}
  onEditClick={(type) => openEditSheet(type)}
  onDeleteClick={(type) => handleDelete(type)}
  entityName="Segment Type"
  showCounts
  showSource
/>

<TaxonomyTypeSheet
  open={sheetOpen}
  onOpenChange={setSheetOpen}
  type={editingType}
  onSubmit={handleSubmit}
  onSuccess={refreshData}
  entityName="Segment Type"
/>

// Item Management (Level 2)
<TaxonomyItemCardGrid
  items={segments}
  onEditClick={(item) => openEditSheet(item)}
  onDeleteClick={(item) => handleDelete(item)}
  entityName="Segment"
  showCounts
  showSourceProject
  currentProjectId={projectId}
/>

<TaxonomyItemSheet
  open={sheetOpen}
  onOpenChange={setSheetOpen}
  item={editingItem}
  types={segmentTypes}
  defaultTypeId={selectedTypeId}
  onSubmit={handleSubmit}
  onSuccess={refreshData}
  entityName="Segment"
  typeEntityName="Segment Type"
  showAiContext
/>

// Selection UI
<TaxonomySelector
  groups={selectorGroups}
  selected={selectedIds}
  onChange={setSelectedIds}
  entityName="Segment"
  showSourceIndicators
  showProjectBadges
  currentProjectId={projectId}
/>

Prop

Type

Default

Description

open

boolean

required

Whether the sheet is open

onOpenChange

(open: boolean) => void

required

Called when open state changes

type / item

TaxonomyType | TaxonomyItem | null

-

Entity to edit (null for create mode)

onSubmit

(data) => Promise<{ success: boolean; error?: string }>

required

Form submission handler

onSuccess

() => void

-

Called after successful submission

entityName

string

required

Display name (e.g., "Segment", "Trait")

i18nNamespace

string

'taxonomy'

Override i18n namespace

showAiContext

boolean

true

Show AI context field (item sheet only)

Prop

Type

Default

Description

types / items

TaxonomyType[] | TaxonomyItem[]

required

Array of entities to display

onTypeClick / onItemClick

(entity) => void

-

Called when card is clicked

onEditClick

(entity) => void

-

Called when edit action is clicked

onDeleteClick

(entity) => void

-

Called when delete action is clicked

entityName

string

required

Display name for empty states

showCounts

boolean

true

Show item/assignment counts

showSource

boolean

-

Show Platform/Program badge (types only)

showSourceProject

boolean

-

Show source project badge (items only)

currentProjectId

string

-

Highlight current project items

Prop

Type

Default

Description

groups

TaxonomySelectorGroup[]

required

Taxonomy types with nested items

selected

string[]

required

Array of selected item IDs

onChange

(ids: string[]) => void

required

Called when selection changes

entityName

string

required

Display name for placeholders

showSourceIndicators

boolean

-

Show Platform/Program badges on types

showProjectBadges

boolean

-

Show project source badges on items

currentProjectId

string

-

Highlight current project items

disabled

boolean

false

Disable the selector

import { TaxonomyTypeSheet, TaxonomyItemSheet, TaxonomyTypeCardGrid, TaxonomyItemCardGrid, TaxonomySelector, type TaxonomyType, type TaxonomyItem, } from '@/ui/blocks'; // Type Management (Level 1) <TaxonomyTypeCardGrid types={segmentTypes} onTypeClick={(type) => router.push(`/segments/${type.slug}`)} onEditClick={(type) => openEditSheet(type)} onDeleteClick={(type) => handleDelete(type)} entityName="Segment Type" showCounts showSource /> <TaxonomyTypeSheet open={sheetOpen} onOpenChange={setSheetOpen} type={editingType} onSubmit={handleSubmit} onSuccess={refreshData} entityName="Segment Type" /> // Item Management (Level 2) <TaxonomyItemCardGrid items={segments} onEditClick={(item) => openEditSheet(item)} onDeleteClick={(item) => handleDelete(item)} entityName="Segment" showCounts showSourceProject currentProjectId={projectId} /> <TaxonomyItemSheet open={sheetOpen} onOpenChange={setSheetOpen} item={editingItem} types={segmentTypes} defaultTypeId={selectedTypeId} onSubmit={handleSubmit} onSuccess={refreshData} entityName="Segment" typeEntityName="Segment Type" showAiContext /> // Selection UI <TaxonomySelector groups={selectorGroups} selected={selectedIds} onChange={setSelectedIds} entityName="Segment" showSourceIndicators showProjectBadges currentProjectId={projectId} />