---
title: AI quick reference
description: Comprehensive structured reference for AI tools to quickly understand and use Click UI components
---

Source: https://clickhouse.design/click-ui/ai-quick-reference

# AI quick reference

Structured reference optimized for AI parsing. All components, props, patterns, and examples in one place.

## Package information

**Package**: `@clickhouse/click-ui`\
**Version**: Check current version in component docs\
**Import Pattern**: `import { ComponentName } from '@clickhouse/click-ui'`\
**Provider Required**: All components must be wrapped in `ClickUIProvider`

```tsx
import { ClickUIProvider } from '@clickhouse/click-ui'

function App() {
return (
  <ClickUIProvider theme="dark">
    {/* Your app */}
  </ClickUIProvider>
)
}
```

## Component categories

### Layout components

**Category**: Layout\
**Components**: Container, Grid, GridContainer, Panel, Spacer

### Form components

**Category**: Forms\
**Components**: TextField, TextArea, NumberField, PasswordField, SearchField, Checkbox, RadioGroup, Switch, Select, AutoComplete, DatePicker, DateRangePicker, FileUpload, FileMultiUpload, Label

### Display components

**Category**: Display\
**Components**: Text, Title, Badge, Avatar, BigStat, CodeBlock, ProgressBar, Icon, Logo, Link

### Navigation components

**Category**: Navigation\
**Components**: Tabs, FileTabs, Accordion, MultiAccordion, VerticalStepper, Pagination

### Overlay components

**Category**: Overlays\
**Components**: Dialog, Flyout, Popover, Tooltip, HoverCard, ConfirmationDialog

### Action components

**Category**: Actions\
**Components**: Button, Dropdown, ContextMenu

### Feedback components

**Category**: Feedback\
**Components**: Alert, Toast

### Data display components

**Category**: Data\
**Components**: Table, Cards, DateDetails

## Essential components quick reference

### Container

**Purpose**: Layout wrapper with flexbox/grid capabilities\
**Required Props**: `orientation` ("horizontal" | "vertical")\
**Common Props**: `gap` (spacing token), `padding`, `alignItems`, `justifyContent`

```tsx
import { Container } from '@clickhouse/click-ui'

<Container orientation="vertical" gap="md" padding="lg">
{/* content */}
</Container>
```

### Button

**Purpose**: Clickable action button\
**Required Props**: `label` (string)\
**Common Props**: `type` ("primary" | "secondary" | "empty" | "danger" | "ghost"), `onClick`, `disabled`, `size`

```tsx
import { Button } from '@clickhouse/click-ui'

<Button type="primary" label="Click me" onClick={() => {}} />
```

### TextField

**Purpose**: Text input field\
**Required Props**: `value` (string), `onChange` (function)\
**Common Props**: `placeholder`, `disabled`, `error`, `label`

```tsx
import { TextField } from '@clickhouse/click-ui'
import { useState } from 'react'

function MyForm() {
const [value, setValue] = useState('')
return <TextField value={value} onChange={setValue} placeholder="Enter text" />
}
```

### Table

**Purpose**: Data table with sorting and pagination\
**Required Props**: `headers` (array), `rows` (array)\
**Common Props**: `pageSize`, `onPageChange`, `isSortable`

```tsx
import { Table } from '@clickhouse/click-ui'

const headers = [
{ label: 'Name', isSortable: true },
{ label: 'Email', isSortable: true }
]
const rows = [
{ id: '1', items: [{ label: 'John' }, { label: 'john@example.com' }] },
{ id: '2', items: [{ label: 'Jane' }, { label: 'jane@example.com' }] }
]

<Table headers={headers} rows={rows} />
```

### Dialog

**Purpose**: Modal dialog overlay\
**Required Props**: `open` (boolean), `onOpenChange` (function)\
**Sub-components**: `Dialog.Content`, `Dialog.Trigger`, `Dialog.Close`

```tsx
import { Dialog, Button } from '@clickhouse/click-ui'
import { useState } from 'react'

function MyDialog() {
const [open, setOpen] = useState(false)
return (
  <>
    <Button label="Open" onClick={() => setOpen(true)} />
    <Dialog open={open} onOpenChange={setOpen}>
      <Dialog.Content title="Title" showClose onClose={() => setOpen(false)}>
        Content here
      </Dialog.Content>
    </Dialog>
  </>
)
}
```

### Icon

**Purpose**: Display icon\
**Required Props**: `name` (IconName string)\
**Common Props**: `size` ("xs" | "sm" | "md" | "lg" | "xl" | "xxl"), `color`, `state`

```tsx
import { Icon } from '@clickhouse/click-ui'

<Icon name="check" size="md" state="success" />
```

### Logo

**Purpose**: Display partner/customer logos\
**Required Props**: `name` (LogoName string)\
**Common Props**: `size`, `theme` ("light" | "dark")

```tsx
import { Logo } from '@clickhouse/click-ui'

<Logo name="clickhouse" size="md" theme="light" />
```

## Common patterns

### Form in dialog

**Components**: Dialog, TextField, Label, Container, Button

```tsx
import { Dialog, TextField, Label, Container, Button } from '@clickhouse/click-ui'
import { useState } from 'react'

function FormDialog() {
const [open, setOpen] = useState(false)
const [name, setName] = useState('')

return (
  <>
    <Button label="Add User" onClick={() => setOpen(true)} />
    <Dialog open={open} onOpenChange={setOpen}>
      <Dialog.Content title="Add user" showClose onClose={() => setOpen(false)}>
        <Container orientation="vertical" gap="md">
          <Label htmlFor="name">Name</Label>
          <TextField id="name" value={name} onChange={setName} />
          <Container orientation="horizontal" gap="sm" justifyContent="end">
            <Button label="Cancel" onClick={() => setOpen(false)} />
            <Button type="primary" label="Save" onClick={() => setOpen(false)} />
          </Container>
        </Container>
      </Dialog.Content>
    </Dialog>
  </>
)
}
```

### Table with pagination

**Components**: Table, Pagination, Title, Container

```tsx
import { Table, Pagination, Title, Container } from '@clickhouse/click-ui'
import { useState } from 'react'

function DataTable() {
const [page, setPage] = useState(1)
const headers = [{ label: 'Name', isSortable: true }]
const rows = [{ id: '1', items: [{ label: 'John' }] }]

return (
  <Container orientation="vertical" gap="md">
    <Title size="lg">Users</Title>
    <Table headers={headers} rows={rows} pageSize={10} />
    <Pagination currentPage={page} totalPages={10} onChange={setPage} />
  </Container>
)
}
```

### Search with filters

**Components**: SearchField, Container, Button

```tsx
import { SearchField, Container, Button } from '@clickhouse/click-ui'
import { useState } from 'react'

function SearchFilters() {
const [search, setSearch] = useState('')

return (
  <Container orientation="horizontal" gap="md" alignItems="center">
    <SearchField value={search} onChange={setSearch} placeholder="Search..." />
    <Button label="Filter" onClick={() => {}} />
  </Container>
)
}
```

## Design tokens

### Spacing

**Tokens**: `none`, `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`\
**Usage**: `gap="md"`, `padding="lg"`

### Sizes

**Tokens**: `xs`, `sm`, `md`, `lg`, `xl`, `xxl`\
**Usage**: `size="md"`, `Icon size="lg"`

### Colors

**Theme-aware**: Components automatically adapt to light/dark themes\
**Custom**: Use `color` prop for icons/text (CSS color value or "currentColor")

## Icon names (165 total)

**Common Icons**: `check`, `cross`, `warning`, `info-in-circle`, `arrow-down`, `arrow-up`, `arrow-left`, `arrow-right`, `chevron-down`, `chevron-up`, `chevron-left`, `chevron-right`, `search`, `filter`, `gear`, `user`, `users`, `calendar`, `clock`, `bell`, `home`, `database`, `table`, `chart-area`, `bar-chart`, `download`, `upload`, `trash`, `edit`, `pencil`, `plus`, `minus`, `dots-horizontal`, `dots-vertical`

**Full List**: See `/click-ui/iconLibrary` for complete list of 165 icons

## Logo names (58 total)

**Common Logos**: `clickhouse`, `aws`, `gcp`, `azure`, `github`, `google`, `mysql`, `postgres`, `kafka`, `snowflake`, `databricks`, `mongodb`, `python`, `nodejs`, `rust`, `golang`

**Full List**: See `/click-ui/logoLibrary` for complete list of 58 logos

## Component relationships

### Dialog works with

- Button (for triggers)
- TextField, Label (for forms)
- Container (for layout)
- FormContainer (for structured forms)

### Table works with

- Pagination (for paginated data)
- Title (for page headers)
- Container (for layout)
- Button (for actions)

### Form components work with

- Label (for accessibility)
- Container (for layout)
- Button (for submission)
- Dialog (for modal forms)

## Type definitions

### Common types

```typescript
type IconSize = "xs" | "sm" | "md" | "lg" | "xl" | "xxl"
type IconState = "default" | "success" | "warning" | "danger" | "info"
type ButtonType = "primary" | "secondary" | "empty" | "danger" | "ghost"
type Orientation = "horizontal" | "vertical"
type ThemeName = "light" | "dark" | "classic"
type SpacingToken = "none" | "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl"
```

### Table types

```typescript
interface TableHeader {
  label: string
  isSortable?: boolean
}

interface TableRow {
  id: string
  items: Array<{ label: string }>
}
```

## Best practices

1. **Always use Container** for layout structure
2. **Use Label** with form inputs for accessibility
3. **Manage state externally** - components are controlled
4. **Use spacing tokens** - never hardcode pixel values
5. **Wrap in ClickUIProvider** at app root
6. **Use semantic components** - Title for headings, Text for body

## Quick start template

```tsx
import { ClickUIProvider, Container, Title, Text, Button, TextField, Label } from '@clickhouse/click-ui'
import { useState } from 'react'

function MyPage() {
const [value, setValue] = useState('')

return (
  <ClickUIProvider theme="dark">
    <Container orientation="vertical" gap="lg" padding="lg">
      <Title size="lg">Page Title</Title>
      <Container orientation="vertical" gap="md">
        <Label htmlFor="input">Label</Label>
        <TextField id="input" value={value} onChange={setValue} />
        <Button type="primary" label="Submit" onClick={() => {}} />
      </Container>
    </Container>
  </ClickUIProvider>
)
}
```

## Component documentation links

- **Layout**: Container, Grid, GridContainer, Panel, Spacer
- **Forms**: TextField, Select, Checkbox, DatePicker, DateRangePicker, FileUpload
- **Display**: Text, Title, Badge, Icon, Logo, CodeBlock
- **Navigation**: Tabs, Accordion, Pagination, VerticalStepper
- **Overlays**: Dialog, Flyout, Popover, Tooltip, ConfirmationDialog
- **Actions**: Button, Dropdown, ContextMenu
- **Feedback**: Alert, Toast
- **Data**: Table, Cards

**Full Documentation**: Each component has detailed docs at `/click-ui/[componentName]` with props tables, examples, and use cases.

## Common use cases

### Create a form page

Use: Container (vertical), Title, Label, TextField/Select, Button

### Create a data table page

Use: Container (vertical), Title, Table, Pagination

### Create a modal form

Use: Dialog, Dialog.Content, Container, Label, TextField, Button

### Create a dashboard

Use: Container, GridContainer, Cards, BigStat, Title

### Create a settings page

Use: Container, Tabs, Title, TextField, Switch, Button

## Complete component props reference

### Container

**Required**: `orientation` ("horizontal" | "vertical")\
**Optional**: `gap` (SpacingToken, default: "none"), `padding` (SpacingToken), `alignItems`, `justifyContent`, `wrap` (boolean), `width`, `height`

### Button

**Required**: `label` (string)\
**Optional**: `type` ("primary" | "secondary" | "empty" | "danger" | "ghost", default: "primary"), `onClick` (function), `disabled` (boolean), `size` (IconSize), `iconLeft` (IconName), `iconRight` (IconName), `fillWidth` (boolean)

### TextField

**Required**: `value` (string), `onChange` (function receiving string)\
**Optional**: `placeholder` (string), `disabled` (boolean), `error` (boolean), `errorText` (string), `label` (string), `id` (string), `type` (string)

### Table

**Required**: `headers` (Array with label and optional isSortable), `rows` (Array with id and items array)\
**Optional**: `pageSize` (number), `onPageChange` (function), `isSelectable` (boolean), `selectedIds` (array), `onSelect` (function), `onDelete` (function)\
**Structure**: headers array contains objects with "label" (string) and optional "isSortable" (boolean). rows array contains objects with "id" (string or number) and "items" array containing objects with "label" (string).

### Dialog

**Required**: `open` (boolean), `onOpenChange` (function receiving boolean)\
**Dialog.Content Props**: `title` (string), `showClose` (boolean), `onClose` (function), `showOverlay` (boolean, default: true)

### Select

**Required**: `value` (string), `onSelect` (function receiving string), `options` (array of objects with label and value properties)\
**Optional**: `label` (string), `placeholder` (string), `disabled` (boolean), `error` (boolean)

### DatePicker

**Required**: `date` (Date or undefined), `onSelectDate` (function receiving Date)\
**Optional**: `placeholder` (string), `disabled` (boolean), `futureDatesDisabled` (boolean)

### DateRangePicker

**Required**: `startDate` (Date or undefined), `endDate` (Date or undefined), `onSelectDateRange` (function receiving start Date and end Date)\
**Optional**: `placeholder` (string), `disabled` (boolean), `futureDatesDisabled` (boolean), `maxRangeLength` (number), `predefinedDatesList` (array of objects with startDate and endDate properties)

## Common errors to avoid

### ❌ Wrong: Button with children

```tsx
<Button onClick={handleClick}>Click me</Button>  // WRONG
```

### ✅ Correct: Button with label prop

```tsx
<Button label="Click me" onClick={handleClick} />  // CORRECT
```

### ❌ Wrong: Hardcoded spacing

```tsx
<Container gap="20px" padding="16px">  // WRONG
```

### ✅ Correct: Use spacing tokens

```tsx
<Container gap="md" padding="lg">  // CORRECT
```

### ❌ Wrong: Uncontrolled form input

```tsx
<TextField placeholder="Enter text" />  // WRONG - missing value/onChange
```

### ✅ Correct: Controlled input

```tsx
const [value, setValue] = useState('')
<TextField value={value} onChange={setValue} placeholder="Enter text" />  // CORRECT
```

### ❌ Wrong: Dialog without controlled state

```tsx
<Dialog defaultOpen={true}>  // WRONG - use controlled state
```

### ✅ Correct: Controlled Dialog

```tsx
const [open, setOpen] = useState(false)
<Dialog open={open} onOpenChange={setOpen}>  // CORRECT
```

### ❌ Wrong: Table with wrong data structure

```tsx
<Table data={users} columns={columns} />  // WRONG - wrong prop names
```

### ✅ Correct: Table with headers/rows

```tsx
<Table headers={headers} rows={rows} />  // CORRECT
```

### ❌ Wrong: Missing Label for accessibility

```tsx
<TextField value={value} onChange={setValue} />  // WRONG - no label
```

### ✅ Correct: Use Label component

```tsx
<Label htmlFor="input">Name</Label>
<TextField id="input" value={value} onChange={setValue} />  // CORRECT
```

### ❌ Wrong: Invalid icon name

```tsx
<Icon name="check-circle" />  // WRONG - should be "check-in-circle"
```

### ✅ Correct: Valid icon name

```tsx
<Icon name="check-in-circle" />  // CORRECT
```

## State management patterns

### Form state pattern

```tsx
const [formData, setFormData] = useState({
name: '',
email: '',
age: ''
})

// Update single field
<TextField 
value={formData.name} 
onChange={(value) => setFormData({ ...formData, name: value })} 
/>

// Update multiple fields
const handleChange = (field: string, value: string) => {
setFormData({ ...formData, [field]: value })
}
```

### Dialog state pattern

```tsx
const [open, setOpen] = useState(false)

// Open dialog
<Button label="Open" onClick={() => setOpen(true)} />

// Close dialog
<Dialog open={open} onOpenChange={setOpen}>
<Dialog.Content onClose={() => setOpen(false)}>
  <Button label="Close" onClick={() => setOpen(false)} />
</Dialog.Content>
</Dialog>
```

### Table selection pattern

```tsx
const [selectedIds, setSelectedIds] = useState<Array<string | number>>([])

<Table
headers={headers}
rows={rows}
isSelectable={true}
selectedIds={selectedIds}
onSelect={(selectedItems) => {
  setSelectedIds(selectedItems.map(item => item.item.id))
}}
/>
```

### Pagination state pattern

```tsx
const [currentPage, setCurrentPage] = useState(1)
const [pageSize, setPageSize] = useState(10)
const totalPages = Math.ceil(totalItems / pageSize)

<Pagination
currentPage={currentPage}
totalPages={totalPages}
onChange={setCurrentPage}
pageSize={pageSize}
onPageSizeChange={setPageSize}
/>
```

## Validation patterns

### Form validation example

```tsx
const [errors, setErrors] = useState<Record<string, string>>({})

const validate = () => {
const newErrors: Record<string, string> = {}

if (!formData.name.trim()) {
  newErrors.name = 'Name is required'
}

if (!formData.email.trim()) {
  newErrors.email = 'Email is required'
} else if (!/\S+@\S+\.\S+/.test(formData.email)) {
  newErrors.email = 'Email is invalid'
}

setErrors(newErrors)
return Object.keys(newErrors).length === 0
}

<TextField
value={formData.name}
onChange={(value) => {
  setFormData({ ...formData, name: value })
  setErrors({ ...errors, name: '' }) // Clear error on change
}}
error={!!errors.name}
errorText={errors.name}
/>
```

## Complete icon list (165 icons)

**All available icon names** (use exactly as shown):
`activity`, `alarm`, `arrow-down`, `arrow-left`, `arrow-right`, `arrow-triangle`, `arrow-directions`, `arrow-up`, `auth-app`, `auth-sms`, `backups`, `bar-chart`, `bell`, `beta`, `blog`, `bold`, `book`, `brackets`, `briefcase`, `building`, `burger-menu`, `calendar`, `calendar-with-time`, `cards`, `cell-tower`, `chat`, `chart-area`, `chart-bar-horizontal`, `chart-donut`, `chart-heatmap`, `chart-scatter`, `chart-stacked-horizontal`, `chart-stacked-vertical`, `check`, `check-in-circle`, `chevron-down`, `chevron-left`, `chevron-right`, `chevron-up`, `circle`, `clock`, `cloud`, `cloud-keys`, `code`, `code-in-square`, `connect`, `connect-alt`, `console`, `copy`, `cpu`, `cross`, `credit-card`, `data`, `database`, `data-lakes`, `disk`, `display`, `document`, `dot`, `dots-horizontal`, `dots-triangle`, `dots-vertical`, `dots-vertical-double`, `double-check`, `download`, `download-in-circle`, `email`, `empty`, `enter`, `eye`, `eye-closed`, `filter`, `fire`, `flag`, `flash`, `flask`, `folder-closed`, `folder-open`, `gear`, `gift`, `git-merge`, `globe`, `hexagon`, `history`, `horizontal-loading`, `home`, `http`, `http-monitoring`, `info-in-circle`, `information`, `insert-row`, `integrations`, `italic`, `key`, `keys`, `lifebuoy`, `light-bulb`, `light-bulb-on`, `lightening`, `line-in-circle`, `list-bulleted`, `list-numbered`, `loading`, `loading-animated`, `lock`, `map-pin`, `metrics`, `metrics-alt`, `minus`, `mcp`, `moon`, `no-cloud`, `pause`, `payment`, `pencil`, `pie-chart`, `pipe`, `play`, `play-in-circle`, `plug`, `plus`, `popout`, `puzzle-piece`, `query`, `question`, `resize-arrows-horizontal`, `resize-arrows-vertical`, `refresh`, `rocket`, `sandglass`, `search`, `secure`, `server`, `services`, `settings`, `share`, `share-arrow`, `share-network`, `sleep`, `slide-in`, `slide-out`, `sort-alt`, `sort`, `sparkle`, `speaker`, `speed`, `square`, `star`, `stop`, `support`, `table`, `taxi`, `text-slash`, `thumbs-down`, `thumbs-up`, `trash`, `tree-structure`, `upgrade`, `upload`, `url`, `user`, `users`, `underline`, `warning`, `waves`

## Complete logo list (58 logos)

**All available logo names** (use exactly as shown):
`clickhouse`, `airbyte`, `aws`, `aws-athena`, `aws-glue`, `aws-kinesis`, `aws-msk`, `aws-redshift`, `aws-s3`, `azure`, `azure-blob-storage`, `azure-event-hub`, `bigquery`, `c#`, `cloudflare`, `confluent`, `databricks`, `datagrip`, `dbeaver`, `dbt`, `decodeable`, `deepnote`, `deltalake`, `digital_ocean`, `feature_database`, `feature_hexagon`, `fivetran`, `gcp`, `gcs`, `github`, `golang`, `google`, `grafana`, `hex`, `hudi`, `iceberg`, `jdbc`, `kafka`, `kubenetes`, `mariadb`, `metabase`, `microsoft`, `mongodb`, `mysql`, `nodejs`, `postgres`, `prequel`, `python`, `redpanda`, `rust`, `snowflake`, `superset`, `tableau`, `upstash`, `vector`, `warpstream`

## Component dependencies

### Required dependencies

- **All components**: Must be wrapped in `ClickUIProvider`
- **Form inputs**: Should use `Label` component for accessibility
- **Dialog**: Requires controlled state (open/onOpenChange)
- **Table with pagination**: Requires `Pagination` component
- **Form validation**: Requires error state management

### Optional but Recommended

- **Forms**: Use `Container` for layout
- **Tables**: Use `Title` for page headers
- **Modals**: Use `Button` for triggers
- **Data display**: Use `Container` for spacing

## Notes for AI Tools

1. **All components are controlled** - manage state with useState/useEffect
2. **Props are typed** - use TypeScript for better autocomplete
3. **Spacing uses tokens** - never use pixel values for gaps/padding
4. **Icons/Logos use string names** - must match exactly (case-sensitive, use hyphens not underscores for icons)
5. **Components are theme-aware** - no need to manually handle dark/light mode
6. **Accessibility is built-in** - use Label with form inputs (htmlFor/id pattern)
7. **Container is essential** - use it for all layouts (orientation is required)
8. **Button uses label prop** - not children (common mistake)
9. **Table uses headers/rows arrays** - not data/columns (common mistake)
10. **Dialog requires controlled state** - use open/onOpenChange pattern (not defaultOpen)
11. **Form inputs require value/onChange** - all are controlled components
12. **Icon names use hyphens** - e.g., "check-in-circle" not "checkInCircle" or "check\_circle"
13. **Logo names use underscores** - e.g., "digital\_ocean" not "digital-ocean"
14. **Default values** - most props are optional, check component docs for defaults
15. **Error handling** - use error/errorText props for form validation feedback