# Data Components

Data components render records from your tables. Each binds to a table through the shared `dataSource` module (`table`, `filter`, `sort`, `pagination`, `mode`) and renders the matching records as a table, list, gallery, kanban board, calendar, chart, KPI, or timeline. Record fields are referenced with `$record.<field>` in templates. See [Pages Overview → Data Binding](/en/docs/pages-overview#data-binding) for the full `dataSource` contract.

```yaml
components:
  - type: data-table
    dataSource: { table: tasks, sort: [{ field: due_date, direction: asc }] }
    columns:
      - { field: title, sortable: true }
      - { field: status, format: badge }
      - { field: due_date, format: relative-date }
```

## `data-table`

A feature-rich table with sorting, filtering, grouping, selection, bulk actions, summaries, and inline editing.

| Property       | Description                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `dataSource`   | Table binding (filter/sort applied server-side with AND logic).                                                  |
| `view`         | Name of a saved [table view](/en/docs/table-views) to inherit filters, sorts, and visible fields.                |
| `columns`      | Column definitions (see below). Auto-generated from table fields when omitted.                                   |
| `filter`       | Additional filter conditions stacked on top of view filters.                                                     |
| `sort`         | Default sort rules (initial state, or applied when no view sorts exist).                                         |
| `rowHeight`    | Row height preset (default: `medium`).                                                                           |
| `striped`      | Alternating row colors (default: `false`).                                                                       |
| `bordered`     | Show cell borders (default: `false`).                                                                            |
| `rowNumbers`   | Show a row-number column (default: `false`).                                                                     |
| `emptyMessage` | Message displayed when no records match.                                                                         |
| `toolbar`      | Toolbar controls — e.g. `{ columnVisibility: true }` to show a column-visibility toggle.                         |
| `selection`    | Row selection config (see below).                                                                                |
| `bulkActions`  | Actions available when rows are selected (see below).                                                            |
| `groupBy`      | Row grouping config (see below).                                                                                 |
| `summary`      | Summary row with aggregate computations (see below).                                                             |
| `autoSave`     | Inline-edit save behavior — see [Interactivity & Scripts → Auto-Save](/en/docs/interactivity-scripts#auto-save). |

### `columns`

Each entry defines one column.

| Property            | Description                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `field`             | Field name from the data-source table.                                                                   |
| `label`             | Header label override (defaults to the field's display name).                                            |
| `width`             | Column width in pixels.                                                                                  |
| `minWidth`          | Minimum column width in pixels.                                                                          |
| `align`             | Text alignment: `left` (default), `center`, `right`.                                                     |
| `format`            | Display format override for cell rendering (e.g. `badge`, `currency`, `relative-date`).                  |
| `pinned`            | Pin the column to the left side of the table.                                                            |
| `sortable`          | Allow sorting on this column (default: `true`).                                                          |
| `filterable`        | Allow filtering on this column (default: `true`).                                                        |
| `editable`          | Allow inline editing (defaults to the table's permissions).                                              |
| `hidden`            | Column visibility (default: `true` = visible).                                                           |
| `conditionalStyles` | Rules `{ when: { operator: value }, className }` applying Tailwind classes when a cell condition is met. |
| `actions`           | Action buttons (e.g. edit/delete) with `label`, `icon`, and a confirm message (supports `{count}`).      |

### `selection`

| Property       | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `mode`         | `none` (default), `single`, or `multiple`.                        |
| `showCheckbox` | Show a checkbox column (default: `true` when mode is `multiple`). |

### `bulkActions`

| Property  | Description                                                                      |
| --------- | -------------------------------------------------------------------------------- |
| `label`   | Bulk-action button label.                                                        |
| `icon`    | Lucide icon name (e.g. `truck`, `trash`).                                        |
| `confirm` | Confirmation dialog message; supports `{count}` for the number of selected rows. |
| `action`  | The action invoked on the selected rows.                                         |

### `groupBy`

| Property    | Description                                |
| ----------- | ------------------------------------------ |
| `field`     | Field to group rows by.                    |
| `direction` | Group sort direction (default: `asc`).     |
| `collapsed` | Start groups collapsed (default: `false`). |
| `hideEmpty` | Hide empty groups (default: `false`).      |

### `summary`

| Property    | Description                                               |
| ----------- | --------------------------------------------------------- |
| `field`     | Field to compute the summary on.                          |
| `aggregate` | Aggregate function (`sum`, `avg`, `count`, `min`, `max`). |

## `list`

A vertical list of records, each rendered from a template using `$record.*` references.

| Property            | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `dataSource`        | Table binding.                                                 |
| `template.title`    | Primary text (`$record.*` reference).                          |
| `template.subtitle` | Secondary text.                                                |
| `template.image`    | Image URL (`$record.*` reference).                             |
| `template.badge`    | Badge text.                                                    |
| `template.meta`     | Metadata fields shown in the item footer (`field` + `format`). |
| `pagination`        | `button` (Load More) or `infinite` (load on scroll).           |
| `highlightSearch`   | Highlight matched search terms (default: `false`).             |
| `divided`           | Show dividers between items (default: `false`).                |
| `maxItems`          | Maximum number of items to display.                            |
| `emptyMessage`      | Message when no search results match.                          |

## `gallery`

A responsive card grid of records.

| Property           | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `dataSource`       | Table binding.                                                    |
| `gridColumns`      | Responsive column counts per breakpoint (mobile, sm, md, lg, xl). |
| `card.image`       | Cover image URL or `$record.*` reference.                         |
| `card.aspectRatio` | Cover aspect ratio (e.g. `4:3`, `16:9`, `1:1`).                   |
| `card.children`    | Child components for the card body.                               |
| `card.overlay`     | Components rendered in a hover overlay on the card.               |

## `kanban`

A drag-and-drop board grouping records into columns by a field value.

| Property           | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `dataSource`       | Table binding.                                                     |
| `groupBy`          | Field whose values become the kanban columns.                      |
| `card.children`    | Child components for the card body.                                |
| `card.image`       | Image URL or `$record.*` reference for the card cover.             |
| `card.colorField`  | Field whose values set the card background color.                  |
| `card.footer`      | Metadata fields displayed in the card footer (`field` + `format`). |
| `dragDrop.enabled` | Enable drag-and-drop between columns (default: `true`).            |

## `calendar`

A month/week/day calendar of date-bearing records.

| Property                   | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `dataSource`               | Table binding.                                                       |
| `mode`                     | Display mode: `month`, `week`, or `day`.                             |
| `event`                    | How records map to calendar events (start/end fields, title, color). |
| `interaction.slotMinutes`  | Time-slot interval in minutes for week/day views (default: 60).      |
| `interaction.nowIndicator` | Show a line at the current time in week/day views.                   |

## `chart`

A data visualization (bar, line, area) computed from aggregated records.

| Property          | Description                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| `dataSource`      | Table binding.                                                                                 |
| `series`          | One or more `{ field, color, stackGroup, fillOpacity }` series. Color is a theme token or hex. |
| `xAxis` / `yAxis` | Axis config — `{ field, scale, format, gridLines }`.                                           |
| `aggregate`       | `{ function, field, groupBy, interval }` for summarized data (omit `field` for count).         |
| `legend`          | `{ position, show }` legend display.                                                           |
| `tooltip`         | Tooltip text template (supports `{label}` and `{value}`).                                      |

## `kpi`

A single summary metric (a "stat card") with optional trend and sparkline.

| Property     | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| `dataSource` | Table binding.                                                                                |
| `aggregate`  | `{ function, field }` aggregate (omit `field` for count).                                     |
| `format`     | `{ type, options }` value formatting (e.g. `{ type: currency, options: { currency: USD } }`). |
| `trend`      | `{ period, direction, color, change }` comparison vs. a previous period.                      |
| `sparkline`  | `{ field, groupBy, interval, days }` mini trend line.                                         |

## `data-timeline`

A chronological feed of records ordered by a date/time field. Renders each record as a timeline entry.

| Property     | Description                                                                    |
| ------------ | ------------------------------------------------------------------------------ |
| `dataSource` | Table binding.                                                                 |
| `template`   | Per-record entry template (`$record.*` references for title, body, timestamp). |
| `props`      | Additional HTML attributes (e.g. `className`).                                 |

## `data-form` / `form`

A record-backed form for create/update operations against a table. The `action` (`crud`) determines whether it creates or edits, and form fields are generated from the table schema (overridable per field). For the full field reference and submission handling, see [Forms](/en/docs/forms-overview) and [Form Controls](/en/docs/form-controls).

| Property     | Description                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------- |
| `dataSource` | Table binding (single mode for edit, supplying current values).                                                      |
| `fields`     | Per-field config — `{ field, label, placeholder, readonly, disabled, default, hidden, accept, dropZone, maxFiles }`. |
| `layout`     | Field layout mode (default: `single-column`).                                                                        |
| `groups`     | Group fields under a labeled section divider (`{ label, fields }`).                                                  |
| `action`     | `crud` action with `operation: create                                                                                | update | delete`, `confirm`, and `onSuccess`/`onError` handlers. |

```yaml
- type: data-form
  dataSource: { table: contacts, mode: single, param: id }
  action:
    type: crud
    operation: update
    onSuccess: { type: navigate, url: /contacts }
  fields:
    - { field: email, label: 'Email Address' }
    - { field: notes, placeholder: 'Internal notes…' }
```

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — `dataSource` binding, filters, pagination, `$currentUser` scoping.
- [Tables Overview](/en/docs/tables-overview) — the data models these components render.
- [Views](/en/docs/table-views) — saved filters/sorts reused via `data-table.view`.
- [Form Controls](/en/docs/form-controls) — individual input components.
- [Forms](/en/docs/forms-overview) — standalone form definitions.
- [Interactivity & Scripts](/en/docs/interactivity-scripts) — auto-save for inline editing.