# Click UI Design System Documentation

## Overview
Click UI is the official design system and component library for ClickHouse. This documentation site provides comprehensive guides, examples, and API references for all components.

## Reading this site as markdown

Do not fetch the HTML pages. Every documentation page is available as clean
markdown, which is far cheaper to read:

- **Append `.md` to any URL.** `https://clickhouse.design/click-ui/buttons`
  becomes `https://clickhouse.design/click-ui/buttons.md`. Section roots work
  too: `https://clickhouse.design/click-ui.md`. The homepage is
  `https://clickhouse.design/index.md`.
- **Or send `Accept: text/markdown`** with a request for the normal URL and you
  will be redirected to the markdown version.

Component props are rendered as markdown tables and all code samples are kept as
fenced code blocks, so the `.md` version contains everything the page shows.

### Best starting points
- `https://clickhouse.design/click-ui/ai-quick-reference.md` — every component,
  prop, pattern and example on one page. Start here.
- `https://clickhouse.design/click-ui/getting-started.md` — installation and the
  required `ClickUIProvider` setup.
- `https://clickhouse.design/click-ui/patterns.md` — copy-paste-ready
  compositions for common UI patterns.
- `https://clickhouse.design/click-ui/tokens.md` — design tokens.

## Key Information

### Component Library
- **Package**: `@clickhouse/click-ui`
- **Location**: `https://github.com/ClickHouse/click-ui`
- **Documentation**: `https://clickhouse.design/click-ui`

### Component Categories

#### Layout Components
- `Container` - Flexible layout component for spacing, alignment, and responsive behavior
- `Grid` - Responsive grid layout component
- `GridContainer` - CSS Grid-based container with flexible column definitions
- `Panel` - Content container with optional border, padding, and shadow
- `Spacer` - Vertical spacing utility

#### Form Components
- `TextField` - Text input field
- `TextAreaField` - Multi-line text input
- `NumberField` - Numeric input field
- `PasswordField` - Password input with show/hide toggle
- `SearchField` - Search input with icon
- `Select` - Dropdown select component
- `MultiSelect` - Multi-select dropdown
- `CheckboxMultiSelect` - Checkbox-based multi-select
- `Checkbox` - Checkbox input
- `RadioGroup` - Radio button group
- `Switch` - Toggle switch
- `DatePicker` - Date selection picker
- `DateRangePicker` - Date range selection
- `FileUpload` - Single file upload
- `FileMultiUpload` - Multiple file upload
- `AutoComplete` - Autocomplete input field
- `Label` - Form label component

#### Display Components
- `Text` - Typography component with size, weight, and color variants
- `Title` - Heading component (h1-h6)
- `Badge` - Status badge with states and types
- `Avatar` - User avatar component
- `BigStat` - Large statistic display
- `CodeBlock` - Code block with syntax highlighting
- `InlineCodeBlock` - Inline code display
- `ProgressBar` - Progress indicator
- `Icon` - Icon component (see iconLibrary.mdx for all available icons)
- `Logo` - Logo component (see logoLibrary.mdx for all available logos)
- `Link` - Link component with styling
- `Separator` - Visual divider (horizontal or vertical)

#### Navigation Components
- `Tabs` - Tab navigation component
- `FileTabs` - File tab interface with drag-and-drop reordering
- `Accordion` - Collapsible accordion component
- `MultiAccordion` - Multiple accordion items
- `VerticalStepper` - Vertical step indicator
- `Pagination` - Page navigation with page size selector
- `SidebarNavigationItem` - Sidebar navigation item
- `SidebarCollapsibleItem` - Collapsible sidebar item
- `SidebarNavigationTitle` - Sidebar section title
- `SidebarCollapsibleTitle` - Collapsible sidebar section title

#### Overlay Components
- `Dialog` - Modal dialog component
- `Flyout` - Slide-in panel from left/right
- `Popover` - Popover component
- `Tooltip` - Tooltip component
- `HoverCard` - Hover card component
- `ConfirmationDialog` - Confirmation dialog
- `ContextMenu` - Context menu component

#### Action Components
- `Button` - Primary button component with types (primary, secondary, empty, danger)
- `IconButton` - Icon-only button
- `SplitButton` - Button with dropdown menu
- `ButtonGroup` - Grouped buttons
- `Dropdown` - Dropdown menu component

#### Feedback Components
- `Alert` - Alert message component (DangerAlert, InfoAlert, WarningAlert, SuccessAlert)
- `Toast` - Toast notification system (useToast hook, ToastProvider)

#### Data Display Components
- `Table` - Data table with sorting, selection, and actions
- `CardPrimary` - Primary card component
- `CardSecondary` - Secondary card component
- `CardHorizontal` - Horizontal layout card
- `CardPromotion` - Promotional card
- `DateDetails` - Relative time display with detailed tooltip

#### Utilities
- `FormContainer` - Form layout container
- `EllipsisContent` - Text truncation with ellipsis

## Common Patterns

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

function DataTable() {
  const [currentPage, setCurrentPage] = useState(1)
  const [pageSize, setPageSize] = useState(10)
  
  const headers = [{ label: 'Name' }, { label: 'Email' }]
  const rows = [
    { id: '1', items: [{ label: 'John' }, { label: 'john@example.com' }] }
  ]
  
  return (
    <Container orientation='vertical' gap='lg'>
      <Title as='h2'>Users</Title>
      <Table headers={headers} rows={rows} />
      <Pagination
        currentPage={currentPage}
        totalPages={10}
        onChange={setCurrentPage}
        pageSize={pageSize}
        onPageSizeChange={setPageSize}
        rowCount={100}
        maxRowsPerPageList={[10, 25, 50, 100]}
      />
    </Container>
  )
}
```

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

function FormDialog() {
  const [open, setOpen] = useState(false)
  const [name, setName] = useState('')
  
  return (
    <>
      <Button label='Open Form' onClick={() => setOpen(true)} />
      <Dialog open={open} onOpenChange={setOpen}>
        <Dialog.Content title='Create User' showClose onClose={() => setOpen(false)}>
          <Container orientation='vertical' gap='md'>
            <TextField label='Name' value={name} onChange={e => setName(e.target.value)} />
            <Container justifyContent='flex-end' gap='sm'>
              <Button type='secondary' label='Cancel' onClick={() => setOpen(false)} />
              <Button type='primary' label='Create' onClick={() => {}} />
            </Container>
          </Container>
        </Dialog.Content>
      </Dialog>
    </>
  )
}
```

## Important Notes

1. **Provider Required**: All Click UI components must be wrapped in `ClickUIProvider`
2. **Props Structure**: 
   - Table uses `headers` (array of `{label, isSortable, width}`) and `rows` (array of `{id, items: [{label}]}`)
   - Buttons use `label` prop, not children
   - Form inputs use `onChange` with event handler
3. **State Management**: Most components are controlled - you manage state externally
4. **Styling**: Components use design tokens, no custom CSS needed
5. **Accessibility**: All components are built with accessibility in mind

## Documentation Structure

- Component docs: `/pages/click-ui/[componentName].mdx`
- Common patterns: `/pages/click-ui/patterns.mdx`
- Icon library: `/pages/click-ui/iconLibrary.mdx`
- Logo library: `/pages/click-ui/logoLibrary.mdx`
- PropsTable component: `/components/click-ui/PropsTable.tsx`

## Quick Reference

### Button Types
- `primary` - Main action button
- `secondary` - Secondary action
- `empty` - Minimal styling
- `danger` - Destructive action

### Badge States
- `default`, `success`, `warning`, `danger`, `info`, `neutral`, `disabled`

### Text Sizes
- `xs`, `sm`, `md`, `lg`, `xl`, `xxl`

### Spacing Tokens
- `none`, `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`

### Container Orientation
- `horizontal` - Items arranged horizontally (default)
- `vertical` - Items arranged vertically

## When Creating New Pages

1. Use `Container` for layout structure
2. Use `Title` for page headings
3. Use `Spacer` for consistent vertical spacing
4. Use `Panel` with `hasBorder` for example containers
5. Follow the pattern structure in `patterns.mdx` for common UI patterns