Views

A view is a saved configuration for how records of an object are displayed: which fields appear, their order, whether they're visible, and any filters or groups applied. Use defineView() to ship pre-configured views with your app — typically a default index view for each custom object you create.

import { defineView, ViewKey } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';

export default defineView({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'All example items',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  icon: 'IconList',
  key: ViewKey.INDEX,
  position: 0,
  fields: [
    {
      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
      position: 0,
      isVisible: true,
      size: 200,
    },
  ],
});

Key points

• objectUniversalIdentifier specifies which object this view applies to. It can be a custom object you defined or a standard Twenty object.
• key determines the view type — ViewKey.INDEX is the main list view for the object.
• fields controls which columns appear and in what order. Each field references a fieldMetadataUniversalIdentifier.
• You can also declare filters, filterGroups, groups, and fieldGroups for advanced configurations.
• position controls ordering when multiple views exist for the same object.

Filters

A view can ship with pre-applied filters. Each filter has three coordinates: the field being filtered, the operand (how to compare), and the value (what to compare against). All three must line up — using an operand that doesn't apply to a field type will be rejected at sync time.

import { ViewFilterOperand } from 'twenty-shared/types';

filters: [
  {
    universalIdentifier: '...',
    fieldMetadataUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
    operand: ViewFilterOperand.IS,
    value: ['ACTIVE'],
  },
],

Supported operands per field type

Field types with similar names can use entirely different operands — SELECT and MULTI_SELECT being a common case.

Value shape per operand

The value field is always a JSON-serializable value, but its expected shape depends on the operand:

How views show up in the UI

A view by itself isn't reachable from the sidebar. To make it appear there, pair it with a navigation menu item of type VIEW that points at the view's universalIdentifier. That's the canonical pattern: every custom object typically ships a default view + a sidebar entry that opens it.