# useDocyrusDataGrid
URL: /docs/web/hooks/use-docyrus-data-grid

One-call wiring of a Docyrus data source to a fully configured DataGrid + toolbar (DataGridViewSelect, search, filters, group, sort, row height, display) — including row fetching with view-derived query parameters.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-grid
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [@tanstack/react-table](https://tanstack.com/table/latest)
- [react-querybuilder](https://react-querybuilder.js.org)

This hook is distributed as source. It requires an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDataGrid` is the one-call entry point that wires a Docyrus data source to `

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `data` | `Array

## Field Type → Cell Variant Mapping

The hook maps every Docyrus field type to the matching `DataGrid` cell variant when generating columns from `dataSource.fields`:

| Docyrus `type` | `cell.variant` |
|----------------|----------------|
| `field-text`, `field-code` | `short-text` |
| `field-textarea`, `field-htmlEditor`, `field-docEditor` | `long-text` |
| `field-email` | `email` |
| `field-phone` | `phone` |
| `field-url` | `url` |
| `field-color` | `color` |
| `field-icon` | `icon` |
| `field-number`, `field-autonumber`, `field-identity` | `number` |
| `field-money` | `currency` (with `currency`, `decimalPrecision`, `thousandSeparator` from the field's `format` or flat `currency` / `decimal_precision` / `thousand_separator`) |
| `field-currency` | `currency-code` |
| `field-percent` | `percent` (with `decimalPrecision`, `thousandSeparator`, `symbolPosition` from `format`) |
| `field-rating` | `rating` (with `max` from `format.ratingMax` or `maxRating`, `icon` from `format.ratingIcon`) |
| `field-duration` | `duration` |
| `field-date` | `date` |
| `field-dateRange` | `date-range` |
| `field-dateTime` | `datetime` |
| `field-time` | `time` |
| `field-checkbox` | `checkbox` |
| `field-switch` | `switch` |
| `field-status` | `status` (with options; see [Status cells](#status-cells)) |
| `field-enum`, `field-systemEnum` | `enum` (with `appSlug`, `dataSourceSlug`, `fieldSlug`, options) |
| `field-select`, `field-radioGroup` | `select` (with options) |
| `field-multiSelect` | `multi-select` (with options) |
| `field-tagSelect` | `tag-select` (with options) |
| `field-file` | `file` |
| `field-image` | `image` |
| anything else | `short-text` |

### Enum option resolution

For enum-backed fields (`field-status`, `field-enum`, `field-systemEnum`, `field-select`, `field-radioGroup`, `field-multiSelect`, `field-tagSelect`), options are read from the field's `enums` array (returned by the `expand=enums` data source fetch) and fall back to `options` if `enums` is absent. Each option's `slug` becomes the cell value and `name` becomes the label; `color` is forwarded when present.

### Status cells

`field-status` renders with `StatusCell`, not the plain select. Options may carry `parent` (two-level status → sub-status lists, shown as "Main › Sub"), `isFinalOption` (closing statuses get a check mark) and `forceDescription` / `forceFollowupDate`. When a real data source is bound, the hook wires `tableMeta.onStatusUpdate` to `POST /v1/apps/{app}/data-sources/{ds}/status-update/{fieldSlug}`; the cell then asks for the required note / follow-up date before saving and logs the activity **in addition to** writing the value through the normal cell update — the endpoint only records the activity, it does not change the row. Without `onStatusUpdate` (local `data`), the cell behaves like a select and never asks for details it could not persist.

### Out of scope

`field-userSelect`, `field-userMultiSelect`, `field-relation`, and `field-relatedField` need extra metadata that is not part of the data source field response (user list, related data source id). They fall back to `short-text` — pass `mapColumn` to render a richer cell when your app has the extra info on hand.

## Translating column headers

Column headers default to each field's schema label (`field.name`). Pass `dynamicLabelTranslator` to remap them from your own i18n dictionary — the hook calls it once per column and renders whatever string you return. Omit the prop and headers stay exactly as the schema defines them.

The function receives the raw label and returns the display text. Return the label unchanged for anything you don't want to translate:

```tsx
// Simple dictionary
const labels: Record<string, string> = {
  Name: 'İsim',
  Status: 'Durum',
  Description: 'Açıklama'
};

const { table, gridProps, toolbar } = useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicLabelTranslator: (label) => labels[label] ?? label
});
```

```tsx
// With an i18n library (i18next, next-intl, …)
const { t } = useTranslation();

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicLabelTranslator: (label) => t(`fields.${label}`, label)
});
```

## Translating enum options

`dynamicLabelTranslator` only touches **field-level** labels (headers). To translate the option labels **inside** enum-backed cells and filter dropdowns (`field-select`, `field-status`, `field-radioGroup`, `field-enum`, `field-multiSelect`, `field-tagSelect`), pass `dynamicEnumOptionTranslator`.

Enum options carry a stable, language-independent `slug` (the stored value) plus a display `name`. Key your translation by `enums.<field.slug>.<option.slug>` and translate only `name` — `slug`, `color`, and `icon` are preserved automatically:

```tsx
const { t } = useTranslation();

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicEnumOptionTranslator: (option, field) =>
    t(`enums.${field.slug}.${option.slug}`, option.name)
});
```

```tsx
// Simple dictionary keyed by option slug
const statusLabels: Record<string, string> = { open: 'Açık', done: 'Tamamlandı' };

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicEnumOptionTranslator: (option) =>
    option.slug ? statusLabels[option.slug] ?? option.name : option.name
});
```