Layout

Concept	What it controls	Entity
View	A saved list configuration for an object — visible fields, order, filters, groups	`defineView`
Navigation Menu Item	An entry in the left sidebar that links to a view or an external URL	`defineNavigationMenuItem`
Page Layout	The tabs and widgets that make up a record’s detail page	`definePageLayout`

defineView

Define saved views for objects

Views are saved configurations for how records of an object are displayed — including which fields are visible, their order, and any filters or groups applied. Use defineView() to ship pre-configured views with your app:

src/views/example-view.ts

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.
key determines the view type (e.g., ViewKey.INDEX for the main list view).
fields controls which columns appear and their order. Each field references a fieldMetadataUniversalIdentifier.
You can also define filters, filterGroups, groups, and fieldGroups for more advanced configurations.
position controls the ordering when multiple views exist for the same object.

defineNavigationMenuItem

Define sidebar navigation links

Navigation menu items add custom entries to the workspace sidebar. Use defineNavigationMenuItem() to link to views, external URLs, or objects:

src/navigation-menu-items/example-navigation-menu-item.ts

import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';

export default defineNavigationMenuItem({
  universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
  name: 'example-navigation-menu-item',
  icon: 'IconList',
  color: 'blue',
  position: 0,
  type: NavigationMenuItemType.VIEW,
  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
});

Key points:

type determines what the menu item links to: NavigationMenuItemType.VIEW for a saved view, or NavigationMenuItemType.LINK for an external URL.
For view links, set viewUniversalIdentifier. For external links, set link.
position controls the ordering in the sidebar.
icon and color (optional) customize the appearance.

definePageLayout

Define custom page layouts for record views

Page layouts let you customize how a record detail page looks — which tabs appear, what widgets are inside each tab, and how they are arranged. Use definePageLayout() to ship custom layouts with your app:

src/page-layouts/example-record-page-layout.ts

import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayout({
  universalIdentifier: '203aeb94-6701-46d6-9af1-be2bbcc9e134',
  name: 'Example Record Page',
  type: 'RECORD_PAGE',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  tabs: [
    {
      universalIdentifier: '6ed26b60-a51d-4ad7-86dd-1c04c7f3cac5',
      title: 'Hello World',
      position: 50,
      icon: 'IconWorld',
      layoutMode: PageLayoutTabLayoutMode.CANVAS,
      widgets: [
        {
          universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
          title: 'Hello World',
          type: 'FRONT_COMPONENT',
          configuration: {
            configurationType: 'FRONT_COMPONENT',
            frontComponentUniversalIdentifier:
              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
          },
        },
      ],
    },
  ],
});

Key points:

type is typically 'RECORD_PAGE' to customize the detail view of a specific object.
objectUniversalIdentifier specifies which object this layout applies to.
Each tab defines a section of the page with a title, position, and layoutMode (CANVAS for free-form layout).
Each widget inside a tab can render a front component, a relation list, or other built-in widget types.
position on tabs controls their order. Use higher values (e.g., 50) to place custom tabs after built-in ones.

Overview

Apps

API

Self-Host

Contribute

Layout concepts

​Layout concepts

Layout concepts