Front Components - Twenty Documentation

Front components are React components that render directly inside Twenty’s UI. They run in an isolated Web Worker using Remote DOM — your code is sandboxed but renders natively in the page, not in an iframe.

Where front components can be used

Front components can render in two locations within Twenty:

Side panel — Non-headless front components open in the right-hand side panel. This is the default behavior when a front component is triggered from the command menu.
Widgets (dashboards and record pages) — Front components can be embedded as widgets inside page layouts. When configuring a dashboard or a record page layout, users can add a front component widget.

A front component on its own isn’t reachable from the UI — you need to surface it. The two ways to do that are:

Pair it with a command menu item — registers it in the command menu (Cmd+K) and, optionally, as a pinned quick-action.
Embed it as a widget in a page layout — places it on a record’s detail page or dashboard.

Basic example

The quickest way to see a front component in action is to pair it with a defineCommandMenuItem, so it appears as a quick-action button in the top-right corner of the page:

src/front-components/hello-world.tsx

import { defineFrontComponent } from 'twenty-sdk/define';

const HelloWorld = () => {
  return (
    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
      <h1>Hello from my app!</h1>
      <p>This component renders inside Twenty.</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
  name: 'hello-world',
  description: 'A simple front component',
  component: HelloWorld,
});

src/command-menu-items/hello-world.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
  shortLabel: 'Hello',
  label: 'Hello World',
  icon: 'IconBolt',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});

After syncing with yarn twenty dev (or running a one-shot yarn twenty dev --once), the quick action appears in the top-right corner of the page:

Quick action button in the top-right corner

Click it to render the component inline.

Configuration fields

Field	Required	Description
`universalIdentifier`	Yes	Stable unique ID for this component
`component`	Yes	A React component function
`name`	No	Display name
`description`	No	Description of what the component does
`isHeadless`	No	Set to `true` if the component has no visible UI (see below)

Placing a front component on a page

Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a page layout. See Page Layouts for details.

Headless vs non-headless

Front components come in two rendering modes controlled by the isHeadless option: Non-headless (default) — The component renders a visible UI. When triggered from the command menu it opens in the side panel. This is the default behavior when isHeadless is false or omitted. Headless (isHeadless: true) — The component mounts invisibly in the background. It does not open the side panel. Headless components are designed for actions that execute logic and then unmount themselves — for example, running an async task, navigating to a page, or showing a confirmation modal. They pair naturally with the SDK Command components described below.

src/front-components/sync-tracker.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
import { useEffect } from 'react';

const SyncTracker = () => {
  const recordId = useRecordId();

  useEffect(() => {
    enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
  }, [recordId]);

  return null;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-tracker',
  description: 'Tracks record views silently',
  isHeadless: true,
  component: SyncTracker,
});

Because the component returns null, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.

SDK Command components

The twenty-sdk package provides four Command helper components designed for headless front components. Each component executes an action on mount, handles errors by showing a snackbar notification, and automatically unmounts the front component when done. Import them from twenty-sdk/command:

Command — Runs an async callback via the execute prop.
CommandLink — Navigates to an app path. Props: to, params, queryParams, options.
CommandModal — Opens a confirmation modal. If the user confirms, executes the execute callback. Props: title, subtitle, execute, confirmButtonText, confirmButtonAccent.
CommandOpenSidePanelPage — Opens a specific side panel page. Props: page, pageTitle, pageIcon.

Here is a full example of a headless front component using Command to run an action from the command menu:

src/front-components/run-action.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/command';
import { CoreApiClient } from 'twenty-sdk/clients';

const RunAction = () => {
  const execute = async () => {
    const client = new CoreApiClient();

    await client.mutation({
      createTask: {
        __args: { data: { title: 'Created by my app' } },
        id: true,
      },
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
  name: 'run-action',
  description: 'Creates a task from the command menu',
  component: RunAction,
  isHeadless: true,
});

src/command-menu-items/run-action.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
  label: 'Run my action',
  icon: 'IconPlayerPlay',
  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
});

And an example using CommandModal to ask for confirmation before executing:

src/front-components/delete-draft.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { CommandModal } from 'twenty-sdk/command';

const DeleteDraft = () => {
  const execute = async () => {
    // perform the deletion
  };

  return (
    <CommandModal
      title="Delete draft?"
      subtitle="This action cannot be undone."
      execute={execute}
      confirmButtonText="Delete"
      confirmButtonAccent="danger"
    />
  );
};

export default defineFrontComponent({
  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
  name: 'delete-draft',
  description: 'Deletes a draft with confirmation',
  component: DeleteDraft,
  isHeadless: true,
});

Calling a logic function

Front components run browser-side in a sandboxed Web Worker, while logic functions run server-side. There is no direct in-process call between the two — instead, a front component reaches a logic function over HTTP. A logic function declared with httpRouteTriggerSettings is exposed under the /s/ endpoint at ${TWENTY_API_URL}/s<path>. Your front component calls that route with the RestApiClient from twenty-client-sdk/rest, which authenticates with the TWENTY_APP_ACCESS_TOKEN that Twenty injects into the worker. The RestApiClient is built for exactly this. It reads TWENTY_API_URL and TWENTY_APP_ACCESS_TOKEN from the worker environment, attaches the Authorization: Bearer header, serializes and parses JSON, and throws a RestApiClientError when the token or URL is missing or the response is non-2xx — so you don’t reimplement that boilerplate in every component. A headless front component can run the call on mount via the Command component, then unmount automatically:

src/front-components/sync-prs.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/command';
import { RestApiClient } from 'twenty-client-sdk/rest';

const SyncPrs = () => {
  const execute = async () => {
    const client = new RestApiClient();

    await client.post('/s/github/fetch-prs', {
      owner: 'twentyhq',
      repo: 'twenty',
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-prs',
  description: 'Triggers the fetch-prs logic function',
  isHeadless: true,
  component: SyncPrs,
});

The path passed to the client is the route’s public path — the logic function’s httpRouteTriggerSettings.path prefixed with /s. Keep isAuthRequired: true; the client supplies the app access token Twenty mints for your component:

src/logic-functions/fetch-prs.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import type { RoutePayload } from 'twenty-sdk/logic-function';

const handler = async (event: RoutePayload) => {
  const { owner, repo } = (event.body ?? {}) as { owner: string; repo: string };
  // ...fetch from GitHub and persist records...
  return { ok: true };
};

export default defineLogicFunction({
  universalIdentifier: '...',
  name: 'fetch-prs',
  handler,
  httpRouteTriggerSettings: {
    path: '/github/fetch-prs',
    httpMethod: 'POST',
    isAuthRequired: true,
  },
});

TWENTY_API_URL and TWENTY_APP_ACCESS_TOKEN are injected automatically — see Application variables. Because secret application variables are never exposed to front components, keep API keys and other sensitive logic in the logic function, not in the front component.

RestApiClient reference

Import RestApiClient from twenty-client-sdk/rest. It belongs to the same client family as CoreApiClient and MetadataApiClient, but targets your app’s HTTP routes instead of the GraphQL API.

Method	Description
`get(path, options?)`	Sends a `GET` request
`post(path, body?, options?)`	Sends a `POST` request
`put(path, body?, options?)`	Sends a `PUT` request
`patch(path, body?, options?)`	Sends a `PATCH` request
`delete(path, options?)`	Sends a `DELETE` request
`request(method, path, options?)`	Generic request with any HTTP method

options accepts headers, query (a record of query-string params; nullish values are skipped), and an AbortSignal via signal. A non-FormData object body is JSON-serialized automatically. On a 401, the client refreshes the access token once through the host and retries the request. The base URL and token are resolved from the environment by default. Pass overrides to the constructor when needed — for example in tests:

const client = new RestApiClient({
  baseUrl: 'https://api.example.com',
  token: 'my-token',
});

Failed requests throw a RestApiClientError exposing status, statusText, url, and the parsed body:

import { RestApiClient, RestApiClientError } from 'twenty-client-sdk/rest';

const client = new RestApiClient();

try {
  const prs = await client.get('/s/github/fetch-prs', {
    query: { state: 'open' },
  });
} catch (error) {
  if (error instanceof RestApiClientError) {
    console.error(error.status, error.body);
  }
}

Accessing runtime context

Inside your component, use SDK hooks to access the current user, record, and component instance:

src/front-components/record-info.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import {
  useUserId,
  useRecordId,
  useFrontComponentId,
} from 'twenty-sdk/front-component';

const RecordInfo = () => {
  const userId = useUserId();
  const recordId = useRecordId();
  const componentId = useFrontComponentId();

  return (
    <div>
      <p>User: {userId}</p>
      <p>Record: {recordId ?? 'No record context'}</p>
      <p>Component: {componentId}</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
  name: 'record-info',
  component: RecordInfo,
});

Available hooks:

Hook	Returns	Description
`useUserId()`	`string` or `null`	The current user’s ID
`useSelectedRecordIds()`	`string[]`	All selected record IDs (empty array if none selected)
`useRecordId()`	`string` or `null`	Deprecated. Use `useSelectedRecordIds()` instead
`useFrontComponentId()`	`string`	This component instance’s ID
`useColorScheme()`	`'light'` or `'dark'`	The host UI’s active color scheme (`System` is already resolved)
`useFrontComponentExecutionContext(selector)`	varies	Access the full execution context with a selector function

Application variables

Application variables defined in defineApplication() with isSecret: false are available inside front components via the getApplicationVariable utility:

src/front-components/greeting.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { getApplicationVariable } from 'twenty-sdk/front-component';

const Greeting = () => {
  const recipientName = getApplicationVariable('DEFAULT_RECIPIENT_NAME') ?? 'World';

  return <p>Hello, {recipientName}!</p>;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'greeting',
  component: Greeting,
});

Secret variables (isSecret: true) are not exposed to front components. They are only available in logic functions, which run server-side. This prevents sensitive values like API keys from being sent to the browser.

The following system variables are always available via process.env:

Variable	Description
`TWENTY_API_URL`	Base URL of the Twenty API
`TWENTY_APP_ACCESS_TOKEN`	Short-lived token scoped to your app’s role

Host communication API

Front components can trigger navigation, modals, and notifications using functions from twenty-sdk:

Function	Description
`navigate(to, params?, queryParams?, options?)`	Navigate to a page in the app
`openSidePanelPage(params)`	Open a side panel
`closeSidePanel()`	Close the side panel
`openCommandConfirmationModal(params)`	Show a confirmation dialog
`enqueueSnackbar(params)`	Show a toast notification
`unmountFrontComponent()`	Unmount the component
`updateProgress(progress)`	Update a progress indicator

Here is an example that uses the host API to show a snackbar and close the side panel after an action completes:

src/front-components/archive-record.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { useRecordId } from 'twenty-sdk/front-component';
import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-sdk/clients';

const ArchiveRecord = () => {
  const recordId = useRecordId();

  const handleArchive = async () => {
    const client = new CoreApiClient();

    await client.mutation({
      updateTask: {
        __args: { id: recordId, data: { status: 'ARCHIVED' } },
        id: true,
      },
    });

    await enqueueSnackbar({
      message: 'Record archived',
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Archive this record?</p>
      <button onClick={handleArchive}>Archive</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
  name: 'archive-record',
  description: 'Archives the current record',
  component: ArchiveRecord,
});

Working with multiple records

Use useSelectedRecordIds() to handle multiple selected records. This is useful for bulk operations:

src/front-components/bulk-export.tsx

import { defineFrontComponent, numberOfSelectedRecords } from 'twenty-sdk/define';
import { useSelectedRecordIds } from 'twenty-sdk/front-component';
import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-sdk/clients';

const BulkExport = () => {
  const selectedRecordIds = useSelectedRecordIds();

  const handleExport = async () => {
    const client = new CoreApiClient();

    for (const recordId of selectedRecordIds) {
      await client.mutation({
        updateTask: {
          __args: { id: recordId, data: { exported: true } },
          id: true,
        },
      });
    }

    await enqueueSnackbar({
      message: `Exported ${selectedRecordIds.length} records`,
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Export {selectedRecordIds.length} selected record(s)?</p>
      <button onClick={handleExport}>Export</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
  name: 'bulk-export',
  description: 'Export selected records',
  component: BulkExport,
  command: {
    universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
    label: 'Bulk Export',
    availabilityType: 'RECORD_SELECTION',
    conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
  },
});

Public assets

Front components can access files from the app’s public/ directory using getPublicAssetUrl:

import { defineFrontComponent } from 'twenty-sdk/define';
import { getPublicAssetUrl } from 'twenty-sdk/utils';

const Logo = () => <img src={getPublicAssetUrl('logo.png')} alt="Logo" />;

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'logo',
  component: Logo,
});

See the public assets section for details.

Styling

Front components support multiple styling approaches. You can use:

Inline styles — style={{ color: 'red' }}
Twenty UI components — import from twenty-sdk/ui (Button, Tag, Status, Chip, Avatar, and more)
Emotion — CSS-in-JS with @emotion/react
Styled-components — styled.div patterns
Tailwind CSS — utility classes
Any CSS-in-JS library compatible with React

import { defineFrontComponent } from 'twenty-sdk/define';
import { Button, Tag, Status } from 'twenty-sdk/ui';

const StyledWidget = () => {
  return (
    <div style={{ padding: '16px', display: 'flex', gap: '8px' }}>
      <Button title="Click me" onClick={() => alert('Clicked!')} />
      <Tag text="Active" color="green" />
      <Status color="green" text="Online" />
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
  name: 'styled-widget',
  component: StyledWidget,
});

​Where front components can be used

​Basic example

​Configuration fields

​Placing a front component on a page

​Headless vs non-headless

​SDK Command components

​Calling a logic function

​RestApiClient reference

​Accessing runtime context

​Application variables

​Host communication API

​Working with multiple records

​Public assets

​Styling

Where front components can be used

Basic example

Configuration fields

Placing a front component on a page

Headless vs non-headless

SDK Command components

Calling a logic function

RestApiClient reference

Accessing runtime context

Application variables

Host communication API

Working with multiple records

Public assets

Styling