---
title: View Metadata
description: Configure list views and form views — grid, kanban, calendar, gantt, and more
---

# View Metadata

A **View** defines how records of an Object are displayed to users. ObjectStack supports two main view categories: **List Views** for browsing records and **Form Views** for editing individual records.

## List View

A List View controls how a collection of records is presented. It supports multiple visualization types.

### Basic Structure

```typescript
const taskListView = {
  name: 'all_tasks',
  label: 'All Tasks',
  type: 'grid',
  data: {
    provider: 'object',
    object: 'task',
  },
  columns: [
    { field: 'title', label: 'Title', width: 300 },
    { field: 'status', label: 'Status', width: 120 },
    { field: 'assignee', label: 'Assignee', width: 200 },
    { field: 'due_date', label: 'Due Date', width: 150 },
  ],
  filter: [],
  sort: [{ field: 'created_at', direction: 'desc' }],
};
```

### View Types

| Type | Description | Use Case |
| :--- | :--- | :--- |
| `grid` | Table/spreadsheet view | Default record listing |
| `kanban` | Card board grouped by field | Status-based workflows |
| `gallery` | Card grid with images | Visual content browsing |
| `calendar` | Calendar with date events | Scheduling and planning |
| `timeline` | Horizontal timeline | Project scheduling |
| `gantt` | Gantt chart with dependencies | Project management |
| `map` | Geographic map pins | Location-based data |

### List View Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | `string` | ✅ | Machine name (`snake_case`) |
| `label` | `string` | ✅ | Display label |
| `type` | `enum` | ✅ | View type (see table above) |
| `data` | `ViewData` | ✅ | Data source configuration |
| `columns` | `ListColumn[]` | optional | Column definitions |
| `filter` | `array` | optional | Filter criteria |
| `sort` | `array` | optional | Sort configuration |
| `searchableFields` | `string[]` | optional | Fields included in search |
| `filterableFields` | `string[]` | optional | Fields available for filtering |
| `grouping` | `object` | optional | Row grouping configuration |
| `pagination` | `object` | optional | Pagination settings |
| `selection` | `object` | optional | Row selection mode |
| `navigation` | `object` | optional | Row click navigation |
| `rowActions` | `array` | optional | Per-row action buttons |
| `bulkActions` | `array` | optional | Bulk selection actions |
| `inlineEdit` | `boolean` | optional | Enable inline editing |
| `exportOptions` | `object` | optional | Export configuration |

### Column Configuration

```typescript
columns: [
  {
    field: 'name',
    label: 'Account Name',
    width: 250,
    pinned: 'left',          // 'left' | 'right' — freeze column
    sortable: true,
    resizable: true,
    summary: {               // Column footer aggregation
      function: 'count',
    },
  },
  {
    field: 'annual_revenue',
    label: 'Revenue',
    width: 150,
    align: 'right',
    summary: {
      function: 'sum',
    },
  },
]
```

| Property | Type | Description |
| :--- | :--- | :--- |
| `field` | `string` | Field name |
| `label` | `string` | Display header |
| `width` | `number` | Column width in pixels |
| `hidden` | `boolean` | Hide column |
| `pinned` | `'left' \| 'right'` | Freeze column position |
| `sortable` | `boolean` | Allow column sorting |
| `resizable` | `boolean` | Allow column resize |
| `summary` | `object` | Footer aggregation (`count`, `sum`, `avg`, `min`, `max`) |
| `link` | `string` | Make cell a clickable link |

### Data Source

Views can load data from three sources:

```typescript
// From an Object (most common)
data: { provider: 'object', object: 'task' }

// From an external API
data: {
  provider: 'api',
  read: { url: '/api/external/tasks', method: 'GET' },
}

// Static values
data: {
  provider: 'value',
  items: [{ id: '1', name: 'Item 1' }],
}
```

### Type-Specific Configuration

#### Kanban

```typescript
type: 'kanban',
kanban: {
  groupByField: 'status',
  titleField: 'title',
  colorField: 'priority',
}
```

#### Calendar

```typescript
type: 'calendar',
calendar: {
  startDateField: 'start_date',
  endDateField: 'end_date',
  titleField: 'title',
  colorField: 'status',
}
```

#### Gantt

```typescript
type: 'gantt',
gantt: {
  startDateField: 'start_date',
  endDateField: 'end_date',
  titleField: 'title',
  progressField: 'percent_complete',
  dependenciesField: 'depends_on',
}
```

## Form View

A Form View defines how a single record is displayed for viewing or editing.

### Basic Structure

```typescript
const taskFormView = {
  type: 'simple',
  data: { provider: 'object', object: 'task' },
  sections: [
    {
      label: 'Basic Information',
      columns: 2,
      fields: [
        { field: 'title', colSpan: 2 },
        { field: 'status' },
        { field: 'priority' },
        { field: 'assignee' },
        { field: 'due_date' },
      ],
    },
    {
      label: 'Details',
      collapsible: true,
      columns: 1,
      fields: [
        { field: 'description', colSpan: 1 },
      ],
    },
  ],
};
```

### Form Types

| Type | Description |
| :--- | :--- |
| `simple` | Single-page form |
| `tabbed` | Form with tab navigation |
| `wizard` | Multi-step wizard |
| `split` | Split-pane layout |
| `drawer` | Side drawer form |
| `modal` | Modal dialog form |

### Section Configuration

| Property | Type | Description |
| :--- | :--- | :--- |
| `label` | `string` | Section header |
| `columns` | `1-4` | Grid column count |
| `collapsible` | `boolean` | Can section be collapsed |
| `collapsed` | `boolean` | Initially collapsed |
| `fields` | `FormField[]` | Fields in the section |

### Form Field Configuration

Each field in a form section can be customized:

```typescript
fields: [
  {
    field: 'title',
    label: 'Task Title',        // Override field label
    placeholder: 'Enter title',
    helpText: 'A brief description of the task',
    required: true,              // Override required
    colSpan: 2,                  // Span 2 grid columns
    widget: 'custom-editor',     // Custom widget component
    visibleOn: "status != 'cancelled'",
  },
]
```

| Property | Type | Description |
| :--- | :--- | :--- |
| `field` | `string` | Field name |
| `label` | `string` | Display label override |
| `placeholder` | `string` | Placeholder text |
| `helpText` | `string` | Help/hint text |
| `readonly` | `boolean` | Read-only override |
| `required` | `boolean` | Required override |
| `hidden` | `boolean` | Hidden override |
| `colSpan` | `1-4` | Column span in grid layout |
| `widget` | `string` | Custom widget/component name |
| `dependsOn` | `string` | Parent field for cascading |
| `visibleOn` | `string` | Visibility condition expression |

### Default Sort for Related Lists

```typescript
// Sort related records
defaultSort: [
  { field: 'created_at', direction: 'desc' },
]
```

## Complete Example

```typescript
// List view: Kanban board for tasks
const taskKanban = {
  name: 'task_board',
  label: 'Task Board',
  type: 'kanban',
  data: { provider: 'object', object: 'task' },
  kanban: {
    groupByField: 'status',
    titleField: 'title',
  },
  columns: [
    { field: 'title', label: 'Title' },
    { field: 'assignee', label: 'Assignee' },
    { field: 'priority', label: 'Priority' },
    { field: 'due_date', label: 'Due Date' },
  ],
  sort: [{ field: 'priority', direction: 'desc' }],
};

// Form view: Task edit form
const taskForm = {
  type: 'tabbed',
  data: { provider: 'object', object: 'task' },
  sections: [
    {
      label: 'Details',
      columns: 2,
      fields: [
        { field: 'title', colSpan: 2, required: true },
        { field: 'status' },
        { field: 'priority' },
        { field: 'assignee' },
        { field: 'due_date' },
        { field: 'description', colSpan: 2 },
      ],
    },
    {
      label: 'System',
      collapsible: true,
      collapsed: true,
      columns: 2,
      fields: [
        { field: 'created_at', readonly: true },
        { field: 'updated_at', readonly: true },
      ],
    },
  ],
};
```

## Related

- [Object Metadata](./object) — Define the data behind views
- [Field Metadata](./field) — Field types that views display
- [Page Metadata](./page) — Custom pages with component layouts
- [Dashboard Metadata](./dashboard) — Analytics dashboards with charts
