# Lists

Lists are the primary way users browse and interact with records. As a developer, you control how lists look and behave through field options, cell renderers, and list configuration.

## List formats[​](#list-formats "Direct link to List formats")

The grid engine supports 14 representation formats:

| Format        | Description                                    |
| ------------- | ---------------------------------------------- |
| Table         | Standard data grid with sortable columns       |
| Gantt         | Timeline visualization with drag-to-reschedule |
| Boards        | Kanban-style columns grouped by a lookup field |
| Calendar      | Date-based event view                          |
| Pivot tables  | Cross-tabulation with aggregations             |
| Charts (Vega) | Custom data visualizations                     |
| Cards         | Card layout for visual browsing                |
| Word cloud    | Text frequency visualization                   |
| Google Maps   | Geographic data on a map                       |
| File folders  | File and folder navigation view                |
| Feed          | Activity stream layout                         |
| Resources     | Resource allocation view                       |
| Quick edit    | Inline editing                                 |
| Heatmap       | Color-coded data density view                  |

## Cell renderers[​](#cell-renderers "Direct link to Cell renderers")

Cell renderers control how field values appear in grid columns. Configure them using the `gridview_renderer` and `plain_renderer` field options.

### Built-in renderers (20+)[​](#built-in-renderers-20 "Direct link to Built-in renderers (20+)")

| Renderer             | Use case                                     |
| -------------------- | -------------------------------------------- |
| `circle_percent`     | Progress circles (0-100%)                    |
| `indicator`          | Status indicators with icons and colors      |
| `rich_text_line`     | Single-line rich text preview                |
| `colorful-lookup`    | Lookup values with custom colors             |
| `avatar-image`       | User avatar thumbnails                       |
| `work-progress-bar`  | Progress bars                                |
| State-colored badges | Lookup fields with per-entry color coding    |
| Boolean checkboxes   | Yes/no toggle display                        |
| Currency             | Formatted monetary values with prefix/suffix |
| Sparklines           | Inline mini-charts                           |
| Priority indicators  | Visual priority levels                       |
| Linked records       | Clickable cross-record references            |
| File previews        | Attachment thumbnails                        |
| Comments count       | Comment badge                                |
| HTML content         | Rendered HTML snippets                       |

### Configuring renderers[​](#configuring-renderers "Direct link to Configuring renderers")

Set renderers in your field definition using field options:

```
{
  name: "progress",
  type: "number",
  options: {
    gridview_renderer: "circle_percent",
    plain_renderer: "work-progress-bar"
  }
}
```

The `gridview_renderer` controls the list/grid cell appearance. The `plain_renderer` controls the read-only form view appearance.

### Renderer examples[​](#renderer-examples "Direct link to Renderer examples")

The `gridview_renderer` option controls how a field value appears in list and grid columns. The `plain_renderer` option controls how the same value appears in the read-only form view. You can set either or both depending on where you need custom rendering.

```
// Colored status indicator in grid
{
  name: 'c_status',
  dataType: 'lookup',
  textType: 'keyword',
  options: {
    gridview_renderer: 'indicator',
    lookup_entries_formatting: {
      active:  { bgColor: '#4caf50', textColor: '#fff' },
      pending: { bgColor: '#ff9800', textColor: '#fff' },
      closed:  { bgColor: '#9e9e9e', textColor: '#fff' },
    },
  },
}
```

```
// Progress bar in grid
{
  name: 'c_progress',
  dataType: 'number',
  numberType: 'integer',
  options: {
    gridview_renderer: 'circle_percent',
  },
}
```

```
// Avatar image from URL field
{
  name: 'c_photo',
  dataType: 'text',
  textType: 'string',
  options: {
    gridview_renderer: 'avatar-image',
  },
}
```

```
// Colorful lookup with per-entry styling
{
  name: 'c_priority',
  dataType: 'lookup',
  textType: 'keyword',
  options: {
    plain_renderer: 'colorful-lookup',
    lookup_entries_formatting: {
      critical: { bgColor: '#d32f2f', textColor: '#fff', icon: 'fa-fire' },
      high:     { bgColor: '#f57c00', textColor: '#fff' },
      normal:   { bgColor: '#1976d2', textColor: '#fff' },
      low:      { bgColor: '#757575', textColor: '#fff' },
    },
  },
}
```

### Lookup entry formatting[​](#lookup-entry-formatting "Direct link to Lookup entry formatting")

Customize colors, icons, and text colors for individual lookup values:

```
{
  name: "status",
  type: "lookup",
  options: {
    lookup_entries_formatting: {
      open: { color: "#4CAF50", icon: "circle", textColor: "#fff" },
      closed: { color: "#9E9E9E", icon: "check", textColor: "#fff" },
      blocked: { color: "#F44336", icon: "warning", textColor: "#fff" }
    }
  }
}
```

Localize lookup entry captions per language:

```
{
  options: {
    lookup_entries_localization: {
      open: { en: "Open", uk: "Відкрито", ru: "Открыто" }
    }
  }
}
```

## Filtering[​](#filtering "Direct link to Filtering")

### Relational expression syntax[​](#relational-expression-syntax "Direct link to Relational expression syntax")

Grid filters use a relational expression language:

```
state="open" AND priority>3
creation_date>="2026-01-01" AND assignee="John Smith"
(state="open" OR state="in_progress") AND priority>=2
```

### Faceted filtering[​](#faceted-filtering "Direct link to Faceted filtering")

Facets provide sidebar checkbox filters with record counts:

* **Lookup facets** - single-select checkboxes
* **Multi-select facets** - multiple selections
* **Date range facets** - calendar picker for date fields
* **Auto-generated facets** - created automatically from lookup and user fields, collapsed by default
* **User avatar facets** - show user photos next to names

Facets and the grid filter sync bidirectionally - changing one updates the other. Active filters display as chips above the grid.

### Quick filter[​](#quick-filter "Direct link to Quick filter")

Three search modes are available:

1. **Visible fields** - search only columns currently shown
2. **Include files/comments** - extend search to attachments and comments
3. **Everywhere** - full-text search across all fields

## Sorting and grouping[​](#sorting-and-grouping "Direct link to Sorting and grouping")

### Multi-level sorting[​](#multi-level-sorting "Direct link to Multi-level sorting")

Sort by multiple columns simultaneously. Set default sort order in list configuration.

### Grouping[​](#grouping "Direct link to Grouping")

Group rows by any field with date-based granularity options:

* Year, month, day, or hour for date fields
* Lookup values for categorical fields
* Nested grouping across multiple levels

## Inline editing[​](#inline-editing "Direct link to Inline editing")

Edit field values directly in grid cells without opening the record form. Supported for text, number, date, and lookup field types.

## Mass editing[​](#mass-editing "Direct link to Mass editing")

Bulk update fields across selected records:

1. Select records using checkboxes or Ctrl+click
2. Choose the target field and new value
3. Optionally fire an action on all selected records

## Real-time updates[​](#real-time-updates "Direct link to Real-time updates")

Lists refresh automatically when records change on the server. Grid rows update, appear, or disappear in real time - no manual refresh needed.

## Data export[​](#data-export "Direct link to Data export")

Export the current list view to XLSX (Excel) format. The export respects current filters and column selection.

## Virtual joins[​](#virtual-joins "Direct link to Virtual joins")

Display fields from linked records directly in grid columns without duplicating data. Virtual joins let you show related data inline:

## Importing list configurations[​](#importing-list-configurations "Direct link to Importing list configurations")

Import saved list views (filters, columns, sort order) using the CLI:

```
npx comind importCustomViews
```

## Keyboard shortcuts[​](#keyboard-shortcuts "Direct link to Keyboard shortcuts")

| Shortcut     | Action                 |
| ------------ | ---------------------- |
| Arrow keys   | Navigate between cells |
| Enter        | Open selected record   |
| E / F2       | Edit cell inline       |
| Delete       | Clear cell value       |
| Ctrl+A       | Select all records     |
| Ctrl+C       | Copy cell value        |
| Page Up/Down | Scroll by page         |

## Drag-and-drop[​](#drag-and-drop "Direct link to Drag-and-drop")

Reorder rows or restructure tree hierarchies by dragging. The platform validates drop targets to prevent invalid parent-child relationships.

For user-facing documentation on lists, views, and visualization formats, see [About lists](/user-guide/app-records-list/about-lists.md) in the user guide.

## Visual customization[​](#visual-customization "Direct link to Visual customization")

### Conditional formatting with lookup entries[​](#conditional-formatting-with-lookup-entries "Direct link to Conditional formatting with lookup entries")

The most common way to add visual cues is through `lookup_entries_formatting` on lookup fields. This applies colors and icons automatically in both grid cells and form views:

```
{
  name: 'c_risk_level',
  dataType: 'lookup',
  textType: 'keyword',
  options: {
    gridview_renderer: 'colorful-lookup',
    lookup_entries_formatting: {
      high:   { bgColor: '#d32f2f', textColor: '#fff', icon: 'fa-exclamation-triangle' },
      medium: { bgColor: '#f57c00', textColor: '#fff' },
      low:    { bgColor: '#4caf50', textColor: '#fff' },
    },
  },
}
```

This approach is preferred over custom CSS because it is declarative, portable across environments, and does not require front-end code.

### Custom CSS[​](#custom-css "Direct link to Custom CSS")

For styling beyond what renderers and lookup formatting provide, you can inject custom CSS through the app's client-side code. Common uses include custom fonts, row highlighting, or column width overrides.

CSS loading order

Custom CSS may cause a brief visual flicker on page load if styles are applied after the grid renders. To minimize this, keep CSS rules targeted (use specific class selectors rather than broad element selectors) and avoid large font or layout changes that trigger re-rendering.

## Widgets[​](#widgets "Direct link to Widgets")

Embed grid instances in dashboard or wiki pages with configurable max rows.