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

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, CheckboxMultiSelect, AutoComplete, DatePicker, DateRangePicker, DateTimeRangePicker, FileUpload, FileMultiUpload, Label

Display components

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

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

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

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

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

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

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

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”)

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

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

Common patterns

Form in dialog

Components: Dialog, TextField, Label, Container, Button

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

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

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

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

interface TableHeader {
  label: string
  isSortable?: boolean
}

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

Best practices

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

Quick start template

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, CheckboxMultiSelect, DatePicker, DateRangePicker, DateTimeRangePicker, 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

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)

Text

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), description (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)

CheckboxMultiSelect

Required: none for uncontrolled use; for controlled use value (string[]) and onSelect (function receiving string[])
Optional: defaultValue (string[]), options (array of objects with label and value, or { heading, options } groups), children (CheckboxMultiSelect.Group / Item / ItemDescription), label (ReactNode), placeholder (string, default “Select an option”), selectLabel (string, trigger text when anything is selected), disabled (boolean), error (ReactNode), showSearch (boolean), useFullWidthItems (boolean), allowCreateOption (boolean)
Item props: value (string), label or children, description (ReactNode), disabled (boolean), icon (IconName), iconDir (“start” | “end”), variant (“default” | “var1”–“var7”)

DatePicker

Required: onSelectDate (function receiving Date)
Optional: date (Date or undefined), placeholder (string), disabled (boolean), futureDatesDisabled (boolean), allowOnlyDatesList (array of Date), timezone (“system” | “UTC”, default “system”), responsivePositioning (boolean, default true)

DateRangePicker

Required: onSelectDateRange (function receiving start Date and end Date)
Optional: startDate (Date or undefined), endDate (Date or undefined), placeholder (string), disabled (boolean), futureDatesDisabled (boolean), maxRangeLength (number), predefinedDatesList (array of objects with startDate and endDate properties), allowOnlyDatesList (array of Date), timezone (“system” | “UTC”, default “system”), responsivePositioning (boolean, default true)

DateTimeRangePicker

Required: onSelectDateRange (function receiving start Date, end Date, and optional predefinedDateLabel string)
Optional: startDate (Date or undefined), endDate (Date or undefined), placeholder (string), disabled (boolean), futureDatesDisabled (boolean), futureStartDatesDisabled (boolean), maxRangeLength (number, default -1), predefinedTimesList (array of objects with label and dateRange { startDate, endDate }), shouldShowSeconds (boolean), timezone (“system” | “UTC”, default “system”), defaultActiveTab (“startDate” | “endDate”, default “startDate”), closeOnDateRangeSelected (boolean, default false), shouldFireIfInvalid (boolean, default true), openDirection (“left” | “right”, default “right”), responsivePositioning (boolean, default true)

Common errors to avoid

❌ Wrong: Button with children

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

✅ Correct: Button with label prop

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

❌ Wrong: Hardcoded spacing

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

✅ Correct: Use spacing tokens

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

❌ Wrong: Uncontrolled form input

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

✅ Correct: Controlled input

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

❌ Wrong: Dialog without controlled state

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

✅ Correct: Controlled Dialog

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

❌ Wrong: Table with wrong data structure

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

✅ Correct: Table with headers/rows

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

❌ Wrong: Missing Label for accessibility

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

✅ Correct: Use Label component

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

❌ Wrong: Invalid icon name

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

✅ Correct: Valid icon name

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

State management patterns

Form state pattern

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

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

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

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

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

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

Availability states Common patterns

AI quick reference

Package information

Component categories

Layout components

Form components

Display components

Navigation components

Overlay components

Action components

Feedback components

Data display components

Essential components quick reference

Container

Button

TextField

Table

Dialog

Icon

Logo

Common patterns

Form in dialog

Table with pagination

Search with filters

Design tokens

Spacing

Sizes

Colors

Icon names (165 total)

Logo names (58 total)

Component relationships

Dialog works with

Table works with

Form components work with

Type definitions

Common types

Table types

Best practices

Quick start template

Component documentation links

Common use cases

Create a form page

Create a data table page

Create a modal form

Create a dashboard

Create a settings page

Complete component props reference

Container

Button

Text

TextField

Table

Dialog

Select

CheckboxMultiSelect

DatePicker

DateRangePicker

DateTimeRangePicker

Common errors to avoid

❌ Wrong: Button with children

✅ Correct: Button with label prop

❌ Wrong: Hardcoded spacing

✅ Correct: Use spacing tokens

❌ Wrong: Uncontrolled form input

✅ Correct: Controlled input

❌ Wrong: Dialog without controlled state

✅ Correct: Controlled Dialog

❌ Wrong: Table with wrong data structure

✅ Correct: Table with headers/rows

❌ Wrong: Missing Label for accessibility

✅ Correct: Use Label component

❌ Wrong: Invalid icon name

✅ Correct: Valid icon name

State management patterns

Form state pattern

Dialog state pattern

Table selection pattern

Pagination state pattern

Validation patterns

Form validation example

Complete icon list (165 icons)