# rn-data-grid-view-select
URL: /docs/native/docyrus/data-grid-view-select

Saved-view switcher for a data grid — pill tabs, dropdown or picker sheet, active-view actions, a full-screen view editor with 11 sections and a manage-views sheet. Same API as the web component.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-data-grid-view-select
```

**Dependencies:**
- [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)
- [@react-querybuilder/core](https://www.npmjs.com/package/@react-querybuilder/core)
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)

`DataGridViewSelect` drives the TanStack `table` of a data grid (from `useDataGrid`, `useDocyrusDataGrid` or your own `useReactTable`): selecting a view applies it with `applyViewToTable` (visibility, order, pinning, sorting, filters, grouping, row height, display mode, column options). The public API mirrors web `@docyrus/ui` 1:1 — `useDocyrusDataViewSelect` returns a ready-made `gridViewSelectProps` object for it.

Mobile adaptations:

- **Active-view menu** — long-press a tab (or the view chip), or tap its **⋯**: an ActionSheet with *Configure*, *Rename*, *Hide*, *Hidden views*, *Add view after / before*, *Duplicate view*, *Delete* (confirmed with `DeleteConfirmDialog`) and *Manage all views*. System views (`isSystem`) only offer *Hide*, *Hidden views* and *Manage all views*.
- **View editor** — a full-screen page sheet with an accordion of sections instead of the web two-pane dialog.
- **Manage all views** — a bottom sheet with up / down reorder, hide / unhide and delete.
- **Add view** — the **+** button (and the picker sheet's *Add view* row) opens a quick "name this view" sheet that saves the grid's **current layout** (`captureViewSnapshot`); *Configure all settings…* opens the full editor instead.
- **`vertical-tabs`** (web side panel) renders a trigger chip that opens a picker sheet listing every view.

## Usage

```tsx
import { useDataGrid, DataGrid } from '@/components/docyrus-native/data-grid';
import { DataGridViewSelect, type SavedDataGridView } from '@/components/docyrus-native/data-grid-view-select';

function DealsPage() {
  const grid = useDataGrid({ data, columns });
  const [views, setViews] = useState} />
```

## API Reference

### DataGridViewSelect

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `table` | `Table<TData>` | — | **Required.** The grid's TanStack table. Views are applied to it via `applyViewToTable`; the editor reads its columns (labels, groups, `meta.forcedReadOnly`, relation cells, groupable / sortable columns). |
| `views` | `SavedDataGridView[]` | — | **Required.** The saved views (see [SavedDataGridView](#saveddatagridview)). |
| `variant` | `'dropdown' \| 'horizontal-tabs' \| 'vertical-tabs' \| 'tabs'` | `'dropdown'` | `dropdown`: view chip + searchable picker sheet. `horizontal-tabs`: scrollable pill tab strip. `vertical-tabs`: view chip + picker sheet + add button (web side panel). `tabs`: **deprecated** alias of `horizontal-tabs`. |
| `maxVisibleViews` | `number` | — | `horizontal-tabs` only. Views past this count move into a **More (n)** sheet; the active view is swapped onto the strip. |
| `activeViewId` | `string` | — | Controlled active view id. |
| `defaultActiveViewId` | `string` | — | Initial active view id (uncontrolled). Nothing is active when omitted (web parity). |
| `onViewChange` | `(view: SavedDataGridView) => void` | — | Fires after the selected view was applied to `table`. |
| `onViewCreate` | `(view: SavedDataGridView, position?: { afterViewId?: string; beforeViewId?: string }) => void` | — | Create from the editor, quick create, *Duplicate view* (`afterViewId` = source) and *Add view after / before*. Omitted → no create affordances. |
| `onViewSave` | `(view: SavedDataGridView) => void` | — | Save from the editor. Also receives renames when `onViewRename` is omitted. |
| `onViewDelete` | `(viewId: string) => void` | — | Delete (editor button, actions sheet, manage sheet). Always confirmed. Never offered for system views. |
| `onViewHide` | `(viewId: string) => void` | — | Hide a view from the list. |
| `onViewUnhide` | `(viewId: string) => void` | — | Unhide (Hidden views sheet, Manage all views). |
| `hiddenViewIds` | `string[]` | — | Ids of hidden views. |
| `onViewReorder` | `(orderedViewIds: string[]) => void` | — | New top-to-bottom order from **Manage all views**. Omitted → no reorder controls. |
| `onViewRename` | `(viewId: string, name: string) => void` | — | Native convenience for the *Rename* action. Falls back to `onViewSave({ ...view, name })`. |
| `fields` | `FullField[]` | — | Query-builder fields (`@react-querybuilder/core`) for the editor's **Filters** section. Omitted / empty → section hidden. |
| `forms` | `DataForm[]` | — | Saved forms (`@docyrus/app-utils`) for the editor's **Form** section. Omitted / empty → section hidden. Archived forms are skipped. |
| `editable` | `boolean` | `false` | Enables the actions sheet, editor, quick create, and manage sheet. |
| `disabled` | `boolean` | — | Disables every interaction. |
| `placeholder` | `string` | `ui.dataGridView.selectView` → `'Select view'` | Chip label when no view is active. |
| `isSaving` | `boolean` | — | `true` while a create / save request is in flight. The editor stays open behind a **Saving…** overlay and closes when it flips back to `false`. Omitted → the editor closes immediately on Save. |
| `isLoading` | `boolean` | — | Renders a *Loading views…* row while `views` is still empty. |
| `defaultRowGroupingColumn` | `string` | — | Column id shown as *(Default)* in the Row Grouping section, with a hint when the view has no grouping. |
| `galleryCardConfig` | `DataGalleryCardConfigSerializable` | — | Live gallery card bindings for the **Gallery View** section. |
| `galleryDisplayConfig` | `DataGalleryDisplayConfig` | `DEFAULT_DATA_GALLERY_DISPLAY_CONFIG` | Live gallery layout for the **Gallery View** section. |
| `onGalleryCardConfigChange` | `(updater: (prev) => DataGalleryCardConfigSerializable) => void` | — | With `onGalleryDisplayConfigChange`, shows the Gallery View section (edited live — persisted by the host on Save). |
| `onGalleryDisplayConfigChange` | `(updater: (prev) => DataGalleryDisplayConfig) => void` | — | See above. |
| `className` | `string` | — | Root className. |

### DataGridViewEditor

The full-screen editor (web `ViewEditorDialog`). `DataGridViewSelect` mounts it for you; use it directly for custom triggers.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `table` | `Table<TData>` | — | **Required.** Source of the column list and defaults. |
| `open` | `boolean` | — | Controlled open state. |
| `onOpenChange` | `(open: boolean) => void` | — | Open state change. |
| `value` | `SavedDataGridView` | — | The view being edited. Omitted → create mode (defaults from the table's current row height / display mode). |
| `views` | `SavedDataGridView[]` | — | Enables the *Switch view* picker (non-system views) while editing. |
| `onSave` | `(view: SavedDataGridView) => void` | — | Receives the built view. |
| `onDelete` | `(viewId: string) => void` | — | Delete button handler. |
| `onCancel` | `() => void` | — | Cancel handler. |
| `onViewSwitch` | `(viewId: string) => void` | — | *Switch view* handler (swap `value`). |
| `fields` | `FullField[]` | — | Filters section fields. |
| `forms` | `DataForm[]` | — | Form section forms. |
| `defaultRowGroupingColumn` | `string` | — | Row Grouping default. |
| `isSaving` | `boolean` | — | Saving overlay + auto-close. |
| `disabled` | `boolean` | — | Disables every control. |
| `showDelete` | `boolean` | — | Shows the Delete button (edit mode only). |
| `trigger` | `ReactNode` | — | Pressable content that opens the editor (uncontrolled use). |
| `galleryCardConfig` / `galleryDisplayConfig` / `onGalleryCardConfigChange` / `onGalleryDisplayConfigChange` | — | — | Gallery View section (see above). |
| `className` | `string` | — | Sheet body className. |

### Editor sections

| Section | Contents |
|---------|----------|
| **General** | Name + icon picker (Font Awesome / Huge Icons, searchable), description, row height (`short` / `medium` / `tall` / `extra-tall`), display mode (`table` / `gallery`). |
| **Columns** | Search; *Selected columns* with remove, **pin** (writes `columnPinning.left` in selected order), visibility eye (disabled when the column can't hide) and up / down reorder; *Available columns* grouped by `meta.group` with add; *Column options* — **Show autonumber** for relation columns (`columnOptions[id].showAutonumber`). |
| **Sorting** | Ordered sort rules: column, Asc / Desc, reorder, remove, *Add sort*. |
| **Row Grouping** | One groupable column (select, status, relation, date, datetime, user) or *No grouping*. |
| **Paging** | *Activate paging footer*, paging mode (`standard` / `virtual-scroll`), page size (`DATA_GRID_PAGE_SIZE_OPTIONS`). |
| **Inline Editing** | Master switch + per-column read-only switches, *All editable* / *All read-only*. Columns with `meta.forcedReadOnly` are locked (metadata badge). |
| **Form** | Bind a saved form (`formId`) — shown when `forms` is non-empty. |
| **Filters** | Native `QueryBuilderDocyrus` over `fields` → `filterQuery` — shown when `fields` is non-empty. |
| **Gallery View** | `DataGalleryCardConfigMenu` + `DataGalleryDisplayMenu` (live) — shown when both gallery change handlers are set. |
| **Row Color Rules** | JSONata formula + colour (palette swatches or any hex / Tailwind name such as `emerald-500`, resolved with `resolveColorHex`). |
| **Cell Color Rules** | Column + JSONata formula + colour. |

Everything except Gallery View is a draft emitted only on **Save** (the Save button needs a name).

### SavedDataGridView

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | View id. |
| `name` | `string` | Display name. |
| `description` | `string` | Optional description (shown in the picker sheet). |
| `icon` | `string` | Docyrus icon (`'fal table'`, `'huge file-01'`). |
| `columnVisibility` | `Record<string, boolean>` | Column visibility. |
| `columnOrder` | `string[]` | Selected columns in order. |
| `columnPinning` | `{ left?: string[]; right?: string[] }` | Pinned columns (`select` / `actions` are kept pinned first by `applyViewToTable`). |
| `rowHeight` | `'short' \| 'medium' \| 'tall' \| 'extra-tall'` | Row height. |
| `displayMode` | `'table' \| 'gallery'` | Display mode. |
| `sorting` | `SortingState` | Sort rules. |
| `columnFilters` | `ColumnFiltersState` | Column (chip) filters — preserved as-is by the editor. |
| `grouping` | `string[]` | Row grouping (one column). |
| `filterQuery` | `RuleGroupType` | Query-builder filter. |
| `rowColorRules` | `{ formula: string; color: string }[]` | Row colour rules (JSONata). |
| `cellColorRules` | `{ column: string; formula: string; color: string }[]` | Cell colour rules (JSONata). |
| `pagingEnabled` | `boolean` | Paging footer on. |
| `pagingMode` | `'standard' \| 'virtual-scroll'` | Paging layout. |
| `pageSize` | `number` | Page size. |
| `inlineEditingEnabled` | `boolean` | Inline editing on. |
| `readOnlyColumns` | `string[]` | User-chosen read-only columns (forced ones are recomputed). |
| `columnOptions` | `Record<string, { showAutonumber?: boolean }>` | Per-column display options. |
| `isSystem` | `boolean` | Developer-defined view — can be hidden, never edited / deleted. |
| `isDefault` | `boolean` | Initial view when nothing is persisted. |
| `formId` | `string` | Bound saved form. |
| `galleryCardConfig` | `DataGalleryCardConfigSerializable` | Gallery card bindings. |
| `galleryDisplayConfig` | `Partial<DataGalleryDisplayConfig>` | Gallery layout. |

## DataGridAdvancedFilter

The grid toolbar's AND / OR filter lives in the data-grid package (`@/components/docyrus-native/data-grid`) and shares this editor's query builder. See the [rn-data-grid](/docs/native/docyrus/data-grid) page.

## Translations

All copy goes through `useUiTranslation()` with the web keys — `ui.dataGridView.*` (e.g. `selectView`, `addView`, `configure`, `hideView`, `hiddenViews`, `addViewAfter`, `addViewBefore`, `duplicateView`, `deleteView`, `manageAllViews`, `editView`, `newView`, `saveView`, `saving`, `general`, `columns`, `sorting`, `rowGrouping`, `paging`, `inlineEditing`, `form`, `filters`, `galleryView`, `rowColorRules`, `cellColorRules`, …) plus native-only keys `renameView`, `createView`, `configureAllSettings`, `moreViews`, `more`, `moveUp`, `moveDown`, `columnOptions`, `color`, `customColorPlaceholder`, `apply`, `viewObjectName`, `deleteViewTitle`, `rowColorRulesHint`, `cellColorRulesHint`, `manageAllViewsDescriptionNative`.

## Breaking changes (native)

| Before | Now |
|--------|-----|
| No `table` prop | `table` is **required** — views are applied to it. |
| `views: DataGridView[]` (`filters` / `sorting` / `columns: unknown`) | `views: SavedDataGridView[]`. `DataGridView` type removed. |
| `onViewCreate(name: string)` | `onViewCreate(view: SavedDataGridView, position?)` — quick create now sends a full view built from the current table layout. |
| `variant: 'tabs' \| 'dropdown'`, default `'tabs'` | `'dropdown' \| 'horizontal-tabs' \| 'vertical-tabs'`, default **`'dropdown'`** (web). `'tabs'` still works as a deprecated alias. |
| First view active by default | Nothing active unless `activeViewId` / `defaultActiveViewId` is set (web). |
| Long-press a tab → inline rename | Long-press → actions sheet (Rename is one of its actions). |
| `style` prop | Removed — use `className`. |
| Single-file `components/data-grid-view-select.tsx` | Multi-file folder with an `index.tsx` barrel (same import path). |

## Type Exports

| Type | Description |
|------|-------------|
| `DataGridViewSelectProps<TData>` | Props of `DataGridViewSelect`. |
| `DataGridViewEditorProps<TData>` | Props of `DataGridViewEditor`. |
| `DataGridViewSelectVariant` | `'dropdown' \| 'horizontal-tabs' \| 'vertical-tabs' \| 'tabs'`. |
| `DataGridViewCreatePosition` | `{ afterViewId?: string; beforeViewId?: string }`. |
| `DataGridGalleryCardConfigUpdater` / `DataGridGalleryDisplayConfigUpdater` | Gallery change-handler signatures. |
| `DataGridViewDraftColumn` | Editor column draft (returned by `buildDraftColumns`). |
| `SavedDataGridView` | Re-exported from the data-grid types. |

Also exported: `buildDraftColumns(table, view?)` — the editor's column list builder.