Skip to content

The open alternative to Salesforce, designed for AI.

Remove the record creation form feature flag (#29246)

Weikoa3c264550055
diff --git a/packages/twenty-client-sdk/src/metadata/generated/schema.graphql b/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
index f8f5621b93b..6be373c338d 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
+++ b/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
@@ -2328,7 +2328,6 @@ enum FeatureFlagKey {
IS_GETTING_STARTED_ENABLED
IS_MCP_SERVERS_ENABLED
IS_PRIVATE_RECORD_ENABLED
- IS_RECORD_CREATION_FORM_ENABLED
IS_RECORD_LEVEL_SHARING_ENABLED
IS_RELATED_RECORD_PATHS_ENABLED
IS_REST_METADATA_API_NEW_FORMAT_DIRECT
diff --git a/packages/twenty-client-sdk/src/metadata/generated/schema.ts b/packages/twenty-client-sdk/src/metadata/generated/schema.ts
index 35a38b50fa1..fa67dd7c343 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/schema.ts
+++ b/packages/twenty-client-sdk/src/metadata/generated/schema.ts
@@ -1528,7 +1528,7 @@ export interface FeatureFlag {
__typename: 'FeatureFlag'
}
-export type FeatureFlagKey = 'IS_AI_CHAT_COMPONENT_BUILDER_ENABLED' | 'IS_AI_CHAT_INBOX_ENABLED' | 'IS_APP_PREFERENCES_ENABLED' | 'IS_CALENDAR_EVENT_SHARED_ACROSS_CHANNELS_ENABLED' | 'IS_CONFIGURABLE_SEARCH_FIELDS_ENABLED' | 'IS_GETTING_STARTED_ENABLED' | 'IS_MCP_SERVERS_ENABLED' | 'IS_PRIVATE_RECORD_ENABLED' | 'IS_RECORD_CREATION_FORM_ENABLED' | 'IS_RECORD_LEVEL_SHARING_ENABLED' | 'IS_RELATED_RECORD_PATHS_ENABLED' | 'IS_REST_METADATA_API_NEW_FORMAT_DIRECT' | 'IS_ROW_LEVEL_PERMISSION_RELATION_HOP_ENABLED'
+export type FeatureFlagKey = 'IS_AI_CHAT_COMPONENT_BUILDER_ENABLED' | 'IS_AI_CHAT_INBOX_ENABLED' | 'IS_APP_PREFERENCES_ENABLED' | 'IS_CALENDAR_EVENT_SHARED_ACROSS_CHANNELS_ENABLED' | 'IS_CONFIGURABLE_SEARCH_FIELDS_ENABLED' | 'IS_GETTING_STARTED_ENABLED' | 'IS_MCP_SERVERS_ENABLED' | 'IS_PRIVATE_RECORD_ENABLED' | 'IS_RECORD_LEVEL_SHARING_ENABLED' | 'IS_RELATED_RECORD_PATHS_ENABLED' | 'IS_REST_METADATA_API_NEW_FORMAT_DIRECT' | 'IS_ROW_LEVEL_PERMISSION_RELATION_HOP_ENABLED'
export interface Field {
applicationId: Scalars['UUID']
@@ -12539,7 +12539,6 @@ export const enumFeatureFlagKey = {
IS_GETTING_STARTED_ENABLED: 'IS_GETTING_STARTED_ENABLED' as const,
IS_MCP_SERVERS_ENABLED: 'IS_MCP_SERVERS_ENABLED' as const,
IS_PRIVATE_RECORD_ENABLED: 'IS_PRIVATE_RECORD_ENABLED' as const,
- IS_RECORD_CREATION_FORM_ENABLED: 'IS_RECORD_CREATION_FORM_ENABLED' as const,
IS_RECORD_LEVEL_SHARING_ENABLED: 'IS_RECORD_LEVEL_SHARING_ENABLED' as const,
IS_RELATED_RECORD_PATHS_ENABLED: 'IS_RELATED_RECORD_PATHS_ENABLED' as const,
IS_REST_METADATA_API_NEW_FORMAT_DIRECT: 'IS_REST_METADATA_API_NEW_FORMAT_DIRECT' as const,
diff --git a/packages/twenty-front/src/generated-admin/schema.ts b/packages/twenty-front/src/generated-admin/schema.ts
index 029eebc724c..4a20af0dbbd 100644
--- a/packages/twenty-front/src/generated-admin/schema.ts
+++ b/packages/twenty-front/src/generated-admin/schema.ts
@@ -545,7 +545,6 @@ export enum FeatureFlagKey {
IS_GETTING_STARTED_ENABLED = 'IS_GETTING_STARTED_ENABLED',
IS_MCP_SERVERS_ENABLED = 'IS_MCP_SERVERS_ENABLED',
IS_PRIVATE_RECORD_ENABLED = 'IS_PRIVATE_RECORD_ENABLED',
- IS_RECORD_CREATION_FORM_ENABLED = 'IS_RECORD_CREATION_FORM_ENABLED',
IS_RECORD_LEVEL_SHARING_ENABLED = 'IS_RECORD_LEVEL_SHARING_ENABLED',
IS_RELATED_RECORD_PATHS_ENABLED = 'IS_RELATED_RECORD_PATHS_ENABLED',
IS_REST_METADATA_API_NEW_FORMAT_DIRECT = 'IS_REST_METADATA_API_NEW_FORMAT_DIRECT',
diff --git a/packages/twenty-front/src/generated-metadata/schema.ts b/packages/twenty-front/src/generated-metadata/schema.ts
index 16a8334f59b..8a11619dd65 100644
--- a/packages/twenty-front/src/generated-metadata/schema.ts
+++ b/packages/twenty-front/src/generated-metadata/schema.ts
@@ -2460,7 +2460,6 @@ export enum FeatureFlagKey {
IS_GETTING_STARTED_ENABLED = 'IS_GETTING_STARTED_ENABLED',
IS_MCP_SERVERS_ENABLED = 'IS_MCP_SERVERS_ENABLED',
IS_PRIVATE_RECORD_ENABLED = 'IS_PRIVATE_RECORD_ENABLED',
- IS_RECORD_CREATION_FORM_ENABLED = 'IS_RECORD_CREATION_FORM_ENABLED',
IS_RECORD_LEVEL_SHARING_ENABLED = 'IS_RECORD_LEVEL_SHARING_ENABLED',
IS_RELATED_RECORD_PATHS_ENABLED = 'IS_RELATED_RECORD_PATHS_ENABLED',
IS_REST_METADATA_API_NEW_FORMAT_DIRECT = 'IS_REST_METADATA_API_NEW_FORMAT_DIRECT',
diff --git a/packages/twenty-front/src/modules/command-menu-item/engine-command/record/no-selection/components/CreateNewIndexRecordNoSelectionRecordCommand.tsx b/packages/twenty-front/src/modules/command-menu-item/engine-command/record/no-selection/components/CreateNewIndexRecordNoSelectionRecordCommand.tsx
index d6e40092165..3e4e941ecb4 100644
--- a/packages/twenty-front/src/modules/command-menu-item/engine-command/record/no-selection/components/CreateNewIndexRecordNoSelectionRecordCommand.tsx
+++ b/packages/twenty-front/src/modules/command-menu-item/engine-command/record/no-selection/components/CreateNewIndexRecordNoSelectionRecordCommand.tsx
@@ -2,8 +2,6 @@ import { HeadlessEngineCommandWrapperEffect } from '@/command-menu-item/engine-c
import { useHeadlessCommandContextApi } from '@/command-menu-item/engine-command/hooks/useHeadlessCommandContextApi';
import { getToastOptionsFromError } from '@/error-handler/utils/getToastOptionsFromError';
import { useCreateNewIndexRecord } from '@/object-record/record-table/hooks/useCreateNewIndexRecord';
-import { useIsFeatureEnabled } from '@/workspace/hooks/useIsFeatureEnabled';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
import { doNotTranslate } from 'twenty-shared/i18n';
import { useToast } from 'twenty-ui/components/feedback';
@@ -11,10 +9,6 @@ import { useToast } from 'twenty-ui/components/feedback';
export const CreateNewIndexRecordNoSelectionRecordCommand = () => {
const { objectMetadataItem, recordIndexId } = useHeadlessCommandContextApi();
- const isRecordCreationFormEnabled = useIsFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- );
-
const { enqueueToast } = useToast();
if (!isDefined(objectMetadataItem) || !isDefined(recordIndexId)) {
@@ -32,13 +26,10 @@ export const CreateNewIndexRecordNoSelectionRecordCommand = () => {
return (
<HeadlessEngineCommandWrapperEffect
- execute={
- isRecordCreationFormEnabled
- ? () =>
- void createNewIndexRecord({ position: 'first' }).catch((error) =>
- enqueueToast(getToastOptionsFromError({ error })),
- )
- : () => createNewIndexRecord({ position: 'first' })
+ execute={() =>
+ void createNewIndexRecord({ position: 'first' }).catch((error) =>
+ enqueueToast(getToastOptionsFromError({ error })),
+ )
}
/>
);
diff --git a/packages/twenty-front/src/modules/command-menu-item/hooks/useGlobalRecordCreationCommandMenuItems.ts b/packages/twenty-front/src/modules/command-menu-item/hooks/useGlobalRecordCreationCommandMenuItems.ts
index 9651dfb7cd8..6b5ed20d08e 100644
--- a/packages/twenty-front/src/modules/command-menu-item/hooks/useGlobalRecordCreationCommandMenuItems.ts
+++ b/packages/twenty-front/src/modules/command-menu-item/hooks/useGlobalRecordCreationCommandMenuItems.ts
@@ -2,14 +2,10 @@ import { buildGlobalRecordCreationCommandMenuItems } from '@/command-menu-item/u
import { type CommandMenuItemDefinition } from '@/command-menu-item/types/CommandMenuItemDefinition';
import { useFilteredObjectMetadataItems } from '@/object-metadata/hooks/useFilteredObjectMetadataItems';
import { useObjectPermissions } from '@/object-record/hooks/useObjectPermissions';
-import { useIsFeatureEnabled } from '@/workspace/hooks/useIsFeatureEnabled';
import { useLingui } from '@lingui/react/macro';
import { useMemo } from 'react';
import { isDefined } from 'twenty-shared/utils';
-import {
- EngineComponentKey,
- FeatureFlagKey,
-} from '~/generated-metadata/graphql';
+import { EngineComponentKey } from '~/generated-metadata/graphql';
export const useGlobalRecordCreationCommandMenuItems = (
commandMenuItems: CommandMenuItemDefinition[],
@@ -17,19 +13,15 @@ export const useGlobalRecordCreationCommandMenuItems = (
const { t } = useLingui();
const { activeObjectMetadataItems } = useFilteredObjectMetadataItems();
const { objectPermissionsByObjectMetadataId } = useObjectPermissions();
- const isRecordCreationFormEnabled = useIsFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- );
const createRecordCommand = commandMenuItems.find(
(item) =>
item.engineComponentKey === EngineComponentKey.CREATE_NEW_RECORD &&
!isDefined(item.availabilityObjectMetadataId),
);
- const hasGlobalRecordCreationCommandTemplate =
- isRecordCreationFormEnabled && isDefined(createRecordCommand);
+ const hasGlobalRecordCreationCommandTemplate = isDefined(createRecordCommand);
const globalRecordCreationCommandMenuItems = useMemo(() => {
- if (!isRecordCreationFormEnabled || !isDefined(createRecordCommand)) {
+ if (!isDefined(createRecordCommand)) {
return [];
}
@@ -40,7 +32,6 @@ export const useGlobalRecordCreationCommandMenuItems = (
getLabel: (objectLabelSingular) => t`Create ${objectLabelSingular}`,
});
}, [
- isRecordCreationFormEnabled,
createRecordCommand,
activeObjectMetadataItems,
objectPermissionsByObjectMetadataId,
diff --git a/packages/twenty-front/src/modules/object-record/hooks/useCreateNewRecord.ts b/packages/twenty-front/src/modules/object-record/hooks/useCreateNewRecord.ts
index 5ebfe768786..b8d87ba324c 100644
--- a/packages/twenty-front/src/modules/object-record/hooks/useCreateNewRecord.ts
+++ b/packages/twenty-front/src/modules/object-record/hooks/useCreateNewRecord.ts
@@ -46,7 +46,7 @@ export const useCreateNewRecord = ({
const { upsertRecordsInStore } = useUpsertRecordsInStore();
- const { createRecordWithOptionalForm } = useRecordCreationForm();
+ const { requestRecordCreation } = useRecordCreationForm();
const navigate = useNavigateApp();
@@ -93,7 +93,7 @@ export const useCreateNewRecord = ({
async (recordInput?: Partial<ObjectRecord>) => {
let submittedRecordInput = recordInput;
- const createdRecord = await createRecordWithOptionalForm({
+ const createdRecord = await requestRecordCreation({
objectMetadataItem,
initialDraftRecord: {
...buildRecordInputFromRLSPredicates(),
@@ -167,7 +167,7 @@ export const useCreateNewRecord = ({
openRecordIn,
closeSidePanelMenu,
workspaceSurface.type,
- createRecordWithOptionalForm,
+ requestRecordCreation,
],
);
diff --git a/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/__tests__/useCreateJunctionRecordWithNestedTarget.test.tsx b/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/__tests__/useCreateJunctionRecordWithNestedTarget.test.tsx
index e81e47acb87..ef03f5e581f 100644
--- a/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/__tests__/useCreateJunctionRecordWithNestedTarget.test.tsx
+++ b/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/__tests__/useCreateJunctionRecordWithNestedTarget.test.tsx
@@ -19,7 +19,6 @@ import {
sidePanelNavigationStackState,
type SidePanelNavigationStackItem,
} from '@/side-panel/states/sidePanelNavigationStackState';
-import { useIsFeatureEnabled } from '@/workspace/hooks/useIsFeatureEnabled';
import { getMockFieldMetadataItemOrThrow } from '~/testing/utils/getMockFieldMetadataItemOrThrow';
import { getMockObjectMetadataItemOrThrow } from '~/testing/utils/getMockObjectMetadataItemOrThrow';
import { getTestEnrichedObjectMetadataItemsMock } from '~/testing/utils/getTestEnrichedObjectMetadataItemsMock';
@@ -29,7 +28,6 @@ jest.mock('@/object-record/hooks/useBuildRecordInputFromRLSPredicates');
jest.mock('@/object-record/hooks/useCreateOneRecord', () => ({
useCreateOneRecord: jest.fn(),
}));
-jest.mock('@/workspace/hooks/useIsFeatureEnabled');
const mockNavigateSidePanelMenu = jest.fn();
@@ -125,7 +123,6 @@ const setup = () => {
beforeEach(() => {
jest.clearAllMocks();
jest.mocked(useObjectMetadataItems).mockReturnValue({ objectMetadataItems });
- jest.mocked(useIsFeatureEnabled).mockReturnValue(true);
jest.mocked(useBuildRecordInputFromRLSPredicates).mockReturnValue({
buildRecordInputFromRLSPredicates: () => ({}),
});
@@ -207,22 +204,3 @@ it('creates and links a target for each submission, including Create another', a
isMatchingSearchFilter: true,
});
});
-
-it('creates and links the target right away when the form flag is off', async () => {
- jest.mocked(useIsFeatureEnabled).mockReturnValue(false);
- const { result } = setup();
-
- await act(async () => {
- await result.current.createJunctionRecordWithNestedTarget({
- searchInput: 'Quick task',
- targetObjectMetadataItemId: taskMetadata.id,
- });
- });
-
- expect(mockNavigateSidePanelMenu).not.toHaveBeenCalled();
- expect(mockCreateJunctionRecord).toHaveBeenCalledWith({
- id: expect.any(String),
- targetRocketId: 'rocket-id',
- task: { create: { id: expect.any(String), title: 'Quick task' } },
- });
-});
diff --git a/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/useCreateJunctionRecordWithNestedTarget.ts b/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/useCreateJunctionRecordWithNestedTarget.ts
index 6403b86a8ee..0332b216a9a 100644
--- a/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/useCreateJunctionRecordWithNestedTarget.ts
+++ b/packages/twenty-front/src/modules/object-record/record-field/ui/hooks/useCreateJunctionRecordWithNestedTarget.ts
@@ -38,7 +38,7 @@ export const useCreateJunctionRecordWithNestedTarget = ({
const [isCreatePending, setIsCreatePending] = useState(false);
const { objectMetadataItems } = useObjectMetadataItems();
const { enqueueToast } = useToast();
- const { createRecordWithOptionalForm } = useRecordCreationForm();
+ const { requestRecordCreation } = useRecordCreationForm();
const { buildRecordInputFromRLSPredicates } =
useBuildRecordInputFromRLSPredicates();
const { createOneRecord: createJunctionRecord } = useCreateOneRecord({
@@ -121,7 +121,7 @@ export const useCreateJunctionRecordWithNestedTarget = ({
setIsCreatePending(true);
try {
- const targetRecord = await createRecordWithOptionalForm({
+ const targetRecord = await requestRecordCreation({
objectMetadataItem: targetObjectMetadataItem,
initialDraftRecord: {
...buildRecordInputFromRLSPredicates({
@@ -155,7 +155,7 @@ export const useCreateJunctionRecordWithNestedTarget = ({
[
buildRecordInputFromRLSPredicates,
createJunctionRecord,
- createRecordWithOptionalForm,
+ requestRecordCreation,
enqueueToast,
junctionConfig,
objectMetadataItems,
diff --git a/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/__tests__/useAddNewRecordAndOpenSidePanel.test.tsx b/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/__tests__/useAddNewRecordAndOpenSidePanel.test.tsx
index 5a2fd67b019..f8cddca8c23 100644
--- a/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/__tests__/useAddNewRecordAndOpenSidePanel.test.tsx
+++ b/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/__tests__/useAddNewRecordAndOpenSidePanel.test.tsx
@@ -1,4 +1,3 @@
-import { useObjectMetadataItems } from '@/object-metadata/hooks/useObjectMetadataItems';
import { useAddNewRecordAndOpenSidePanel } from '@/object-record/record-field/ui/meta-types/input/hooks/useAddNewRecordAndOpenSidePanel';
import { RecordCreationFormProvider } from '@/object-record/record-form/components/RecordCreationFormProvider';
import { useRecordCreationFormContextOrThrow } from '@/object-record/record-form/contexts/RecordCreationFormContext';
@@ -14,7 +13,6 @@ import { createStore, Provider } from 'jotai';
import { type ReactNode } from 'react';
import { getMockFieldMetadataItemOrThrow } from '~/testing/utils/getMockFieldMetadataItemOrThrow';
import { getMockObjectMetadataItemOrThrow } from '~/testing/utils/getMockObjectMetadataItemOrThrow';
-import { getTestEnrichedObjectMetadataItemsMock } from '~/testing/utils/getTestEnrichedObjectMetadataItemsMock';
const mockCreateOneRecord = jest.fn(
async (recordInput: Partial<ObjectRecord>) => recordInput,
@@ -22,9 +20,7 @@ const mockCreateOneRecord = jest.fn(
const mockUpdateOneRecord = jest.fn();
const mockOpenRecordInSidePanel = jest.fn();
const mockNavigateSidePanelMenu = jest.fn();
-let mockIsFeatureEnabled = true;
-jest.mock('@/object-metadata/hooks/useObjectMetadataItems');
jest.mock('@/object-record/hooks/useCreateOneRecord', () => ({
useCreateOneRecord: () => ({ createOneRecord: mockCreateOneRecord }),
}));
@@ -53,9 +49,6 @@ jest.mock('@/side-panel/hooks/useSidePanelMenu', () => ({
closeSidePanelMenu: jest.fn(),
}),
}));
-jest.mock('@/workspace/hooks/useIsFeatureEnabled', () => ({
- useIsFeatureEnabled: () => mockIsFeatureEnabled,
-}));
type Relation = {
sourceObject: string;
@@ -160,10 +153,6 @@ const setup = (relation: Relation) => {
beforeEach(() => {
jest.clearAllMocks();
- mockIsFeatureEnabled = true;
- jest.mocked(useObjectMetadataItems).mockReturnValue({
- objectMetadataItems: getTestEnrichedObjectMetadataItemsMock(),
- });
});
it('creates nothing when the form is cancelled', async () => {
@@ -294,18 +283,16 @@ it.each([
},
},
])(
- 'creates and opens the record right away for $relationLabel when the form flag is off',
+ 'opens the creation form for $relationLabel without a feature flag',
async ({ relation, searchInput, expectedRecordInput }) => {
- mockIsFeatureEnabled = false;
- const { result } = setup(relation);
+ const { start, submit } = setup(relation);
+ const creation = start(searchInput);
- let createdRecordId: string | undefined;
- await act(async () => {
- createdRecordId =
- await result.current.createNewRecordAndOpenSidePanel?.(searchInput);
- });
+ expect(mockNavigateSidePanelMenu).toHaveBeenCalled();
+ expect(mockCreateOneRecord).not.toHaveBeenCalled();
- expect(mockNavigateSidePanelMenu).not.toHaveBeenCalled();
+ await submit({ draftRecord: expectedRecordInput });
+ const createdRecordId = await creation;
expect(mockCreateOneRecord).toHaveBeenCalledWith({
id: createdRecordId,
...expectedRecordInput,
diff --git a/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/useAddNewRecordAndOpenSidePanel.ts b/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/useAddNewRecordAndOpenSidePanel.ts
index f3ce28a513d..ef9d479cce7 100644
--- a/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/useAddNewRecordAndOpenSidePanel.ts
+++ b/packages/twenty-front/src/modules/object-record/record-field/ui/meta-types/input/hooks/useAddNewRecordAndOpenSidePanel.ts
@@ -51,7 +51,7 @@ export const useAddNewRecordAndOpenSidePanel = ({
});
const { openRecordInSidePanel } = useOpenRecordInSidePanel();
- const { createRecordWithOptionalForm } = useRecordCreationForm();
+ const { requestRecordCreation } = useRecordCreationForm();
const apolloCoreClient = useApolloCoreClient();
@@ -103,7 +103,7 @@ export const useAddNewRecordAndOpenSidePanel = ({
attachRecord: shouldAttachToSourceRecord ? attachRecord : undefined,
});
- const createdRecord = await createRecordWithOptionalForm({
+ const createdRecord = await requestRecordCreation({
objectMetadataItem: relationObjectMetadataItem,
initialDraftRecord: {
...buildRecordInputFromRLSPredicates(),
diff --git a/packages/twenty-front/src/modules/object-record/record-form/hooks/useRecordCreationForm.ts b/packages/twenty-front/src/modules/object-record/record-form/hooks/useRecordCreationForm.ts
index 2df3da26518..03bc200e920 100644
--- a/packages/twenty-front/src/modules/object-record/record-form/hooks/useRecordCreationForm.ts
+++ b/packages/twenty-front/src/modules/object-record/record-form/hooks/useRecordCreationForm.ts
@@ -1,37 +1,7 @@
-import { useObjectMetadataItems } from '@/object-metadata/hooks/useObjectMetadataItems';
import { useRecordCreationFormContextOrThrow } from '@/object-record/record-form/contexts/RecordCreationFormContext';
-import { type RecordCreationRequest } from '@/object-record/record-form/types/RecordCreationRequest';
-import { computeRecordFormCreateRecordInput } from '@/object-record/record-form/utils/computeRecordFormCreateRecordInput';
-import { useIsFeatureEnabled } from '@/workspace/hooks/useIsFeatureEnabled';
-import { useCallback } from 'react';
-import { FeatureFlagKey } from '~/generated-metadata/graphql';
export const useRecordCreationForm = () => {
const { requestRecordCreation } = useRecordCreationFormContextOrThrow();
- const { objectMetadataItems } = useObjectMetadataItems();
- const isRecordCreationFormEnabled = useIsFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- );
-
- const createRecordWithOptionalForm = useCallback(
- (request: RecordCreationRequest) => {
- if (isRecordCreationFormEnabled) {
- return requestRecordCreation(request);
- }
-
- return request.createRecord(
- computeRecordFormCreateRecordInput({
- draftRecord: request.initialDraftRecord ?? {},
- fieldMetadataItems: request.objectMetadataItem.fields,
- objectMetadataItems,
- }),
- );
- },
- [isRecordCreationFormEnabled, objectMetadataItems, requestRecordCreation],
- );
-
- return {
- createRecordWithOptionalForm,
- };
+ return { requestRecordCreation };
};
diff --git a/packages/twenty-front/src/modules/settings/admin-panel/constants/SettingsAdminFeatureFlagMetadata.ts b/packages/twenty-front/src/modules/settings/admin-panel/constants/SettingsAdminFeatureFlagMetadata.ts
index 586e75d6b9f..bc2070067f8 100644
--- a/packages/twenty-front/src/modules/settings/admin-panel/constants/SettingsAdminFeatureFlagMetadata.ts
+++ b/packages/twenty-front/src/modules/settings/admin-panel/constants/SettingsAdminFeatureFlagMetadata.ts
@@ -20,10 +20,6 @@ export const SETTINGS_ADMIN_FEATURE_FLAG_METADATA: Record<
label: msg`Record sharing`,
description: msg`Let people restrict and share individual records.`,
},
- [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED]: {
- label: msg`Record creation form`,
- description: msg`Use a dedicated form when creating records, and enable validation rules.`,
- },
[FeatureFlagKey.IS_CALENDAR_EVENT_SHARED_ACROSS_CHANNELS_ENABLED]: {
label: msg`Share calendar events across channels`,
description: msg`Store a meeting synced by several calendars of the same provider once, instead of once per calendar.`,
diff --git a/packages/twenty-front/src/modules/settings/data-model/object-details/components/tabs/ObjectSettings.tsx b/packages/twenty-front/src/modules/settings/data-model/object-details/components/tabs/ObjectSettings.tsx
index ce7cd09e8f9..3ef5d264290 100644
--- a/packages/twenty-front/src/modules/settings/data-model/object-details/components/tabs/ObjectSettings.tsx
+++ b/packages/twenty-front/src/modules/settings/data-model/object-details/components/tabs/ObjectSettings.tsx
@@ -105,9 +105,6 @@ export const ObjectSettings = ({
const isReadOnly =
isObjectMetadataReadOnly({ objectMetadataItem }) || isDDLLocked;
- const isRecordCreationFormEnabled = useIsFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- );
const hasValidationRulesEntitlement = useHasValidationRulesEntitlement();
const isRelatedRecordPathsEnabled = useIsFeatureEnabled(
FeatureFlagKey.IS_RELATED_RECORD_PATHS_ENABLED,
@@ -192,29 +189,27 @@ export const ObjectSettings = ({
/>
</Section.Root>
)}
- {isRecordCreationFormEnabled &&
- !objectMetadataItem.isRemote &&
- !objectMetadataItem.isSystem && (
- <Section.Root>
- <Section.Header
- title={t`Validation rules`}
- description={t`Block records that break your rules, like an opportunity marked Won with no amount. Checked on every save.`}
- actions={<OrganizationAdornment />}
+ {!objectMetadataItem.isRemote && !objectMetadataItem.isSystem && (
+ <Section.Root>
+ <Section.Header
+ title={t`Validation rules`}
+ description={t`Block records that break your rules, like an opportunity marked Won with no amount. Checked on every save.`}
+ actions={<OrganizationAdornment />}
+ />
+ {hasValidationRulesEntitlement ? (
+ <SettingsObjectValidationRulesSection
+ objectMetadataItem={objectMetadataItem}
+ isReadOnly={isReadOnly}
/>
- {hasValidationRulesEntitlement ? (
- <SettingsObjectValidationRulesSection
- objectMetadataItem={objectMetadataItem}
- isReadOnly={isReadOnly}
- />
- ) : (
- <SettingsEnterpriseFeatureGateCard
- title={t`Organization feature`}
- description={t`Upgrade to Organization to set validation rules.`}
- buttonTitle={t`Activate`}
- />
- )}
- </Section.Root>
- )}
+ ) : (
+ <SettingsEnterpriseFeatureGateCard
+ title={t`Organization feature`}
+ description={t`Upgrade to Organization to set validation rules.`}
+ buttonTitle={t`Activate`}
+ />
+ )}
+ </Section.Root>
+ )}
<Section.Root>
<Section.Header
title={t`Advanced`}
diff --git a/packages/twenty-front/src/modules/side-panel/pages/record-creation-form/components/__stories__/RecordCreationFlow.stories.tsx b/packages/twenty-front/src/modules/side-panel/pages/record-creation-form/components/__stories__/RecordCreationFlow.stories.tsx
index 8c42ef3c39a..6add4522e4e 100644
--- a/packages/twenty-front/src/modules/side-panel/pages/record-creation-form/components/__stories__/RecordCreationFlow.stories.tsx
+++ b/packages/twenty-front/src/modules/side-panel/pages/record-creation-form/components/__stories__/RecordCreationFlow.stories.tsx
@@ -45,7 +45,6 @@ import { ComponentDecorator } from 'twenty-ui/testing';
import { getOsControlSymbol } from 'twenty-ui/utilities';
import {
EngineComponentKey,
- FeatureFlagKey,
PageLayoutTabLayoutMode,
PageLayoutType,
WidgetConfigurationType,
@@ -157,12 +156,7 @@ const RecordCreationFlow = ({ commandOrigin }: RecordCreationFlowProps) => {
applyChanges();
store.set(currentWorkspaceState.atom, {
...mockCurrentWorkspace,
- featureFlags: [
- {
- key: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: true,
- },
- ],
+ featureFlags: [],
});
store.set(currentWorkspaceMemberState.atom, (member) =>
isDefined(member)
diff --git a/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRules.test.tsx b/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRules.test.tsx
index f6b43b5c579..b6c137429b2 100644
--- a/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRules.test.tsx
+++ b/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRules.test.tsx
@@ -3,7 +3,6 @@ import { act, renderHook, waitFor } from '@testing-library/react';
import { Provider as JotaiProvider } from 'jotai';
import { type ReactNode } from 'react';
-import { currentWorkspaceState } from '@/auth/states/currentWorkspaceState';
import { dispatchMetadataOperationBrowserEvent } from '@/browser-event/utils/dispatchMetadataOperationBrowserEvent';
import {
jotaiStore,
@@ -13,10 +12,8 @@ import { useValidationRules } from '@/validation-rules/hooks/useValidationRules'
import { type ValidationRule } from '@/validation-rules/types/ValidationRule';
import {
AllMetadataName,
- FeatureFlagKey,
FindManyValidationRulesDocument,
} from '~/generated-metadata/graphql';
-import { mockCurrentWorkspace } from '~/testing/mock-data/users';
const OBJECT_METADATA_ID = '20202020-0000-4000-8000-000000000001';
const OTHER_OBJECT_METADATA_ID = '20202020-0000-4000-8000-000000000002';
@@ -63,21 +60,12 @@ const buildValidationRulesMock = (validationRules: ValidationRule[]) => ({
const renderUseValidationRules = ({
mocks,
- isRecordCreationFormEnabled = true,
+ objectMetadataId = OBJECT_METADATA_ID,
}: {
mocks: ReturnType<typeof buildValidationRulesMock>[];
- isRecordCreationFormEnabled?: boolean;
+ objectMetadataId?: string;
}) => {
resetJotaiStore();
- jotaiStore.set(currentWorkspaceState.atom, {
- ...mockCurrentWorkspace,
- featureFlags: [
- {
- key: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: isRecordCreationFormEnabled,
- },
- ],
- });
const wrapper = ({ children }: { children: ReactNode }) => (
<JotaiProvider store={jotaiStore}>
@@ -85,10 +73,9 @@ const renderUseValidationRules = ({
</JotaiProvider>
);
- return renderHook(
- () => useValidationRules({ objectMetadataId: OBJECT_METADATA_ID }),
- { wrapper },
- );
+ return renderHook(() => useValidationRules({ objectMetadataId }), {
+ wrapper,
+ });
};
const dispatchValidationRuleUpdate = (updatedRecord: ValidationRule) =>
@@ -210,14 +197,14 @@ describe('useValidationRules', () => {
expect(result.current.validationRules).toHaveLength(1);
});
- it('should neither load nor listen when the feature flag is disabled', async () => {
+ it('should neither load nor listen without an object metadata ID', async () => {
const validationRulesMock = buildValidationRulesMock([
ACTIVE_VALIDATION_RULE,
]);
const { result } = renderUseValidationRules({
mocks: [validationRulesMock],
- isRecordCreationFormEnabled: false,
+ objectMetadataId: '',
});
act(() => {
diff --git a/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRulesReadingField.test.tsx b/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRulesReadingField.test.tsx
index c61c0955900..55c6f1bdc3d 100644
--- a/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRulesReadingField.test.tsx
+++ b/packages/twenty-front/src/modules/validation-rules/hooks/__tests__/useValidationRulesReadingField.test.tsx
@@ -10,10 +10,7 @@ import {
} from '@/ui/utilities/state/jotai/jotaiStore';
import { useValidationRulesReadingField } from '@/validation-rules/hooks/useValidationRulesReadingField';
import { type ValidationRule } from '@/validation-rules/types/ValidationRule';
-import {
- FeatureFlagKey,
- FindValidationRulesReadingFieldDocument,
-} from '~/generated-metadata/graphql';
+import { FindValidationRulesReadingFieldDocument } from '~/generated-metadata/graphql';
import { mockCurrentWorkspace } from '~/testing/mock-data/users';
const FIELD_METADATA_ID = '20202020-0000-4000-8000-000000000001';
@@ -30,21 +27,9 @@ const VALIDATION_RULE: ValidationRule = {
isActive: true,
};
-const renderUseValidationRulesReadingField = ({
- isRecordCreationFormEnabled,
-}: {
- isRecordCreationFormEnabled: boolean;
-}) => {
+const renderUseValidationRulesReadingField = () => {
resetJotaiStore();
- jotaiStore.set(currentWorkspaceState.atom, {
- ...mockCurrentWorkspace,
- featureFlags: [
- {
- key: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: isRecordCreationFormEnabled,
- },
- ],
- });
+ jotaiStore.set(currentWorkspaceState.atom, mockCurrentWorkspace);
const mocks = [
{
@@ -78,9 +63,7 @@ const renderUseValidationRulesReadingField = ({
describe('useValidationRulesReadingField', () => {
it('should be loading, then return the rules reading the field', async () => {
- const { result } = renderUseValidationRulesReadingField({
- isRecordCreationFormEnabled: true,
- });
+ const { result } = renderUseValidationRulesReadingField();
expect(result.current.loading).toBe(true);
@@ -92,13 +75,4 @@ describe('useValidationRulesReadingField', () => {
expect(result.current.loading).toBe(false);
expect(result.current.hasFailedToLoad).toBe(false);
});
-
- it('should not load anything when the feature is off', () => {
- const { result } = renderUseValidationRulesReadingField({
- isRecordCreationFormEnabled: false,
- });
-
- expect(result.current.loading).toBe(false);
- expect(result.current.validationRulesReadingField).toEqual([]);
- });
});
diff --git a/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRules.ts b/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRules.ts
index 22460f159a5..cff64f57e6b 100644
--- a/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRules.ts
+++ b/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRules.ts
@@ -6,10 +6,8 @@ import { useListenToMetadataOperationBrowserEvent } from '@/browser-event/hooks/
import { type MetadataOperationBrowserEventDetail } from '@/browser-event/types/MetadataOperationBrowserEventDetail';
import { type ValidationRule } from '@/validation-rules/types/ValidationRule';
import { shouldRefetchValidationRulesOnOperation } from '@/validation-rules/utils/shouldRefetchValidationRulesOnOperation';
-import { useIsFeatureEnabled } from '@/workspace/hooks/useIsFeatureEnabled';
import {
AllMetadataName,
- FeatureFlagKey,
FindManyValidationRulesDocument,
} from '~/generated-metadata/graphql';
@@ -18,12 +16,7 @@ export const useValidationRules = ({
}: {
objectMetadataId: string;
}) => {
- const isRecordCreationFormEnabled = useIsFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- );
-
- const skip =
- !isRecordCreationFormEnabled || !isNonEmptyString(objectMetadataId);
+ const skip = !isNonEmptyString(objectMetadataId);
const { data, loading, refetch } = useQuery(FindManyValidationRulesDocument, {
variables: { objectMetadataId },
diff --git a/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRulesReadingField.ts b/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRulesReadingField.ts
index 8faadad49c9..9bd7fcbd8fb 100644
--- a/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRulesReadingField.ts
+++ b/packages/twenty-front/src/modules/validation-rules/hooks/useValidationRulesReadingField.ts
@@ -3,10 +3,8 @@ import { isDefined, isNonEmptyString } from 'twenty-shared/utils';
import { useListenToMetadataOperationBrowserEvent } from '@/browser-event/hooks/useListenToMetadataOperationBrowserEvent';
import { type ValidationRule } from '@/validation-rules/types/ValidationRule';
-import { useIsFeatureEnabled } from '@/workspace/hooks/useIsFeatureEnabled';
import {
AllMetadataName,
- FeatureFlagKey,
FindValidationRulesReadingFieldDocument,
} from '~/generated-metadata/graphql';
@@ -15,12 +13,7 @@ export const useValidationRulesReadingField = ({
}: {
fieldMetadataId: string;
}) => {
- const isRecordCreationFormEnabled = useIsFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- );
-
- const skip =
- !isRecordCreationFormEnabled || !isNonEmptyString(fieldMetadataId);
+ const skip = !isNonEmptyString(fieldMetadataId);
const { data, loading, error, refetch } = useQuery(
FindValidationRulesReadingFieldDocument,
diff --git a/packages/twenty-front/src/pages/settings/data-model/validation-rules/SettingsObjectValidationRuleEdit.tsx b/packages/twenty-front/src/pages/settings/data-model/validation-rules/SettingsObjectValidationRuleEdit.tsx
index 0b2d3085784..d949da0560c 100644
--- a/packages/twenty-front/src/pages/settings/data-model/validation-rules/SettingsObjectValidationRuleEdit.tsx
+++ b/packages/twenty-front/src/pages/settings/data-model/validation-rules/SettingsObjectValidationRuleEdit.tsx
@@ -5,14 +5,9 @@ import { useFilteredObjectMetadataItems } from '@/object-metadata/hooks/useFilte
import { SettingsValidationRuleEditForm } from '@/validation-rules/components/SettingsValidationRuleEditForm';
import { useHasValidationRulesEntitlement } from '@/validation-rules/hooks/useHasValidationRulesEntitlement';
import { useValidationRules } from '@/validation-rules/hooks/useValidationRules';
-import { useIsFeatureEnabled } from '@/workspace/hooks/useIsFeatureEnabled';
-import { FeatureFlagKey } from '~/generated-metadata/graphql';
import { NotFound } from '~/pages/not-found/NotFound';
export const SettingsObjectValidationRuleEdit = () => {
- const isRecordCreationFormEnabled = useIsFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- );
const hasValidationRulesEntitlement = useHasValidationRulesEntitlement();
const { objectNamePlural = '', validationRuleId = '' } = useParams();
const { findObjectMetadataItemByNamePlural } =
@@ -25,11 +20,7 @@ export const SettingsObjectValidationRuleEdit = () => {
objectMetadataId: objectMetadataItem?.id ?? '',
});
- if (
- !isRecordCreationFormEnabled ||
- !hasValidationRulesEntitlement ||
- !isDefined(objectMetadataItem)
- ) {
+ if (!hasValidationRulesEntitlement || !isDefined(objectMetadataItem)) {
return <NotFound />;
}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/services/__tests__/defined-tool-registry.service.spec.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/services/__tests__/defined-tool-registry.service.spec.ts
index 4572bdc0593..3ca24dda893 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/services/__tests__/defined-tool-registry.service.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/services/__tests__/defined-tool-registry.service.spec.ts
@@ -87,7 +87,7 @@ const pauseWebhookInputSchema = z.object({ id: z.uuid() });
category: ToolCategory.WEBHOOK,
description: 'Pause a webhook.',
requiredPermissionFlags: [PermissionFlagType.API_KEYS_AND_WEBHOOKS],
- requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
+ requiredFeatureFlags: [FeatureFlagKey.IS_MCP_SERVERS_ENABLED],
})
class PauseWebhookTool extends BaseTool<typeof pauseWebhookInputSchema> {
readonly inputSchema = pauseWebhookInputSchema;
@@ -219,7 +219,7 @@ describe('DefinedToolRegistryService', () => {
isGranted: true,
enabledFeatureFlags: [
FeatureFlagKey.IS_AI_CHAT_INBOX_ENABLED,
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
+ FeatureFlagKey.IS_MCP_SERVERS_ENABLED,
],
});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-front-component/constants/generated/ui-documentation.json b/packages/twenty-server/src/engine/metadata-modules/ai/ai-front-component/constants/generated/ui-documentation.json
index 981bad939e8..b3c3a3e2519 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-front-component/constants/generated/ui-documentation.json
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-front-component/constants/generated/ui-documentation.json
@@ -1 +1 @@
-{"version":"2.55.0","pages":[{"name":"CountrySelect","entryPoint":"twenty-ui/components/input","content":"---\ntitle: CountrySelect\ndescription: A complete country picker and shared parts for prepared choices, stable identifiers, and null clearing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CountrySelectReference from '/snippets/ui/generated/components/input/country-select.mdx';\n\n## Overview\n\n`CountrySelect` provides a complete country picker with a labeled trigger, decorative flags, search, and a no-country choice. `CountrySelect.Root`, `CountrySelect.Trigger`, and `CountrySelect.Options` expose the same implementation for composition with [Dropdown](/ui/components/navigation/dropdown). Your application supplies country data and translated text and decides how selected identifiers map to stored values.\n\n<StoryEmbed\n storyId=\"ui-input-countryselect--display\"\n title=\"Country selection\"\n height={340}\n/>\n\n## Usage\n\nSupply prepared choices with unique stable string identifiers and display labels. The picker reports identifiers unchanged, independently of the displayed language. Flags are optional decorative React nodes. A choice can set `disabled: true` to remain visible without allowing selection.\n\n```tsx\nimport { CountrySelect } from 'twenty-ui/components/input';\n\nconst COUNTRIES = [\n { value: 'FR', label: 'France', flag: '🇫🇷' },\n { value: 'DE', label: 'Germany', flag: '🇩🇪' },\n { value: 'JP', label: 'Japan', flag: '🇯🇵' },\n];\n\nexport const ShippingCountry = () => (\n <CountrySelect\n label=\"Shipping country\"\n countries={COUNTRIES}\n defaultValue=\"FR\"\n searchLabel=\"Search countries\"\n noCountryLabel=\"No country\"\n noResultsLabel=\"No countries found\"\n />\n);\n```\n\n`defaultValue` initializes uncontrolled selection. Use `value` and `onValueChange` for controlled selection. Updating `value` externally updates both the trigger and the selected option, including while the popup is open.\n\n```tsx\nimport { useState } from 'react';\nimport { CountrySelect, type CountryChoice } from 'twenty-ui/components/input';\n\nexport const ControlledCountry = ({\n countries,\n}: {\n countries: readonly CountryChoice[];\n}) => {\n const [country, setCountry] = useState<string | null>('FR');\n\n return (\n <CountrySelect\n label=\"Country\"\n countries={countries}\n value={country}\n onValueChange={setCountry}\n />\n );\n};\n```\n\n## Shared parts\n\n`Root` owns the prepared choices and selected identifier. It adds no DOM element. `Trigger` reads that selection and displays its label and flag. `Options` reads the same data and renders searchable rows inside `Dropdown.SelectionGroup`. Dropdown owns opening, popup placement, pages, navigation, and focus.\n\n```tsx\nimport { CountrySelect, type CountryChoice } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\nexport const ShippingCountryParts = ({\n countries,\n}: {\n countries: readonly CountryChoice[];\n}) => (\n <CountrySelect.Root countries={countries} defaultValue=\"FR\">\n <Dropdown.Root type=\"picker\">\n <CountrySelect.Trigger label=\"Shipping country\" />\n <Dropdown.Content>\n <CountrySelect.Options\n aria-label=\"Shipping country\"\n searchLabel=\"Search countries\"\n />\n </Dropdown.Content>\n </Dropdown.Root>\n </CountrySelect.Root>\n);\n```\n\nThe shorthand assembles these parts internally. Both forms share selection, clearing, disabled behavior, search matching, and selected-option presentation. `closeOnSelect` defaults to `true`. Set it to `false` on the shorthand or `Options` when selection should keep the popup open.\n\n## Clearing and cancellation\n\n`null` represents no country. Selecting the no-country row reports `null`; passing `value={null}` clears a controlled picker. An empty string (`''`) is a valid supplied choice identifier and stays distinct from `null`.\n\n`onValueChange` receives the next identifier or `null` and Dropdown selection event details: `event`, `reason`, `trigger`, `cancel`, and `isCanceled`. Call `details.cancel()` before updating controlled state to preserve the current selection and keep the popup open. Repeated selection of the current identifier does not emit another value change.\n\nAn identifier absent from `countries` displays `noCountryLabel` and the no-country icon. Rendering it does not emit a change or overwrite the host value. The application decides how to handle stored values absent from the current choices.\n\n## Search and interaction\n\nSearch matches prepared display labels. It ignores letter case, optional accents in Latin, Greek, Arabic, and Hebrew text, and Cyrillic stress marks, treats the Cyrillic `ё` as `е`, and folds letters such as `ø`, `æ`, and `ß` into `o`, `ae`, and `ss`. It also ignores standalone accent characters such as `^`, `` ` ``, `´`, `¨`, and `ˇ`, so a pending dead key does not hide matches. Marks that form distinct letters remain significant, such as Japanese voicing marks, Indic vowel signs, and the Cyrillic `й`. A partly typed Korean syllable, such as ㅎ or 하, matches syllables that start with it, such as 한. `noCountryLabel` participates in the same search. A query with no matching options displays `noResultsLabel`.\n\nArrow keys, Home, and End move focus without changing the selected identifier. Enter or Space on an enabled option commits selection through its selection group. Escape and outside interaction use Dropdown dismissal and focus handling. Each picker has independent selection and popup state.\n\nDropdown search activation and IME protection still need integration work, as do lazy page sessions and inactive-page behavior. Both picker forms reset their own search on reopen, including popups kept mounted. Their shared implementation does not yet complete Dropdown's page and browsing lifecycle.\n\n`disabled` on `Root` or the shorthand prevents opening and selection. A picker with no supplied countries is disabled as well. If either condition occurs while its popup is open, the picker requests closure. Closing returns focus to the trigger. Controlled hosts must accept that close request through `onOpenChange`; the shorthand also suppresses the popup while disabled. After accepting the close request, enabling the picker again does not reopen it automatically. The trigger stays focusable and exposes `aria-disabled`. Disabled triggers skip consumer activation handlers. Function forms of `className`, `style`, and `render` receive `disabled: true` in the trigger state.\n\n## Labels and customization\n\nProvide a visible `label`, or use `aria-label` or `aria-labelledby` on the trigger. Referenced labels take precedence over a nonempty `aria-label`, which takes precedence over the visible label. With one of these names, the selected country describes the trigger. Otherwise the selected country names it. The popup inherits the trigger name unless caller-owned popup labels or a Dropdown title name it. The shorthand also names its options listbox from those trigger labels unless `optionsProps` supplies its own accessible name. In composed usage, give `Options` an `aria-label` or `aria-labelledby` for an explicit listbox name. Otherwise it references the registered Dropdown title or trigger content. A tooltip reveals the full selected label when it is truncated.\n\n`searchLabel` supplies the search input's placeholder and accessible name, `noCountryLabel` the no-country text, and `noResultsLabel` the empty-result text. They default to `Search`, `No country`, and `No results`. Pass translated strings when your application is localized. Custom `Trigger` children replace the selected country display; the caller owns that content and its accessible presentation.\n\nNative trigger attributes, event handlers, `className`, `style`, `ref`, and `render` target the trigger button. `wrapperProps` targets the surrounding div that also contains the visible label. `Options` native props, `ref`, and `render` target its selection group div. Its `render` function receives `{ value, multiple: false }`, where `value` is the public country identifier or `null`, rather than an internal option identifier. `searchProps` targets the search input; search value and change handling remain owned by the picker. The shorthand accepts the same search props directly and group attributes through `optionsProps`. Forward supplied props and refs when replacing an element through `render`.\n\n## Host integration and storage\n\nThe shorthand accepts Dropdown's `open`, `defaultOpen`, `onOpenChange`, `onEscapeKeyDown`, `onInteractOutside`, and `defaultPage`. Composed usage sets them on `Dropdown.Root`. `onOpenChange` currently reports only a boolean, matching Dropdown's public contract. Opening event details and general opening cancellation remain unavailable upstream. Escape and outside dismissal callbacks can call `event.preventDefault()` to keep the popup open.\n\n`popupProps` accepts all `Dropdown.Content` props except `children`, including popup native attributes, `ref`, `render`, positioning, portal destination, accessible names, and `keepMounted`. In composed usage, pass them directly to `Dropdown.Content`.\n\nKeep dropdown IDs, focus stacks, field metadata, persistence, and editing lifecycle in the host adapter. Twenty's frontend adapter uses stable country codes for picker identifiers and converts explicit selections back to existing source country-name values. Its stored empty string maps to picker `null`; unmatched legacy values stay stored until an explicit selection changes them. Translated display labels do not become stored country names. Applications with another storage format should make the conversion in their adapter as well.\n\nNative form submission, reset, `required`, `readOnly`, and Field integration for this custom picker remain deferred.\n\n## Front component renderer\n\nReact and Preact front component fixtures verify pointer opening, filtering, and selection through the shorthand and compound APIs, including controlled and uncontrolled values, null clearing and reselection, canceled changes, external controlled updates, disabled interaction, translated labels, and decorative flags. They also verify native trigger and search input props and refs, plus trigger and option-group render targets and refs. Search keyboard activation and IME handling, page-session lifetime, and full renderer portal, geometry, scrolling, outside dismissal, and focus restoration acceptance remain open.\n\n## Migration\n\nReplace the previous empty-string no-country sentinel with `null` in controlled values and selection state. An empty string (`''`) is now a valid choice identifier, so `value=\"\"` no longer means no country. Keep each `CountryChoice.value` stable; existing string identifiers can remain unchanged and display labels can be translated independently.\n\nUpdate `onValueChange` handlers to accept `string | null`. The callback now also receives `eventDetails` as its second argument, including `cancel()` to reject a selection. Handlers that do not need event details can continue using only the first argument.\n\nIf your storage uses `''` for no country, convert it to `null` before passing it to the picker and convert reported `null` back to `''` when persisting. Keep that compatibility conversion in the application adapter, and omit it when `''` is an intentional choice identifier.\n\n## Props\n\n<CountrySelectReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"CountrySelect","entryPoint":"twenty-ui/components/input","slug":"components/input/country-select","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Closes the popup after a selection. Defaults to true. Cancelled selection keeps it open."},{"name":"countries","type":"readonly CountryChoice[]","required":true,"defaultValue":null,"description":"Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the uncontrolled popup is initially open."},{"name":"defaultPage","type":"string","required":false,"defaultValue":null,"description":"Dropdown page shown when the popup opens. Defaults to root."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":null,"description":"Initial uncontrolled selected identifier. Defaults to null."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Prevents opening and selection while the trigger stays focusable. An empty country list is also disabled."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. Generated when omitted."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Optional visible label that names the trigger."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"noCountryLabel","type":"string","required":false,"defaultValue":null,"description":"Text of the no-country choice, also displayed when no country is selected."},{"name":"noResultsLabel","type":"string","required":false,"defaultValue":null,"description":"Text displayed when no choice matches the search."},{"name":"onEscapeKeyDown","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before Escape dismisses the popup. Call event.preventDefault() to keep it open."},{"name":"onInteractOutside","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before outside interaction or Tab dismisses the popup. Call event.preventDefault() to keep it open."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Reports popup opening and closing with the next boolean state, matching Dropdown.Root."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Reports the selected identifier or null with cancellable event details. Call details.cancel() to preserve selection and keep the popup open."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controls whether the country popup is open."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"optionsProps","type":"Omit<CountrySelectOptionsProps, \"closeOnSelect\" | \"searchLabel\" | \"noResultsLabel\" | \"searchProps\">","required":false,"defaultValue":null,"description":"Native props, ref, and render for the selection group div rendered by CountrySelect.Options."},{"name":"popupProps","type":"Omit<DropdownContentProps, \"children\">","required":false,"defaultValue":null,"description":"Dropdown.Content props, including native popup attributes, ref, render, positioning, portal destination, and keepMounted. Explicit popup accessible names override the trigger name. Children are owned by the picker."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the trigger element while preserving its behavior and props."},{"name":"searchLabel","type":"string","required":false,"defaultValue":null,"description":"Placeholder and accessible name of the search input."},{"name":"searchProps","type":"Omit<DropdownSearchProps, \"defaultValue\" | \"value\" | \"onValueChange\">","required":false,"defaultValue":null,"description":"Native search input props, ref, and render. Search value and change handling are owned by the picker."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled selected identifier. Null selects no country; undefined leaves selection uncontrolled."},{"name":"wrapperProps","type":"Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"children\">","required":false,"defaultValue":null,"description":"Native props and ref for the div around the trigger and its visible label. Children are owned by the picker."}],"parts":[{"name":"Root","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Picker composition containing Dropdown.Root, CountrySelect.Trigger, and CountrySelect.Options. Root adds no DOM element."},{"name":"countries","type":"readonly CountryChoice[]","required":true,"defaultValue":null,"description":"Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled selected identifier. Defaults to null."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Prevents opening and selection. An empty country list is also disabled. The trigger stays focusable with aria-disabled."},{"name":"noCountryLabel","type":"string","required":false,"defaultValue":"No country","description":"Text for the null selection and its option. Defaults to No country."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Reports the selected identifier or null with event, reason, trigger, cancel and isCanceled details. Call cancel() to preserve selection and keep the popup open."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled selected identifier. Null selects no country; undefined leaves selection uncontrolled."}]},{"name":"Trigger","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger button."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Optional visible label that names the trigger."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the trigger element. Custom components must forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"wrapperProps","type":"Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"children\">","required":false,"defaultValue":null,"description":"Native props and ref for the div around the trigger and its visible label. Children are owned by the picker."}]},{"name":"Options","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name for the selection listbox. Overrides its default name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"Accessible name references for the selection listbox. Defaults to the registered Dropdown title or trigger element."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the selection group div."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Closes the popup after a selection. Defaults to true. Cancelled selection keeps it open."},{"name":"noResultsLabel","type":"string","required":false,"defaultValue":null,"description":"Text displayed when no choice matches the search. Defaults to No results."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the selection group element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CountrySelectOptionsState>","required":false,"defaultValue":null,"description":"Replaces the selection group div. Functions receive supplied props and { value, multiple: false } state, with the public string or null selection. Custom components must forward the supplied props and ref."},{"name":"searchLabel","type":"string","required":false,"defaultValue":null,"description":"Search placeholder and accessible name. Defaults to Search."},{"name":"searchProps","type":"Omit<DropdownSearchProps, \"defaultValue\" | \"value\" | \"onValueChange\">","required":false,"defaultValue":null,"description":"Native search input props, ref, and render. Search value and change handling are owned by the picker."}]}]}},{"name":"CurrencyPicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: CurrencyPicker\ndescription: Choose a currency with a complete picker or compose its parts in a dropdown.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CurrencyPickerReference from '/snippets/ui/generated/components/input/currency-picker.mdx';\n\n## Overview\n\n`CurrencyPicker` combines a compact currency trigger, searchable options, and a [Dropdown](/ui/components/navigation/dropdown). Supply a currency catalogue and use one component for ordinary selection. Compose `Root`, `Trigger`, and `Options` with Dropdown when the popup needs other content or pages.\n\n<StoryEmbed\n storyId=\"ui-input-currencypicker--display\"\n title=\"Currency picker\"\n height={420}\n/>\n\n## Usage\n\nEach currency has a unique `code`, a `name`, and optional `symbol` and `disabled` properties. The code is the stable selection identifier. The picker does not ship a currency catalogue or choose an application default.\n\n```tsx\nimport { CurrencyPicker } from 'twenty-ui/components/input';\n\nconst CURRENCIES = [\n { code: 'EUR', name: 'Euro', symbol: '€' },\n { code: 'USD', name: 'US Dollar', symbol: '$' },\n];\n\nexport const InvoiceCurrency = () => (\n <CurrencyPicker\n currencies={CURRENCIES}\n defaultValue=\"USD\"\n aria-label=\"Invoice currency\"\n optionsProps={{\n searchLabel: 'Search currencies',\n emptyLabel: 'No currencies found',\n }}\n contentProps={{ width: 280 }}\n />\n);\n```\n\nUse `defaultValue` for uncontrolled selection. For controlled selection, pass `value` and update it from `onValueChange`. The callback receives the next code or `null` and Dropdown selection details containing `event`, `reason`, `trigger`, `cancel`, and `isCanceled`. Call `details.cancel()` to preserve the current selection and keep the popup open. Selecting the current code does not emit another change.\n\n`null` clears the selection. An empty string remains a valid code and does not clear it. An unknown value stays unchanged and appears as its raw code in the trigger; it does not add an option to the catalogue. A later controlled update or catalogue change updates the trigger and selected row.\n\n```tsx\nimport { useState } from 'react';\nimport { CurrencyPicker } from 'twenty-ui/components/input';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst CURRENCIES = [\n { code: 'EUR', name: 'Euro' },\n { code: 'USD', name: 'US Dollar' },\n];\n\nexport const ClearableCurrency = () => {\n const [value, setValue] = useState<string | null>('USD');\n\n return (\n <>\n <CurrencyPicker\n currencies={CURRENCIES}\n value={value}\n onValueChange={setValue}\n aria-label=\"Invoice currency\"\n triggerProps={{ placeholder: 'Choose a currency' }}\n />\n <Button onClick={() => setValue(null)}>Clear currency</Button>\n </>\n );\n};\n```\n\n## Advanced composition\n\n`CurrencyPicker.Root` prepares the catalogue and owns selection for both parts. It adds no DOM element and must be inside `Dropdown.Root`. Keep `Trigger` and `Options` under the same picker root, including when the options live in another dropdown page. The root's render-function children expose `value`, `selectedCurrency`, and `disabled` for caller-owned labels and supporting content.\n\n```tsx\nimport { CurrencyPicker } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\nconst CURRENCIES = [\n { code: 'EUR', name: 'Euro' },\n { code: 'USD', name: 'US Dollar' },\n];\n\nexport const ComposedCurrency = () => (\n <Dropdown.Root type=\"picker\">\n <CurrencyPicker.Root\n currencies={CURRENCIES}\n defaultValue=\"USD\"\n closeOnSelect={false}\n >\n {({ value }) => (\n <>\n <CurrencyPicker.Trigger\n aria-label={`Invoice currency: ${value ?? 'none'}`}\n placeholder=\"Choose a currency\"\n />\n <Dropdown.Content aria-label=\"Invoice currency\" width={280}>\n <Dropdown.Title>Invoice currency</Dropdown.Title>\n <CurrencyPicker.Options\n searchLabel=\"Search currencies\"\n emptyLabel=\"No currencies found\"\n />\n </Dropdown.Content>\n </>\n )}\n </CurrencyPicker.Root>\n </Dropdown.Root>\n);\n```\n\nDropdown owns opening, popup placement, pages, search navigation, and focus. The picker uses a Dropdown selection group for persistent selected values and the close policy. `Root.closeOnSelect` defaults to `true`; use `false` to keep the popup open after choosing a currency. Arrow keys, Home, and End move focus without changing the value. Enter, Space, or pointer activation selects an enabled option. Disabled currencies stay visible and cannot be selected.\n\n## Search and ordering\n\nOptions are searchable by default. Search ignores surrounding whitespace and matches codes, names, symbols, and the default `Name (CODE)` label without case sensitivity, using the same rules in every browser locale. `getSearchText` on the root replaces the searchable text for each currency. Display customization and search text are independent.\n\nResults retain catalogue order. Set `selectedFirst` on the shorthand or root to move the selected currency before the other matches. A query that excludes it also removes its row. An unknown value does not create a selected result. Empty results show `emptyLabel` in a status region.\n\nSet `Options.searchable={false}` to omit the search field. `Options.searchProps` targets the native search input, including its `ref`, `render`, accessible attributes, and controlled `value` or uncontrolled `defaultValue`. `searchProps.onValueChange` receives the query. In shorthand use, pass these options through `optionsProps`.\n\nThe search field receives focus when a searchable picker opens. Enter with a nonempty query activates the first enabled result. With an empty query, move focus to an option before selecting it. Search activation during IME composition and fresh search on reopen remain subject to the shared Dropdown search and page-session contracts.\n\n## Presentation and native targets\n\nThe trigger shows the selected code by default. `renderValue` receives `{ value, selectedCurrency, disabled }` to customize that display without looking up the currency again. `Trigger.children` overrides the value display, and `Trigger.placeholder` supplies the empty display. `getOptionLabel` customizes each option's content, with the default `Name (CODE)` label. Currency names, symbols, labels, and option content belong to the caller.\n\nThe shorthand's native button attributes, event handlers, `className`, `style`, `ref`, and `render` target its trigger. `triggerProps` customizes that same button. Use `optionsProps` for the options wrapper div and its nested `searchProps` for the input. `contentProps` customizes Dropdown's popup. `open`, `defaultOpen`, and `onOpenChange` coordinate the shorthand's open state.\n\nIn compound use, native attributes, `ref`, and `render` on `Trigger` target its button, while those on `Options` target its wrapper div. `Options.listLabel` names only the inner selection listbox. Forward the supplied props and ref from a custom `render` component. Wrapper styling does not change the input's native target.\n\nSet `disabled` on the shorthand or root to disable opening, search, and selection. A part's `disabled` prop can additionally disable that part. Selection is a picker value; native form submission, reset, required validation, and Field integration remain outside this API.\n\n## Labels and application integration\n\n`searchLabel` defaults to `Search` and supplies the search placeholder and accessible name. `emptyLabel` defaults to `No results` and accepts content. Supply localized source labels, an accessible trigger name, and any placeholder from your application. Dropdown content takes the trigger name unless a `Dropdown.Title` or explicit content label names it. The selection listbox takes the registered Dropdown title or trigger name by default. Set `Options.listLabel` to give only that listbox its own accessible name, or pass `optionsProps.listLabel` in shorthand use. Native `aria-label` and `aria-labelledby` on `Options` label only its wrapper. The trigger keeps its own accessible name.\n\nThe application owns amount editing, currency storage, formatting, catalogue loading, and its initial value. An adapter should map stored currency codes and clearing behavior to `value` and `onValueChange`, preserving the application's formatting and fallback rules. Keep translated currency names and labels in the application.\n\n## Front-component renderer\n\nThe React and Preact sandbox fixtures cover shorthand and compound search and selection, disabled controls and options, trigger refs, null clearing, external controlled updates, reopening, and Escape focus restoration. They also verify that clearing an earlier query and typing `$` preserves the symbol query.\n\nPopup visibility, geometry, scrolling, and dismissal depend on the shared renderer's Dropdown and portal support. The picker uses that shared implementation.\n\n## Props\n\n<CurrencyPickerReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"CurrencyPicker","entryPoint":"twenty-ui/components/input","slug":"components/input/currency-picker","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned trigger content that overrides the selected value display."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger button."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Whether committing an enabled option closes the dropdown. Defaults to true. A canceled selection never closes automatically."},{"name":"contentProps","type":"Omit<DropdownContentProps, \"children\">","required":false,"defaultValue":null,"description":"Dropdown popup props, including placement, width, and accessible attributes."},{"name":"currencies","type":"readonly CurrencyPickerOption[]","required":true,"defaultValue":null,"description":"Available currencies in display order. Each code is a unique stable identifier; name and optional symbol are caller-owned data. A currency can be disabled."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is initially open when uncontrolled."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled currency code, or null for an empty selection. Defaults to null."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables opening, search, and every currency option."},{"name":"getOptionLabel","type":"((currency: CurrencyPickerOption) => ReactNode)","required":false,"defaultValue":"Name (CODE)","description":"Returns caller-owned content for a currency option. Defaults to Name (CODE). Display content does not change the search text."},{"name":"getSearchText","type":"((currency: CurrencyPickerOption) => string)","required":false,"defaultValue":"Name (CODE) and symbol","description":"Returns searchable text for a currency. Defaults to Name (CODE) and its optional symbol. Search trims the query and matches without case sensitivity."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID forwarded to the trigger button."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"onEscapeKeyDown","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before Escape closes the popup. Call event.preventDefault() to keep it open."},{"name":"onInteractOutside","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before an outside press or Tab out closes the popup. Call event.preventDefault() to keep it open."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Called with the next open state when the popup opens or closes."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next code or null and cancellable Dropdown selection details: event, reason, trigger, cancel and isCanceled. Calling cancel() preserves selection and prevents automatic close. Repeated single selection does not emit a change."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is open. Use with onOpenChange to control it."},{"name":"optionsProps","type":"CurrencyPickerOptionsProps","required":false,"defaultValue":null,"description":"Props for the options wrapper div, listLabel, and search behavior. Native input customization belongs in optionsProps.searchProps."},{"name":"placeholder","type":"ReactNode","required":false,"defaultValue":null,"description":"Trigger content displayed when the selected value is null."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the native trigger button. Forward the supplied props and ref when rendering a custom component."},{"name":"renderValue","type":"((state: CurrencyPickerState) => ReactNode)","required":false,"defaultValue":null,"description":"Returns selected trigger content from { value, selectedCurrency, disabled }. The default display is the raw code, or the trigger placeholder when null. Trigger children override it."},{"name":"selectedFirst","type":"boolean","required":false,"defaultValue":"false","description":"Moves the matching selected currency before other results. Defaults to false, preserving catalogue order."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the trigger button."},{"name":"triggerProps","type":"CurrencyPickerTriggerProps","required":false,"defaultValue":null,"description":"Props for the trigger button, including native attributes, ref, render, placeholder, and caller-owned children. These override shorthand trigger props."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled currency code or null for an empty selection. Undefined leaves selection uncontrolled. Empty and unknown strings remain identifiers."}],"parts":[{"name":"Root","props":[{"name":"children","type":"ReactNode | ((state: CurrencyPickerState) => ReactNode)","required":true,"defaultValue":null,"description":"Picker parts and supporting content, or a render function receiving { value, selectedCurrency, disabled }. Root owns selection and prepared data without adding a DOM element."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Whether committing an enabled option closes the dropdown. Defaults to true. A canceled selection never closes automatically."},{"name":"currencies","type":"readonly CurrencyPickerOption[]","required":true,"defaultValue":null,"description":"Available currencies in display order. Each code is a unique stable identifier; name and optional symbol are caller-owned data. A currency can be disabled."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled currency code, or null for an empty selection. Defaults to null."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the trigger, search input, and every currency option."},{"name":"getOptionLabel","type":"((currency: CurrencyPickerOption) => ReactNode)","required":false,"defaultValue":"Name (CODE)","description":"Returns caller-owned content for a currency option. Defaults to Name (CODE). Display content does not change the search text."},{"name":"getSearchText","type":"((currency: CurrencyPickerOption) => string)","required":false,"defaultValue":"Name (CODE) and symbol","description":"Returns searchable text for a currency. Defaults to Name (CODE) and its optional symbol. Search trims the query and matches without case sensitivity."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next code or null and cancellable Dropdown selection details: event, reason, trigger, cancel and isCanceled. Calling cancel() preserves selection and prevents automatic close. Repeated single selection does not emit a change."},{"name":"renderValue","type":"((state: CurrencyPickerState) => ReactNode)","required":false,"defaultValue":null,"description":"Returns selected trigger content from { value, selectedCurrency, disabled }. The default display is the raw code, or the trigger placeholder when null. Trigger children override it."},{"name":"selectedFirst","type":"boolean","required":false,"defaultValue":"false","description":"Moves the matching selected currency before other results. Defaults to false, preserving catalogue order."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled currency code or null for an empty selection. Undefined leaves selection uncontrolled. Empty and unknown strings remain identifiers."}]},{"name":"Trigger","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned trigger content that overrides the selected value display."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger button."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Additionally disables the native trigger button. Root disabled state always takes precedence."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID forwarded to the trigger button."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"placeholder","type":"ReactNode","required":false,"defaultValue":null,"description":"Trigger content displayed when the selected value is null."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the native trigger button. Forward the supplied props and ref when rendering a custom component."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the trigger button."}]},{"name":"Options","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the options wrapper div."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Additionally disables search and every currency option. Root disabled state always takes precedence."},{"name":"emptyLabel","type":"ReactNode","required":false,"defaultValue":"No results","description":"Content announced when no currencies match. Defaults to No results."},{"name":"listLabel","type":"string","required":false,"defaultValue":null,"description":"Accessible name for the selection listbox. Defaults to the registered Dropdown title or trigger name. Native accessible attributes on Options target only its wrapper."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the options wrapper div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the non-interactive wrapper div. Forward the supplied props and ref when rendering a custom component. Use searchProps.render to customize the input."},{"name":"searchable","type":"boolean","required":false,"defaultValue":"true","description":"Renders a search input above the options. Defaults to true."},{"name":"searchLabel","type":"string","required":false,"defaultValue":"Search","description":"Search placeholder and accessible name. Defaults to Search."},{"name":"searchProps","type":"DropdownSearchProps","required":false,"defaultValue":null,"description":"Native input attributes, ref, render, and controlled or uncontrolled query props forwarded to Dropdown.Search. Use value with onValueChange or defaultValue."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the options wrapper div."}]}]}},{"name":"ProgressRing","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: ProgressRing\ndescription: Show measured or indeterminate progress in a compact circular indicator.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ProgressRingReference from '/snippets/ui/generated/feedback/progress-ring.mdx';\n\n## Overview\n\n`ProgressRing` supplies a circular appearance for [Progress](/ui/primitives/feedback/progress). It shares the root's custom range, null, formatting, labeling, native prop, ref, and render contract. Optional children display a preformatted value beside the ring.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressring-progressring--display\"\n title=\"Progress ring example\"\n height={90}\n/>\n\n## Usage\n\nSupply the raw controlled value and an accessible name. Use `aria-valuetext` when a formatted value explains progress more clearly than a percentage.\n\n```tsx\nimport { ProgressRing } from 'twenty-ui/primitives/feedback';\n\nexport const ImportProgress = () => (\n <ProgressRing\n value={600}\n max={1000}\n aria-label=\"Importing records\"\n aria-valuetext=\"600 of 1,000 records\"\n >\n 600 / 1,000\n </ProgressRing>\n);\n```\n\nUse `aria-labelledby` to associate the ring with an existing visible label, or compose `Progress.Label` as a child. Preformatted children do not automatically provide the ring's accessible name.\n\n## Controlled progress and ranges\n\nThe application calculates `value` and formats display content. The ring does not fetch data, advance progress, or calculate quotas. `min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for semantic values and arc geometry. The arc fills by the normalized percentage, including when the minimum is nonzero.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressring-progressring--custom-range\"\n title=\"Circular progress in a custom range\"\n height={90}\n/>\n\nPass `value={null}` for indeterminate progress. The ring omits `aria-valuenow` and displays an indeterminate arc. Non-finite values also remain indeterminate; they do not become zero or completion. Display content stays controlled by the application.\n\nUse `locale`, `format`, and `getAriaValueText` as described in [Progress](/ui/primitives/feedback/progress). Compose `Progress.Value` to display the root's formatted value.\n\nUse [ProgressBar](/ui/primitives/feedback/progress-bar) for horizontal progress or [MetricRow](/ui/components/data-display/metric-row) for a label and aligned value.\n\n## Appearance and composition\n\n`size=\"md\"` renders a 16px ring; `size=\"sm\"` renders a 14px ring. Both use a 2px stroke and fill clockwise from the top. `barColor` accepts CSS colors, including theme variables. The SVG is decorative and hidden from accessibility APIs.\n\nValue changes animate for 300ms. Reduced-motion preferences disable the transition and indeterminate rotation. Native attributes, `className`, `style`, and `ref` target the outer progress element. `className` and `style` can receive the progress state. `render` can replace the root while retaining its semantics.\n\n## Props\n\n<ProgressRingReference />\n\n<PageBanner illustration=\"card-page-usage-limits\" />\n","api":{"name":"ProgressRing","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/progress-ring","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name identifying the measured operation."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the visible label that names the operation."},{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"Human-readable progress value overriding the default formatted value."},{"name":"barColor","type":"string","required":false,"defaultValue":null,"description":"CSS color of the filled arc. Defaults to the blue theme color."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional preformatted value or Progress parts displayed before the ring."},{"name":"className","type":"string | ((state: ProgressRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the progress root, or a callback receiving its status."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number | null) => string)","required":false,"defaultValue":null,"description":"Receives the formatted value and raw value, including null, and returns an accessible value description."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format the value. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"Inclusive maximum. Defaults to 100."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"Inclusive minimum. Defaults to 0."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>","required":false,"defaultValue":null,"description":"Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Ring diameter: sm (14px) or md (16px). Defaults to md."},{"name":"style","type":"CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the progress root, or a callback receiving its status."},{"name":"value","type":"number | null","required":true,"defaultValue":null,"description":"Controlled value in the min/max range. Use null for indeterminate progress."}]}},{"name":"DetailsRow","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: DetailsRow\ndescription: Align detail labels with wrapping values and optional actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DetailsRowReference from '/snippets/ui/generated/components/data-display/details-row.mdx';\n\n## Overview\n\n`DetailsRow` pairs a label with a value in a description list. Add a decorative icon, multiple value items, or an action supplied by your application.\n\n<StoryEmbed\n storyId=\"ui-data-display-detailsrow--display\"\n title=\"Details row example\"\n height={220}\n/>\n\n## Usage\n\n```tsx\nimport { DetailsRow } from 'twenty-ui/components/data-display';\nimport { IconNotes, IconTag, IconUser } from 'twenty-ui/icon';\nimport { Chip, Tag } from 'twenty-ui/primitives/data-display';\nimport { Card } from 'twenty-ui/primitives/surfaces';\n\nexport const CollectionDetails = () => (\n <Card.Root>\n <Card.Content>\n <dl style={{ display: 'grid', gap: 8, margin: 0 }}>\n <DetailsRow label=\"Owner\" startIcon={<IconUser size={16} />}>\n <Chip>Jordan Lee</Chip>\n </DetailsRow>\n <DetailsRow label=\"Categories\" startIcon={<IconTag size={16} />}>\n <Tag color=\"blue\">Research</Tag>\n <Tag color=\"purple\">Design</Tag>\n </DetailsRow>\n <DetailsRow label=\"Description\" startIcon={<IconNotes size={16} />}>\n A shared collection of customer research and design decisions.\n </DetailsRow>\n </dl>\n </Card.Content>\n </Card.Root>\n);\n```\n\nPlace each row directly inside a `dl`. Pass the label through `label` and its value through `children`. The application owns labels, localization, formatted values, and placeholders for missing values.\n\n## Alignment and wrapping\n\nLabels and values wrap rather than truncate. Multiple value items, such as chips or tags, wrap onto additional lines. Rows align their content at the top as that content grows.\n\nThe label column defaults to `7rem` and is capped at 40% of the row's width to leave space for the value in narrow containers. Set the same `labelWidth` on sibling rows to adjust their alignment. Numbers use pixels; CSS lengths such as `'8rem'` are also supported.\n\n```tsx\nimport { DetailsRow } from 'twenty-ui/components/data-display';\n\nexport const PublicationDetails = () => (\n <dl style={{ display: 'grid', gap: 8, margin: 0, maxWidth: 360 }}>\n <DetailsRow label=\"Primary contributor\" labelWidth={128}>\n Jordan Lee\n </DetailsRow>\n <DetailsRow label=\"Review notes\" labelWidth={128}>\n Include findings from the customer interviews before publication.\n </DetailsRow>\n </dl>\n);\n```\n\n## Actions\n\nUse `action` for a control beside the value. The row does not add editing, click, or keyboard behavior. Supply a control with an accessible name and connect its handler to the application behavior.\n\n```tsx\nimport { DetailsRow } from 'twenty-ui/components/data-display';\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { IconCopy } from 'twenty-ui/icon';\n\nexport const ContactDetails = ({ onCopy }: { onCopy: () => void }) => (\n <dl style={{ margin: 0 }}>\n <DetailsRow\n label=\"Email\"\n action={\n <LightIconButton aria-label=\"Copy email address\" onClick={onCopy}>\n <IconCopy size={16} />\n </LightIconButton>\n }\n >\n [email protected]\n </DetailsRow>\n </dl>\n);\n```\n\n## Composition and accessibility\n\nEach row renders a `div` grouping with a `dt` label and a `dd` containing the value and optional action. The caller supplies the enclosing `dl`. Provide meaningful text in the label. The optional `startIcon` is hidden from assistive technology, and the caller controls its dimensions.\n\nNative attributes, `className`, `style`, and `ref` target the outer `div`. When using `render` with a custom wrapper, preserve that `div` directly inside the `dl` and forward all supplied props and the ref. Keep actions inside their slot so the term and definition remain the row's direct children.\n\nUse [MetricRow](/ui/components/data-display/metric-row) for a metric with optional progress. `DetailsRow` provides only the label, value, and action layout.\n\n## Props\n\n<DetailsRowReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"DetailsRow","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/details-row","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional action content beside the value. The caller supplies controls, accessible names, and handlers."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Value content rendered in the description definition. Text and multiple items wrap within the available space."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row root."},{"name":"label","type":"ReactNode","required":true,"defaultValue":null,"description":"Visible label rendered as the description term."},{"name":"labelWidth","type":"Width<string | number>","required":false,"defaultValue":"7rem","description":"Preferred label column width. Numbers use pixels. The column is capped at 40% of the row width; use the same width for aligned sibling rows."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the row root div."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the row root. Preserve a div directly inside a dl and forward its props and ref to retain valid description-list grouping."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative node before the label. The caller controls icon dimensions."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row root."}]}},{"name":"MetricRow","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: MetricRow\ndescription: Align a metric label and formatted value with optional progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport MetricRowReference from '/snippets/ui/generated/components/data-display/metric-row.mdx';\n\n## Overview\n\n`MetricRow` aligns a label, optional icon, and preformatted value. An optional [ProgressRing](/ui/primitives/feedback/progress-ring) uses the visible label as its accessible name.\n\n<StoryEmbed\n storyId=\"ui-data-display-metricrow--display\"\n title=\"Metric row example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { MetricRow } from 'twenty-ui/components/data-display';\nimport { IconFiles } from 'twenty-ui/icon';\n\nexport const ImportMetric = () => (\n <MetricRow\n startIcon={<IconFiles size={14} />}\n value=\"75 of 100\"\n progress={75}\n >\n Imported files\n </MetricRow>\n);\n```\n\nPass a nonempty text label as required children and the formatted value through `value`. Add `progress` when the metric has a known percentage.\n\nThe application owns calculations, units, number formatting, and the meaning of the metric. `progressColor` accepts a CSS color for the filled arc.\n\n## Values without progress\n\nOmit `progress` to show a plain value. Numeric zero displays as `0`; content is never replaced with a placeholder. Supply your own placeholder when data is unavailable.\n\n```tsx\nimport { MetricRow } from 'twenty-ui/components/data-display';\n\nexport const CompletedMetric = () => (\n <MetricRow value={0}>Completed imports</MetricRow>\n);\n```\n\n## Composition and accessibility\n\nLabel content accepts nodes. Its accessible text names the progress ring through `aria-labelledby`, including nested text. Provide a meaningful visible label. A nonempty string value is also exposed as its accessible value text. For formatted value content, supply `progressValueText` when a percentage does not describe the metric fully. This text overrides the string value fallback. Without it, other content keeps the ring's percentage value text. An empty `progressValueText` also uses the percentage, including when `value` is a string. The optional `startIcon` node is decorative. The caller controls its dimensions and stroke.\n\n```tsx\nimport { MetricRow } from 'twenty-ui/components/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const FormattedStorageMetric = () => (\n <MetricRow\n value={<Text render={<bdi />}>12 / 20 GB</Text>}\n progress={60}\n progressValueText=\"12 of 20 gigabytes used\"\n >\n <Text render={<strong />}>Storage</Text>\n </MetricRow>\n);\n```\n\nReplace `startIcon={IconDatabase}` with `startIcon={<IconDatabase size={14} />}`. Values stay preformatted by the application.\n\nNative attributes, `className`, `style`, and `ref` target the outer row. `render` can replace that element. Progress stays controlled and bounded to 0 to 100, with the same reduced-motion behavior as `ProgressRing`.\n\n## Props\n\n<MetricRowReference />\n\n<PageBanner illustration=\"dashboards\" />\n","api":{"name":"MetricRow","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/metric-row","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Label content whose accessible text also names the optional progress ring."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row root."},{"name":"progress","type":"number","required":false,"defaultValue":null,"description":"Optional controlled progress from 0 to 100. Omitting it displays the value without a ring."},{"name":"progressColor","type":"string","required":false,"defaultValue":null,"description":"CSS color of the filled arc when progress is provided."},{"name":"progressValueText","type":"string","required":false,"defaultValue":null,"description":"Accessible value text for the progress ring. Nonempty text overrides the string value fallback; an empty string uses the ring percentage. Supply it when formatted content needs more context than a percentage."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the row root element while preserving its contents."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative node content before the label. The caller controls icon geometry."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row root."},{"name":"value","type":"ReactNode","required":true,"defaultValue":null,"description":"Preformatted value displayed at the end of the row. Nonempty string values also supply the progress ring accessible value text."}]}},{"name":"Shortcut","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: Shortcut\ndescription: Display simultaneous key combinations and sequential shortcuts.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ShortcutReference from '/snippets/ui/generated/typography/shortcut.mdx';\n\n## Overview\n\nImport `Shortcut` and `formatShortcut` from `twenty-ui/primitives/typography`. Both share the same model, symbols, and separators. Register shortcuts in your application. `Shortcut` only formats the hint; it does not register keyboard actions. Native attributes, event handlers, styles, class names, and refs target its outer span. `ShortcutProps` and `ShortcutFormatOptions` are public types.\n\n<StoryEmbed\n storyId=\"ui-typography-shortcut--display\"\n title=\"Shortcut presentations\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Shortcut } from 'twenty-ui/primitives/typography';\n\nexport const SearchShortcut = () => <Shortcut shortcut={['Mod', 'K']} />;\n```\n\n## Combinations and sequences\n\n```tsx\nimport { Shortcut, formatShortcut } from 'twenty-ui/primitives/typography';\n\nexport const ShortcutExamples = () => (\n <>\n <Shortcut shortcut={['Enter']} />\n <Shortcut shortcut={['Mod', 'K']} />\n <Shortcut shortcut={[['G'], ['P']]} sequenceJoinLabel=\"then\" />\n <Shortcut\n shortcut={[\n ['Mod', 'K'],\n ['Mod', 'C'],\n ]}\n sequenceJoinLabel=\"then\"\n />\n </>\n);\n\nconst hint = formatShortcut({\n shortcut: ['Mod', 'Enter'],\n});\n```\n\nA flat array is a simultaneous combination: `['Mod', 'K']` means press Mod and K together. A nested array is an ordered sequence: `[['G'], ['P']]` means press G, then P. Each nested array is one combination, so `[['Mod', 'K'], ['Mod', 'C']]` means press Mod and K, then Mod and C. Use a one-element array for a single key. Both array forms can be readonly.\n\n`Mod` and `CommandOrControl` display Command on macOS and iOS, and Control elsewhere. Explicit `Command`, `Control`, `Alt`, and `Enter` keys also have display labels. Other strings are displayed as supplied. Device detection is safe without browser globals; `platform` optionally overrides it with `mac` or `other`.\n\nUse `sequenceJoinLabel` for localized join text. `combinationSeparator` can preserve a host convention such as `+`. The default text separator is empty on Apple devices and a space elsewhere. `variant` selects `keys`, `text`, or `button`. `visibility=\"desktop\"` hides the hint at mobile viewport widths while `always` remains visible.\n\nKey symbols have readable accessible names. Use `accessibleKeyLabels` to localize individual key names in screen reader output. Supply `aria-label` or `aria-labelledby` for a localized name for the whole shortcut, or `aria-hidden` for a decorative hint. Buttons keep their action names and hide their decorative hints on mobile. Menu and list rows keep their hints visible.\n\n## Appearance\n\nUse `keys` for individual keycaps, `text` for an inline hint, or `button` for the compact hint inside an action. These variants only change the presentation.\n\n<StoryEmbed\n storyId=\"ui-typography-shortcut--catalog\"\n title=\"Shortcut appearance variants\"\n height={160}\n/>\n\n## Migration\n\n| Previous prop | Replacement |\n| ----------------------------------------- | ---------------------------------------------------------- |\n| Button `hotkeys={['⌘', 'K']}` | `shortcut={['Mod', 'K']}` |\n| ListItem sequential `hotkeys` / `hotKeys` | `shortcut={[['G'], ['P']]}` |\n| `hotkeysJoinLabel` / `hotKeysJoinLabel` | `shortcutJoinLabel` on Button, ListItem and Dropdown parts |\n| Manual tooltip key concatenation | `formatShortcut({ shortcut: ['Mod', 'Enter'] })` |\n\nFlat stored arrays that represent successive key presses need nesting before being passed to `shortcut`: `hotKeys.map((key) => [key])`. Arrays that represent simultaneous keys can be passed directly. Key strings remain literal tokens, so `['Mod', '+']` contains a plus key and `['Space']` contains the Space key; no shortcut-string parsing is required.\n\n## Props\n\n<ShortcutReference />\n\n<PageBanner illustration=\"card-page-command-menu\" />\n","api":{"name":"Shortcut","entryPoint":"twenty-ui/primitives/typography","slug":"typography/shortcut","props":[{"name":"accessibleKeyLabels","type":"Readonly<Record<string, string>>","required":false,"defaultValue":null,"description":"Optional localized names for individual keys in screen reader output."},{"name":"combinationSeparator","type":"string","required":false,"defaultValue":null,"description":"Optional separator between simultaneous keys. Defaults to no separator on Apple devices and a space elsewhere."},{"name":"platform","type":"\"mac\" | \"other\"","required":false,"defaultValue":null,"description":"Optional mac or other platform override. Defaults to server-safe device detection."},{"name":"sequenceJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequence steps. Defaults to then."},{"name":"shortcut","type":"ShortcutDefinition","required":true,"defaultValue":null,"description":"Flat key array for a simultaneous combination, or nested key arrays for an ordered sequence of combinations."},{"name":"variant","type":"\"button\" | \"keys\" | \"text\"","required":false,"defaultValue":"keys","description":"Keycaps, inline text, or a separated button hint."},{"name":"visibility","type":"\"always\" | \"desktop\"","required":false,"defaultValue":"always","description":"Always visible by default. Desktop hints hide on mobile viewports."}]}},{"name":"VisuallyHidden","entryPoint":"twenty-ui/primitives/accessibility","content":"---\ntitle: VisuallyHidden\ndescription: Keep supporting text available to assistive technology without displaying it visually.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport VisuallyHiddenReference from '/snippets/ui/generated/accessibility/visually-hidden.mdx';\n\n## Overview\n\n`VisuallyHidden` renders a visually hidden `span`. Its content stays in the accessibility tree and can supply an accessible name. It accepts native span props, a span ref, and Base UI `render` composition. Import `VisuallyHiddenProps` from the same entry point.\n\n<StoryEmbed\n storyId=\"ui-accessibility-visuallyhidden--display\"\n title=\"Visually hidden example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { VisuallyHidden } from 'twenty-ui/primitives/accessibility';\nimport { IconPlus } from 'twenty-ui/icon';\n\ntype AddRecordActionProps = { onAdd: () => void };\n\nexport const AddRecordAction = ({ onAdd }: AddRecordActionProps) => (\n <Button onClick={onAdd}>\n <IconPlus aria-hidden />\n <VisuallyHidden>Add record</VisuallyHidden>\n </Button>\n);\n```\n\nUse a visible label when space permits. For controls that already accept `aria-label`, that attribute is another way to supply an accessible name.\n\n## Hidden content\n\nPlace supporting text inside the wrapper. Avoid placing focusable controls inside it: the wrapper stays visually hidden when its children receive focus. It does not add a live region, remove content from assistive technology, or hide confidential data.\n\nUse `id` to associate hidden descriptions with `aria-describedby`. Native attributes, `className`, `style`, and `ref` target the hidden span or the element supplied through `render`. See [accessibility](/ui/accessibility) for labeling and announcement patterns.\n\n## Props\n\n<VisuallyHiddenReference />\n\n<PageBanner illustration=\"page-cover-accessibility\" />\n","api":{"name":"VisuallyHidden","entryPoint":"twenty-ui/primitives/accessibility","slug":"accessibility/visually-hidden","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content hidden visually while remaining available to assistive technology."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render function composed with the hidden span props and ref."}]}},{"name":"ColorSample","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: ColorSample\ndescription: Display a theme color or a custom color alongside a text label.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ColorSampleReference from '/snippets/ui/generated/data-display/color-sample.mdx';\n\n## Overview\n\n`ColorSample` is a non-interactive color swatch. Use it next to a label so the meaning does not depend on color alone. Selection belongs to the surrounding control.\n\n<StoryEmbed\n storyId=\"ui-data-display-colorsample--display\"\n title=\"ColorSample example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { ColorSample } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const PriorityColor = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <ColorSample colorName=\"red\" render={<span />} aria-hidden=\"true\" />\n High priority\n </Text>\n);\n```\n\n`colorName` selects a theme palette entry for the fill and border. `variant` accepts `default` or `circle`. Omitting it uses the default shape.\n\n## Custom colors\n\n```tsx\nimport { ColorSample } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const BrandColor = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <ColorSample\n colorName=\"blue\"\n color=\"#2563eb\"\n render={<span />}\n aria-hidden=\"true\"\n />\n Brand blue\n </Text>\n);\n```\n\nA custom `color` overrides the fill; `colorName` remains required and still determines the border color. Native props, `className`, `style`, and `ref` target the swatch div. `render` accepts an element or callback through Base UI composition, for example a span inside text. Consumer styles override the default fill, border, or geometry. Decorative swatches use `aria-hidden=\"true\"`; a standalone meaningful swatch uses `role=\"img\"` with `aria-label` or `aria-labelledby`. To offer selectable colors, compose the swatch inside a labeled [ListItem](/ui/primitives/navigation/list-item).\n\n## Migration\n\n`ColorSampleProps` and `ColorSampleVariant` remain available from the data-display family. The unused `pipeline` variant is removed. Product-specific indicators belong in the application, using native styles or composition. Default and circle swatches keep their existing appearance.\n\n## Props\n\n<ColorSampleReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n","api":{"name":"ColorSample","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/color-sample","props":[{"name":"aria-hidden","type":"Booleanish","required":false,"defaultValue":null,"description":"Mark decorative swatches as hidden from assistive technology."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name when the caller supplies role=\"img\"."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the swatch class."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"CSS color that overrides the background; the border still uses `colorName`."},{"name":"colorName","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"turquoise\" | \"violet\" | \"yellow\"","required":true,"defaultValue":null,"description":"Theme color used for the background and border. Required even when `color` overrides the background."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the swatch div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles merged with the swatch color defaults. Explicit styles win."},{"name":"variant","type":"\"circle\" | \"default\"","required":false,"defaultValue":null,"description":"Generic swatch shape: `default` or `circle`. Omitting it uses the default shape."}]}},{"name":"Badge","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Badge\ndescription: Display compact inline information with caller-provided content.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport BadgeReference from '/snippets/ui/generated/data-display/badge.mdx';\n\n## Overview\n\n`Badge` displays compact inline information, including short labels and counts. Use [Tag](/ui/primitives/data-display/tag) for categories, [Chip](/ui/primitives/data-display/chip) for compact controls, or [Status](/ui/primitives/data-display/status) for a named state with an indicator.\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--display\"\n title=\"Badge example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\n\nexport const PreviewLabel = () => <Badge>Preview</Badge>;\n```\n\nPass text, numbers, or nodes as children. Badge displays the content you supply and adds no count formatting or visibility rules. The default element is a non-interactive `span`.\n\n## With an icon\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { IconPaperclip } from 'twenty-ui/icon';\n\nexport const AttachmentLabel = () => (\n <Badge>\n <IconPaperclip size={12} aria-hidden />\n Attachment\n </Badge>\n);\n```\n\nIcons are ordinary child nodes. Give decorative icons `aria-hidden` and keep a visible label to explain the content.\n\n## Appearance\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--catalog\"\n title=\"Badge sizes and shapes\"\n height={200}\n/>\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const BadgeAppearances = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <Badge size=\"sm\" color=\"tertiary\" shape=\"pill\">\n Preview\n </Badge>\n <Badge size=\"md\" color=\"inherit\">\n In review\n </Badge>\n <Badge size=\"xs\" color=\"primary\" shape=\"circle\">\n 3\n </Badge>\n <Badge size=\"xs\" color=\"secondary\" shape=\"circle\">\n 12\n </Badge>\n <Badge color=\"accent\">Last used</Badge>\n </Text>\n);\n```\n\n`size` accepts `xs`, `sm`, or `md`. `color` accepts `tertiary`, `inherit`, `primary`, `secondary`, or `accent`. The `accent` treatment pairs an accent-tertiary fill with accent11 text in both themes. The solid `primary` treatment keeps its blue fill and on-accent text. `shape` accepts `pill` or `circle`. The defaults are `sm`, `tertiary`, and `pill`. The circular treatment has a fixed width equal to its height. Use `pill` for longer content, including abbreviated counts.\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--colors\"\n title=\"Badge text colors\"\n height={140}\n/>\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--accent\"\n title=\"Soft accent badges in light and dark themes\"\n height={140}\n/>\n\n## Counts and visibility\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype InboxButtonProps = {\n count: number;\n};\n\nexport const InboxButton = ({ count }: InboxButtonProps) => (\n <Button aria-label={`Inbox, ${count} unread messages`}>\n Inbox\n {count > 0 && (\n <Badge size=\"xs\" color=\"primary\" shape=\"pill\" aria-hidden>\n {count > 99 ? '99+' : count}\n </Badge>\n )}\n </Button>\n);\n```\n\nYour application owns number formatting, abbreviations, clamping, zero visibility, and translated labels. Include the full meaning in the surrounding control's accessible name when its compact count is decorative. A standalone badge can use native accessible attributes, including `aria-label` or `aria-labelledby`.\n\n## Native composition\n\n```tsx\nimport { useRef } from 'react';\nimport { Badge } from 'twenty-ui/primitives/data-display';\n\nexport const BuildStatus = () => {\n const badgeRef = useRef<HTMLSpanElement>(null);\n\n return (\n <Badge ref={badgeRef} title=\"Current build status\" data-build=\"preview\">\n Preview\n </Badge>\n );\n};\n```\n\nNative attributes, event handlers, `className`, `style`, and `ref` target the actual root element. `render` accepts an element or callback through Base UI composition. Choose an appropriate native owner for interactive content:\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const ReleaseLink = () => (\n <Badge render={<Button href=\"#release-notes\" size=\"sm\" />}>\n Release notes\n </Badge>\n);\n```\n\nThe rendered Button owns navigation behavior and link semantics. Badge keeps its presentational default and does not infer interaction from its content.\n\n## Props\n\nTypes and defaults are generated from the public `BadgeProps` type. Native attributes and event handlers are also accepted.\n\n<BadgeReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Badge","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/badge","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-provided text, numbers, icons, or other inline content."},{"name":"color","type":"\"accent\" | \"inherit\" | \"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"tertiary","description":"Neutral tertiary, inherited text, solid primary accent, soft accent tint, or secondary treatment."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default span. Native props, handlers, and the ref target the rendered element."},{"name":"shape","type":"\"circle\" | \"pill\"","required":false,"defaultValue":"pill","description":"Rounded pill label or fixed circle with width equal to its height. Use pill for longer content."},{"name":"size","type":"\"md\" | \"sm\" | \"xs\"","required":false,"defaultValue":"sm","description":"Compact height, font size, and spacing: xs, sm, or md."}]}},{"name":"Banner","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Banner\ndescription: Feedback content with independent status, appearance, and palette.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport BannerReference from '/snippets/ui/generated/feedback/banner.mdx';\n\n## Overview\n\n`Banner` lays out caller-provided content, an optional `icon` node and an optional `action` node. `status` describes feedback meaning: `neutral`, `info`, `success`, `warning` or `error`. `variant` selects `solid` or `soft` appearance. An explicit `color` overrides the status palette without changing its meaning.\n\nDefaults are `status=\"info\"` and `variant=\"solid\"`. The default status palettes are gray, blue, green, orange and red, respectively.\n\n<StoryEmbed\n storyId=\"ui-feedback-banner--display\"\n title=\"Banner example\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { Banner } from 'twenty-ui/primitives/feedback';\n\nexport const SyncBanner = () => (\n <Banner status=\"info\" variant=\"solid\">\n Contact sync is temporarily paused. Your saved records remain available.\n </Banner>\n);\n```\n\n## Actions and appearance\n\n<StoryEmbed\n storyId=\"ui-feedback-banner--catalog\"\n title=\"Banner feedback palettes and variants\"\n height={560}\n/>\n\n```tsx\nimport { Banner } from 'twenty-ui/primitives/feedback';\nimport { IconInfoCircle } from 'twenty-ui/icon';\n\nexport const SyncBanner = ({ onRetry }: { onRetry: () => void }) => (\n <Banner\n status=\"error\"\n variant=\"soft\"\n color=\"blue\"\n icon={<IconInfoCircle aria-hidden=\"true\" />}\n action={<Banner.Action onClick={onRetry}>Retry sync</Banner.Action>}\n >\n Contact sync could not finish.\n </Banner>\n);\n```\n\n`Banner.Action` provides a small outline button that inherits the banner’s displayed color, including explicit palette overrides and solid appearances. It supports Button interactions, links, refs and custom rendering. The `action` slot also accepts arbitrary controls.\n\nThe root target is a `div`. Native attributes, event handlers, `className`, `style` and `ref` apply to that root. `render` accepts a Base UI element or callback; the callback receives native props and ref plus resolved `status`, `variant` and `color` state. Preserve the supplied props and ref when composing another element.\n\n```tsx\nimport { Banner } from 'twenty-ui/primitives/feedback';\n\nexport const SyncResult = () => (\n <Banner\n status=\"success\"\n variant=\"soft\"\n role=\"status\"\n aria-live=\"polite\"\n aria-atomic=\"true\"\n render={<section aria-label=\"Sync result\" />}\n >\n Contacts are up to date.\n </Banner>\n);\n```\n\nStatus does not automatically assign `role`, `aria-live` or announcements. Choose them at the caller when updates should be announced. Supply accessible names for controls and mark decorative icon nodes with `aria-hidden`. The caller owns visibility and dismissal.\n\n## Dismissal\n\nPass `onDismiss` to show a 24px ghost close control at the logical inline end. The control inherits the banner color and has `type=\"button\"`. `closeLabel` defaults to `Close`; supply localized text in your application. Balanced inline spacing keeps centered content and actions clear of the control.\n\nThe caller owns visibility. Activating the close control calls `onDismiss` and leaves the banner mounted until its caller updates state. Other actions remain in the `action` slot.\n\n```tsx\nimport { useState } from 'react';\nimport { Banner } from 'twenty-ui/primitives/feedback';\n\nexport const DismissibleSyncBanner = () => {\n const [isVisible, setIsVisible] = useState(true);\n\n return isVisible ? (\n <Banner\n onDismiss={() => setIsVisible(false)}\n closeLabel=\"Dismiss sync message\"\n >\n Contacts are syncing in the background.\n </Banner>\n ) : null;\n};\n```\n\n<StoryEmbed\n storyId=\"ui-feedback-banner--dismissible\"\n title=\"Dismissible banner\"\n height={160}\n/>\n\n## Migration\n\nReplace `variant=\"primary\"` with `variant=\"solid\"` and `variant=\"secondary\"` with `variant=\"soft\"`. Replace `color=\"danger\"` with `status=\"error\"`, or `color=\"red\"` when only the palette should change. Blue information banners can use `status=\"info\"`.\n\n## Props\n\n<BannerReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Banner","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/banner","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trailing ReactNode. Banner.Action supplies a small outline action that inherits the resolved banner color; arbitrary controls are also accepted."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-provided content, including text, links and controls."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged onto the root div or composed element."},{"name":"closeLabel","type":"string","required":false,"defaultValue":"Close","description":"Accessible label for the close control. Defaults to Close; supply localized text when needed."},{"name":"color","type":"\"blue\" | \"gray\" | \"green\" | \"orange\" | \"red\"","required":false,"defaultValue":"status palette","description":"Palette override: gray, blue, green, orange or red. When omitted, status selects the corresponding palette."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional leading ReactNode. The caller supplies decorative or accessible icon semantics."},{"name":"onDismiss","type":"(() => void)","required":false,"defaultValue":null,"description":"Renders a 24px ghost close control and calls this callback when activated. The caller owns visibility."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or to the DOM element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, BannerState>","required":false,"defaultValue":null,"description":"Base UI element or render callback. The callback receives native props/ref and resolved status, variant and color state."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"info","description":"Feedback meaning: neutral, info, success, warning or error. Defaults to info. Does not assign a role or live region."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root div or composed element."},{"name":"variant","type":"\"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Solid or soft appearance. Defaults to solid, independently of status."}],"parts":[{"name":"Action","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Loader","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Loader\ndescription: Display a compact animated loading indicator beside a status label.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport LoaderReference from '/snippets/ui/generated/feedback/loader.mdx';\n\n## Overview\n\n`Loader` shows an animated dot inside a small bordered capsule. Use it while an operation is in progress and the percentage is unknown. For numeric progress, use [ProgressBar](/ui/primitives/feedback/progress-bar).\n\n<StoryEmbed\n storyId=\"ui-feedback-loader--display\"\n title=\"Loader example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Loader } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype SaveFeedbackProps = { isSaving: boolean };\n\nexport const SaveFeedback = ({ isSaving }: SaveFeedbackProps) => (\n <Text\n render={<div />}\n role=\"status\"\n style={{ display: 'flex', alignItems: 'center', gap: 8 }}\n >\n {isSaving && <Loader color=\"blue\" aria-hidden=\"true\" render={<span />} />}\n {isSaving ? 'Saving changes' : 'Changes saved'}\n </Text>\n);\n```\n\nPlace visible status text beside the loader in a wrapper. The loader is a fixed-size visual indicator and does not accept children.\n\nThe application owns loading state. Keep the status wrapper mounted so text updates can be announced. The loader assigns no label or live-region role by default. Use `aria-hidden=\"true\"` when surrounding text or a button already supplies loading feedback.\n\n## Native composition and labeling\n\nNative props, `className`, `style`, and `ref` target the container div. `render` accepts an element or callback through Base UI composition. Styles override color defaults. `LoaderProps` is exported from the feedback family.\n\nFor a standalone indicator, provide an explicit status role and accessible name. The animated dot remains decorative.\n\n```tsx\nimport { Loader, type LoaderProps } from 'twenty-ui/primitives/feedback';\n\nconst loadingProps: LoaderProps = {\n role: 'status',\n 'aria-label': 'Loading results',\n color: 'blue',\n};\n\nexport const LoadingResults = () => (\n <Loader {...loadingProps} render={<span />} />\n);\n```\n\nUse `aria-labelledby` instead when visible text names the status. Keep a live-region owner mounted when it needs to announce changing text. The application owns when feedback appears and what it says.\n\n## Color\n\nPass a theme palette color to set both the border and dot. Without a color, the loader inherits a surrounding button color when available, otherwise it uses the tertiary text color. For a button action, prefer [Button's loading state](/ui/primitives/input/button#state-ownership), which keeps the feedback inside the control.\n\n## Props\n\n<LoaderReference />\n\n<PageBanner illustration=\"card-page-background-jobs\" />\n","api":{"name":"Loader","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/loader","props":[{"name":"aria-hidden","type":"Booleanish","required":false,"defaultValue":null,"description":"Hide a decorative loader when another element supplies loading feedback."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name for a labeled loader status."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of text that names the loader status."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the loader container class."},{"name":"color","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"turquoise\" | \"violet\" | \"yellow\"","required":false,"defaultValue":null,"description":"Theme color for the animated dot and border. When omitted, inherits the button color if available, otherwise the tertiary text color."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the container div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Supply status to expose loading feedback as a live region. No role is assigned by default."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles merged with the loader color defaults. Explicit styles win."}]}},{"name":"Skeleton","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Skeleton\ndescription: Show themed placeholder shapes while content loads.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport SkeletonReference from '/snippets/ui/generated/feedback/skeleton.mdx';\n\n## Overview\n\n`Skeleton` provides a placeholder shape with theme colors and a moving highlight. Compose shapes in the layout of the content being loaded. The application owns loading state and feature-specific layouts.\n\n<StoryEmbed\n storyId=\"ui-feedback-skeleton--display\"\n title=\"Skeleton shapes\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { Skeleton, SKELETON_HEIGHT_SIZES } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const LoadingProfile = () => (\n <Text render={<div />} style={{ display: 'flex', gap: 16 }}>\n <Skeleton width={40} height={40} borderRadius=\"50%\" />\n <Text\n render={<div />}\n style={{ display: 'flex', flexDirection: 'column', gap: 8 }}\n >\n <Skeleton width={180} height={SKELETON_HEIGHT_SIZES.s} />\n <Skeleton width={120} height={SKELETON_HEIGHT_SIZES.xs} />\n </Text>\n </Text>\n);\n```\n\nSkeleton renders as a block and never grows wider than its container. Use `layout=\"inline\"` to place a placeholder inside a line of text.\n\nNumeric dimensions use pixels. CSS lengths such as percentages and `em` are also supported. Without dimensions, the placeholder fills the available width and uses the inherited font height. Use equal dimensions and `borderRadius=\"50%\"` for a circle.\n\n`SKELETON_HEIGHT_SIZES` provides shared heights for `xs` (13px), `s` (16px), `m` (24px), `l` (32px) and `xl` (40px). Keep layout-specific dimensions in the application.\n\nEach `Skeleton` renders one placeholder. Keep repeated lines, text-line spacing and loading regions in application components that wrap the primitive.\n\n## Motion and accessibility\n\nSkeletons are decorative and have `aria-hidden=\"true\"` by default. Keep loading announcements in a host-owned status region instead of announcing each shape. Skeleton does not accept children.\n\nThe highlight moves from left to right on a 1.5-second ease-in-out loop and is hidden when the user prefers reduced motion. Pass `animated={false}` for a static placeholder.\n\n<StoryEmbed\n storyId=\"ui-feedback-skeleton--static\"\n title=\"Static skeleton\"\n height={90}\n/>\n\n## Composition and theme\n\nNative props, `className`, `style` and `ref` target the placeholder span. Use `render` to compose another element. Explicit native styles override dimension and color props.\n\nThe base and highlight colors default to the theme tertiary background and lighter transparent background. Use `baseColor`, `highlightColor` and `borderRadius` to override them. Corners stay round, including when the theme uses squircles. The default radius uses the `smRound` theme token (4px). Pass `themeCssVariables.border.radius.mdRound` from `twenty-ui/theme` for 8px corners. Custom pixel and CSS radii remain supported, including `borderRadius={80}` for a narrow capsule and `borderRadius=\"50%\"` for a circle. No skeleton-specific provider or stylesheet import is needed after loading `twenty-ui/style.css` and the UI theme.\n\n## Props\n\n<SkeletonReference />\n\n<PageBanner illustration=\"section-ui-primitives\" />\n","api":{"name":"Skeleton","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/skeleton","props":[{"name":"animated","type":"boolean","required":false,"defaultValue":"true","description":"Animate the highlight by default. Reduced-motion preferences always disable animation."},{"name":"aria-hidden","type":"Booleanish","required":false,"defaultValue":null,"description":"Placeholders are decorative and hidden from assistive technology by default. The host owns loading announcements."},{"name":"baseColor","type":"BackgroundColor","required":false,"defaultValue":null,"description":"Placeholder background color. Defaults to the theme tertiary background."},{"name":"borderRadius","type":"BorderRadius<string | number>","required":false,"defaultValue":null,"description":"Round corner radius in pixels or a CSS length. Defaults to the 4px smRound theme token. Use mdRound for 8px corners or a custom radius for circles and capsules."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the placeholder class."},{"name":"height","type":"Height<string | number>","required":false,"defaultValue":null,"description":"Placeholder height in pixels or a CSS length. Defaults to the inherited font height."},{"name":"highlightColor","type":"BackgroundColor","required":false,"defaultValue":null,"description":"Animated highlight color. Defaults to the theme lighter transparent background."},{"name":"layout","type":"\"block\" | \"inline\"","required":false,"defaultValue":"block","description":"`block` renders a block without a text node. `inline` sizes and aligns the placeholder like a line of text."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the placeholder span, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles merged with the placeholder dimensions and colors. Explicit styles win."},{"name":"width","type":"Width<string | number>","required":false,"defaultValue":null,"description":"Placeholder width in pixels or a CSS length. Defaults to the available width and never exceeds the container."}]}},{"name":"Progress","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Progress\ndescription: Compose accessible progress with shared range, labeling, and value semantics.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ProgressReference from '/snippets/ui/generated/feedback/progress.mdx';\n\n## Overview\n\n`Progress` exposes the installed Base UI parts: `Root`, `Track`, `Indicator`, `Label`, and `Value`. Import them from `twenty-ui/primitives/feedback`. Use [ProgressBar](/ui/primitives/feedback/progress-bar) or [ProgressRing](/ui/primitives/feedback/progress-ring) for a convenient appearance with the same semantic contract.\n\n<StoryEmbed\n storyId=\"ui-feedback-progress--display\"\n title=\"Composed progress example\"\n height={100}\n/>\n\n## Usage\n\n`Root` owns the controlled value and accessible progressbar semantics. `Label` supplies its accessible name. `Value` displays the formatted value. `Track` and `Indicator` describe the visual fill; the indicator width comes from the root's normalized range. The parts do not impose an appearance.\n\n```tsx\nimport { Progress } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportProgress = () => (\n <Progress.Root\n value={70}\n min={20}\n max={120}\n style={{\n display: 'grid',\n gridTemplateColumns: '1fr auto',\n alignItems: 'center',\n gap: 8,\n width: 320,\n maxWidth: '100%',\n }}\n >\n <Progress.Label render={<Text />}>Importing records</Progress.Label>\n <Progress.Value render={<Text />} />\n <Progress.Track\n style={{\n gridColumn: '1 / -1',\n height: 8,\n background: 'var(--t-background-tertiary)',\n }}\n >\n <Progress.Indicator\n style={{\n height: '100%',\n background: 'var(--t-font-color-primary)',\n }}\n />\n </Progress.Track>\n </Progress.Root>\n);\n```\n\nThis range displays `50%` while `aria-valuenow` is `70`, `aria-valuemin` is `20`, and `aria-valuemax` is `120`. The application owns requests, timing, and progress updates. There is no `defaultValue` or automatic advancement.\n\n## Values, ranges, and indeterminate progress\n\n`min` defaults to `0`, and `max` defaults to `100`. Supply finite bounds with `min < max`. Finite values outside the range are clamped for the semantic value, formatted value, and visual fill. Completion occurs at the maximum. Changing the range recalculates the percentage without changing the raw value supplied by the application.\n\nPass `value={null}` when the amount of progress is unknown. The root then has indeterminate status, omits `aria-valuenow`, and uses `indeterminate progress` as its default accessible value text. Non-finite values also remain indeterminate; they are not converted to zero. The raw `Indicator` has no computed percentage width in that state, so the composition chooses its indeterminate appearance.\n\n```tsx\nimport { ProgressBar } from 'twenty-ui/primitives/feedback';\n\nexport const PendingImport = () => (\n <ProgressBar value={null} aria-label=\"Preparing the import\" />\n);\n```\n\n## Labels and formatting\n\nCompose `Progress.Label` inside `Root`, or set native `aria-label` or `aria-labelledby`. Use `aria-valuetext` for a human-readable alternative when a percentage is insufficient.\n\nThe default formatter displays the normalized percentage. `locale` and `format` retain the installed `Intl.NumberFormat` contract; an explicit `format` formats the clamped numeric value. `getAriaValueText(formattedValue, value)` receives that formatted text and the raw application value, including `null`. It changes the accessible value text without changing the fill.\n\n```tsx\nimport { Progress } from 'twenty-ui/primitives/feedback';\n\nexport const RecordCount = () => (\n <Progress.Root\n value={600}\n max={1000}\n format={{ style: 'decimal' }}\n getAriaValueText={(formattedValue) => `${formattedValue} of 1,000 records`}\n >\n <Progress.Label>Importing records</Progress.Label>\n <Progress.Value>\n {(formattedValue) => `${formattedValue} / 1,000`}\n </Progress.Value>\n </Progress.Root>\n);\n```\n\n`Progress.Value` receives both the formatted value and raw value through its optional child callback. For indeterminate progress, the callback receives `indeterminate` as formatted text; without a callback, the value part displays no content. Display content does not automatically become the accessible name or accessible value text.\n\n## Native props, refs, and composition\n\n| Part | Default DOM and ref target |\n| ----------- | -------------------------------------- |\n| `Root` | Outer `div` with progressbar semantics |\n| `Track` | Track `div` |\n| `Indicator` | Fill `div` |\n| `Label` | Label `span` |\n| `Value` | Value `span` |\n\nEvery part preserves native props, refs, and the installed `render` composition contract. Forward the supplied props and ref when replacing an element. `className`, `style`, and `render` callbacks receive the public state with `status`: `progressing`, `complete`, or `indeterminate`. State attributes make the same status available to styles.\n\nThe entry point exports `ProgressStatus` and the `Props` and `State` types for every part, including `ProgressRootProps`, `ProgressRootState`, `ProgressIndicatorProps`, and `ProgressIndicatorState`. Each part forwards native event handlers. Applications own feature choreography and completion callbacks.\n\n## Props\n\n<ProgressReference />\n\n<PageBanner illustration=\"card-page-usage-limits\" />\n","api":{"name":"Progress","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/progress","props":[],"parts":[{"name":"Root","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name identifying the measured operation."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the visible label that names the operation."},{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"Human-readable progress value overriding the default formatted value."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Composed Progress parts and supporting content."},{"name":"className","type":"string | ((state: ProgressRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number | null) => string)","required":false,"defaultValue":null,"description":"Receives the formatted value and raw value, including null, and returns an accessible value description."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format the value. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"Inclusive maximum. Defaults to 100."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"Inclusive minimum. Defaults to 0."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through Root.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."},{"name":"value","type":"number | null","required":true,"defaultValue":null,"description":"Controlled value in the min/max range. Use null for indeterminate progress."}]},{"name":"Track","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The indicator and optional supporting content."},{"name":"className","type":"string | ((state: ProgressTrackState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the track div, or the element composed through Track.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressTrackState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressTrackState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: ProgressIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the indicator div, or the element composed through Indicator.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressIndicatorState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]},{"name":"Value","props":[{"name":"children","type":"((formattedValue: string | null, value: number | null) => ReactNode) | null","required":false,"defaultValue":null,"description":"Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content."},{"name":"className","type":"string | ((state: ProgressValueState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the value span, or the element composed through Value.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressValueState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressValueState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]},{"name":"Label","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Visible text that supplies the accessible name of the root."},{"name":"className","type":"string | ((state: ProgressLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the label span, or the element composed through Label.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressLabelState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]}]}},{"name":"ProgressBar","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: ProgressBar\ndescription: Show measured or indeterminate progress with a horizontal bar.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ProgressBarReference from '/snippets/ui/generated/feedback/progress-bar.mdx';\n\n## Overview\n\n`ProgressBar` supplies a horizontal appearance for [Progress](/ui/primitives/feedback/progress). It preserves the complete root contract, including native attributes, refs, render composition, formatting, custom ranges, and indeterminate progress. Give it an `aria-label` that identifies the operation.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressbar-progressbar--display\"\n title=\"ProgressBar example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { ProgressBar } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype ImportProgressProps = { importedRecords: number | null };\n\nexport const ImportProgress = ({ importedRecords }: ImportProgressProps) => (\n <Text style={{ display: 'grid', gap: 8, width: 300 }}>\n <Text>Importing records: {importedRecords ?? 'preparing'}</Text>\n <ProgressBar\n value={importedRecords}\n max={1000}\n aria-label=\"Importing records\"\n />\n </Text>\n);\n```\n\n## State ownership and ranges\n\n`value` is required and controlled by the application. There is no `defaultValue` mode. The component does not start a request or advance progress by itself. Pass `null` when progress is unknown. Non-finite values also remain indeterminate.\n\n`min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for the semantic value and normalized fill. A value of `70` in the range `20` to `120` fills half the bar and reports `50%`, while `aria-valuenow` stays `70`.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressbar-progressbar--custom-range\"\n title=\"A nonzero minimum and custom maximum\"\n height={80}\n/>\n\nUse `aria-valuetext`, `getAriaValueText`, `locale`, and `format` as described in [Progress](/ui/primitives/feedback/progress). Use composed Progress parts when labels and values need their own visible layout.\n\nUse [Toast](/ui/components/feedback/toast) for notifications with a dismiss countdown and hover pause.\n\n## Appearance and composition\n\n`size` selects a 6px or 8px track. `barColor` and `backgroundColor` accept CSS colors, including theme variables. `withBorderRadius` rounds the track and indicator. `withMinimumFillWidth` keeps a small cosmetic fill only between the minimum and completion. This minimum is at most 12px and half the track width, so a narrow track still distinguishes incomplete progress from completion. It does not fill an empty bar or change semantic values.\n\nNative attributes, `className`, `style`, and `ref` target the root. `className` and `style` can receive the progress state. `render` can replace the root while preserving its semantics. Indeterminate progress has its own appearance without reporting a numeric percentage. Reduced-motion preferences disable fill transitions and indeterminate motion.\n\nCompose [Progress parts](/ui/primitives/feedback/progress) for custom layouts or feature animation. Feature timing, grow-in, glints, springs, and completion callbacks belong to the application composition.\n\n## Migration\n\nReplace `ariaLabel` with native `aria-label`. The `withGrowIn`, `withGlint`, `withSpringFill`, and `onGrowInComplete` props are removed. Implement their appearance, timing, and completion callbacks in an application composition using [Progress parts](/ui/primitives/feedback/progress). Native `onAnimationEnd` remains available on the root.\n\n## Props\n\n<ProgressBarReference />\n\n<PageBanner illustration=\"card-page-usage-limits\" />\n","api":{"name":"ProgressBar","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/progress-bar","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name identifying the measured operation."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the visible label that names the operation."},{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"Human-readable progress value overriding the default formatted value."},{"name":"backgroundColor","type":"string","required":false,"defaultValue":"none","description":"CSS background color of the track."},{"name":"barColor","type":"string","required":false,"defaultValue":null,"description":"CSS color of the filled bar. Defaults to the primary text color."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Additional Progress parts or supporting content inside the root."},{"name":"className","type":"string | ((state: ProgressRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the progress root, or a callback receiving its status."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number | null) => string)","required":false,"defaultValue":null,"description":"Receives the formatted value and raw value, including null, and returns an accessible value description."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format the value. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"Inclusive maximum. Defaults to 100."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"Inclusive minimum. Defaults to 0."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>","required":false,"defaultValue":null,"description":"Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Bar height: sm (6px) or md (8px)."},{"name":"style","type":"CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the progress root, or a callback receiving its status."},{"name":"value","type":"number | null","required":true,"defaultValue":null,"description":"Controlled value in the min/max range. Use null for indeterminate progress."},{"name":"withBorderRadius","type":"boolean","required":false,"defaultValue":"false","description":"Rounds the track and indicator corners."},{"name":"withMinimumFillWidth","type":"boolean","required":false,"defaultValue":"true","description":"Applies a cosmetic minimum of up to 12px, capped at half the track width, only above the minimum and below completion."}]}},{"name":"SegmentedControl","entryPoint":"twenty-ui/components/input","content":"---\ntitle: SegmentedControl\ndescription: Choose one value from a compact group of labeled or icon options.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport SegmentedControlReference from '/snippets/ui/generated/components/input/segmented-control.mdx';\n\n## Overview\n\n`SegmentedControl` is a preset assembled from [Radio](/ui/primitives/input/radio) and [RadioGroup](/ui/primitives/input/radio-group), with joined options. Use it for a short, mutually exclusive choice. For navigation between content panels, use [Tabs](/ui/primitives/navigation/tabs).\n\n<StoryEmbed\n storyId=\"components-input-segmentedcontrol--display\"\n title=\"SegmentedControl example\"\n height={110}\n/>\n\n## Usage\n\nSupply an accessible group name with `aria-label` or `aria-labelledby`. Each option needs a unique string `value`. Selection belongs to the group; options do not have independent checked state.\n\n```tsx\nimport { SegmentedControl } from 'twenty-ui/components/input';\n\nexport const BillingPeriod = () => (\n <SegmentedControl\n aria-label=\"Billing period\"\n name=\"billingPeriod\"\n defaultValue=\"annual\"\n options={[\n { label: 'Annual', value: 'annual' },\n { label: 'Monthly', value: 'monthly' },\n ]}\n />\n);\n```\n\n`defaultValue` initializes selection. The group owns later changes. Add `onValueChange` if you need to observe them without controlling the value.\n\n## Controlled state\n\n```tsx\nimport { useState } from 'react';\nimport { SegmentedControl } from 'twenty-ui/components/input';\n\nexport const BillingPeriod = () => {\n const [period, setPeriod] = useState('annual');\n\n return (\n <SegmentedControl\n aria-label=\"Billing period\"\n name=\"billingPeriod\"\n value={period}\n onValueChange={setPeriod}\n options={[\n { label: 'Annual', value: 'annual' },\n { label: 'Monthly', value: 'monthly' },\n ]}\n />\n );\n};\n```\n\nKeep `value` in application state and update it in `onValueChange`. Do not combine `value` and `defaultValue` or switch ownership modes after mounting.\n\n## Icon options\n\n```tsx\nimport { SegmentedControl } from 'twenty-ui/components/input';\nimport { IconList, IconLayoutKanban } from 'twenty-ui/icon';\n\nexport const RecordLayout = () => (\n <SegmentedControl\n aria-label=\"Record layout\"\n defaultValue=\"list\"\n itemWidth=\"content\"\n options={[\n { value: 'list', startIcon: <IconList />, 'aria-label': 'List' },\n {\n value: 'kanban',\n startIcon: <IconLayoutKanban />,\n 'aria-label': 'Kanban',\n },\n ]}\n />\n);\n```\n\nAn icon-only option requires an `aria-label`. `startIcon` is decorative and hidden from assistive technology. Options with visible text use `label` and may also provide `startIcon`. Set `disabled` on an option to prevent its selection, or on the group to disable every option.\n\n## Keyboard, forms, and direction\n\nTab enters the group; arrow keys move between enabled options and update selection. This follows radio behavior. Dropdown selection groups move focus with arrow keys and select on activation. `itemWidth=\"equal\"` is the default; use `content` when labels should determine widths. Set `name` to include the selected value in native form submission. The preset preserves RadioGroup's `required`, `readOnly`, disabled state, and native form integration. `onValueChange` receives the selected value and Base UI event details, including `reason` and `cancel()`.\n\nFor right-to-left content, pair [DirectionProvider](/ui/primitives/layout/direction-provider) with a matching `dir` attribute. The provider controls directional interaction; `dir` controls the document layout.\n\n## Composition and native props\n\nNative props, `className`, `style`, `render`, and `ref` target the group's `div`. Use `render` to compose that group with another element; preserve its accessible name and radio-group semantics. Options render `span` elements with `role=\"radio\"` and hidden native radio inputs. The preset does not assign tab or tab-panel roles. For custom radio content, per-option native props, or a different radio render target, compose `Radio.Root` and `RadioGroup` directly.\n\n## Props\n\n<SegmentedControlReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"SegmentedControl","entryPoint":"twenty-ui/components/input","slug":"components/input/segmented-control","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Accessible group name. Supply this or `aria-labelledby`."},{"name":"aria-labelledby","type":"string","required":true,"defaultValue":null,"description":"ID of an element that labels the group. Supply this or `aria-label`."},{"name":"className","type":"string | ((state: RadioGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string","required":false,"defaultValue":null,"description":"The uncontrolled value of the radio button that should be initially selected.\n\nTo render a controlled radio group, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the radio inputs.\nUseful when the radio group is rendered outside the form."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Stretch the control to the width of its container."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"itemWidth","type":"\"content\" | \"equal\"","required":false,"defaultValue":"equal","description":"Use equal-width options or size each option to its content."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onValueChange","type":"((value: TValue, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Callback fired when the value changes."},{"name":"options","type":"readonly SegmentedControlOption<TValue>[]","required":true,"defaultValue":null,"description":"Options with a unique string `value`, a `label` or `startIcon`, and optional `disabled`. Icon-only options require an `aria-label`."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to select a different radio button in the group."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Control height: `sm` (24px) or `md` (32px)."},{"name":"style","type":"CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The controlled value of the radio item that should be currently selected.\n\nTo render an uncontrolled radio group, use the `defaultValue` prop instead."},{"name":"variant","type":"\"rectangle\" | \"round\"","required":false,"defaultValue":"round","description":"Shape: `round` is a pill, `rectangle` fills its container with form-field corners."}]}},{"name":"Collapsible","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: Collapsible\ndescription: Compose an accessible trigger and animated panel with controlled or uncontrolled expansion.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CollapsibleReference from '/snippets/ui/generated/layout/collapsible.mdx';\n\n## Overview\n\n`Collapsible` exposes Base UI's Root, Trigger, and Panel contracts. Root owns expansion state, Trigger supplies keyboard activation and the panel relationship, and Panel owns animation and content lifetime.\n\n<StoryEmbed\n storyId=\"ui-layout-collapsible--display\"\n title=\"Collapsible example\"\n height={160}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Collapsible } from 'twenty-ui/primitives/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportDetails = () => (\n <Collapsible.Root defaultOpen style={{ width: 360, maxWidth: '100%' }}>\n <Collapsible.Trigger render={<Button />}>\n Import details\n </Collapsible.Trigger>\n <Collapsible.Panel>\n <Text\n style={{\n paddingTop: 12,\n color: 'var(--t-font-color-secondary)',\n lineHeight: 1.5,\n }}\n >\n Match each CSV column to a record field before importing.\n </Text>\n </Collapsible.Panel>\n </Collapsible.Root>\n);\n```\n\nUse `defaultOpen` for uncontrolled expansion. Use `open` and `onOpenChange` when the application owns the state. The callback receives the requested boolean and Base UI event details, including `reason`, `event`, and `cancel()`. Canceling a change preserves the current state. An externally controlled panel can omit Trigger when its state comes from another control or application condition.\n\nTriggers inherit Root's `disabled` state and can override it with their own `disabled` prop. The native trigger supports Enter and Space and supplies `aria-expanded` and `aria-controls` automatically. Give each trigger a meaningful accessible name.\n\n## Anatomy\n\n```text\nCollapsible.Root\n├── Collapsible.Trigger\n└── Collapsible.Panel\n └── Content\n```\n\n## Native customization\n\nRoot and Panel render a `div`; Trigger renders a `button`. Each part accepts native attributes, handlers, `className`, `style`, refs, and Base UI `render` composition. Class and style callbacks receive the part's state. Forward all supplied props and the ref from custom render components. Set `nativeButton={false}` when Trigger renders a non-button element.\n\nPublic types include `CollapsibleRootProps`, `CollapsibleTriggerProps`, `CollapsiblePanelProps`, the three part state types, and `CollapsibleRootChangeEventDetails` and `CollapsibleRootChangeEventReason`.\n\n## Animation and content lifetime\n\nPanel defaults to `dimension=\"height\"`. Use `dimension=\"width\"` for horizontal expansion and constrain the content's width when needed. `containAnimation` defaults to `true`, clips overflow, and lays content out in a column. Set it to `false` when content needs to overflow during the transition.\n\nPanel's `duration` chooses a theme preset (`instant`, `fast`, `normal`, or `slow`) and defaults to `normal`. Reduced-motion preferences disable the transitions.\n\nPanel unmounts after closing by default. Use `keepMounted` to preserve local content state while hiding the closed panel. `hiddenUntilFound` lets browser page search reveal closed content and takes precedence over `keepMounted`.\n\n## Props\n\n<CollapsibleReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Collapsible","entryPoint":"twenty-ui/primitives/layout","slug":"layout/collapsible","props":[],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: CollapsibleRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Initial uncontrolled expansion state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Default disabled state inherited by the triggers in this root."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the requested open state and cancelable Base UI event details."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controlled expansion state. Use defaultOpen for uncontrolled state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsibleRootState>","required":false,"defaultValue":null,"description":"Replaces the root div. Forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: CollapsibleRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: CollapsibleTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables this trigger."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Set to false when render replaces the native button with another element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsibleTriggerState>","required":false,"defaultValue":null,"description":"Replaces the linked trigger button. Forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: CollapsibleTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Panel","props":[{"name":"className","type":"string | ((state: CollapsiblePanelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"containAnimation","type":"boolean","required":false,"defaultValue":"true","description":"Clips overflowing content during expansion and uses a column layout."},{"name":"dimension","type":"\"height\" | \"width\"","required":false,"defaultValue":"height","description":"Dimension animated when the panel opens and closes."},{"name":"duration","type":"\"fast\" | \"instant\" | \"normal\" | \"slow\"","required":false,"defaultValue":"normal","description":"Theme timing preset for both size and opacity. Native style can customize transition timing."},{"name":"hiddenUntilFound","type":"boolean","required":false,"defaultValue":"false","description":"Uses hidden until-found so browser page search can reveal the contents. Overrides keepMounted."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the closed panel mounted and hidden, preserving local content state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsiblePanelState>","required":false,"defaultValue":null,"description":"Replaces the animated panel div. Forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: CollapsiblePanelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Separator","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: Separator\ndescription: Separate adjacent content with a horizontal or vertical divider.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport SeparatorReference from '/snippets/ui/generated/layout/separator.mdx';\n\n## Overview\n\n`Separator` renders a `div` with `role=\"separator\"` and an accessible orientation. It uses the Base UI separator contract, including native props, refs, and `render` composition. Import `SeparatorProps` from the same entry point.\n\n<StoryEmbed\n storyId=\"ui-layout-separator--display\"\n title=\"Horizontal separator\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { Separator } from 'twenty-ui/primitives/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportSources = () => (\n <Text style={{ display: 'grid', gap: 'var(--t-spacing-3)' }}>\n <Text>Import records from a CSV file.</Text>\n <Separator />\n <Text>Connect an external data source.</Text>\n </Text>\n);\n```\n\n## Orientation and appearance\n\n`orientation` defaults to `horizontal`. Margins default to zero in both orientations. Horizontal separators fill the available width. Vertical separators stretch along their flex container. Give a standalone vertical separator a height. Control spacing through the parent layout, or use native `style` or `className` for explicit margins and line color. Base UI also accepts functions of the orientation for these props.\n\n<StoryEmbed\n storyId=\"ui-layout-separator--vertical-documentation\"\n title=\"Vertical separator\"\n height={150}\n/>\n\n## Labeled dividers\n\nUse [LabeledSeparator](/ui/components/layout/labeled-separator) for a text label between divider lines or at the end of a rule. It provides the layout and a single accessible separator name.\n\n```tsx\nimport { LabeledSeparator } from 'twenty-ui/components/layout';\n\nexport const SignInDivider = () => <LabeledSeparator>Or</LabeledSeparator>;\n```\n\n## Migration\n\nReplace the former horizontal helper with `Separator`. Remove `noMargin`, since margins now default to zero. To keep the former default spacing, add `style={{ marginBlock: 'var(--t-spacing-3)' }}`. Replace `color` with `style={{ backgroundColor: color }}`. Use `LabeledSeparator` for labeled dividers, pass the label as children, and rename `textPosition` to `labelPosition`. Replace separators used only for invisible spacing with layout spacing.\n\n## Props\n\n<SeparatorReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Separator","entryPoint":"twenty-ui/primitives/layout","slug":"layout/separator","props":[{"name":"className","type":"string | ((state: SeparatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class or function of the separator orientation."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"Direction of the divider: horizontal or vertical."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState>","required":false,"defaultValue":null,"description":"Element or render function composed with the native separator props and ref."},{"name":"style","type":"CSSProperties | ((state: SeparatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Native style or function of the separator orientation. Use it for spacing and line color."}]}},{"name":"ResizeHandle","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: ResizeHandle\ndescription: Resize a panel with pointer dragging or keyboard controls.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ResizeHandleReference from '/snippets/ui/generated/layout/resize-handle.mdx';\n\n## Overview\n\n`ResizeHandle` manages a numeric size and exposes a focusable separator. The application applies that size to the panel; the handle does not resize another element automatically.\n\n<StoryEmbed\n storyId=\"ui-layout-resizehandle--display\"\n title=\"ResizeHandle example\"\n height={600}\n/>\n\n## Usage\n\nUse `edge` for a panel boundary, or `axis=\"y\"` for inline height resizing and `axis=\"x\"` for inline width resizing. Give the handle a specific accessible name and use `aria-controls` to identify the panel.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { ResizeHandle } from 'twenty-ui/primitives/layout';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ResizableNotes = () => {\n const panelId = useId();\n const [height, setHeight] = useState(150);\n\n return (\n <Card.Root style={{ width: 300, maxWidth: '100%' }}>\n <Text\n id={panelId}\n style={{\n height,\n overflow: 'auto',\n padding: 16,\n boxSizing: 'border-box',\n }}\n >\n <Text\n style={{\n color: 'var(--t-font-color-primary)',\n fontWeight: 'var(--t-font-weight-medium)',\n }}\n >\n Record notes\n </Text>\n <Text style={{ marginTop: 8, lineHeight: 1.5 }}>\n Follow up with Morgan about the proposal. Share the revised timeline\n before Friday.\n </Text>\n </Text>\n <Text style={{ padding: 4 }}>\n <ResizeHandle\n axis=\"y\"\n defaultValue={150}\n onValueChange={setHeight}\n min={50}\n max={500}\n aria-label=\"Resize notes height\"\n aria-controls={panelId}\n />\n </Text>\n </Card.Root>\n );\n};\n```\n\nThe handle owns its value. `onValueChange` copies the latest size to the panel layout without controlling the handle. `defaultValue` only sets the initial size.\n\n## Controlled state\n\n```tsx\nimport { useId, useState } from 'react';\nimport { ResizeHandle } from 'twenty-ui/primitives/layout';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ResizableNotes = () => {\n const panelId = useId();\n const [height, setHeight] = useState(150);\n\n return (\n <Card.Root style={{ width: 300, maxWidth: '100%' }}>\n <Text\n id={panelId}\n style={{\n height,\n overflow: 'auto',\n padding: 16,\n boxSizing: 'border-box',\n }}\n >\n <Text\n style={{\n color: 'var(--t-font-color-primary)',\n fontWeight: 'var(--t-font-weight-medium)',\n }}\n >\n Record notes\n </Text>\n <Text style={{ marginTop: 8, lineHeight: 1.5 }}>\n Follow up with Morgan about the proposal. Share the revised timeline\n before Friday.\n </Text>\n </Text>\n <Text style={{ padding: 4 }}>\n <ResizeHandle\n axis=\"y\"\n value={height}\n onValueChange={setHeight}\n min={50}\n max={500}\n aria-label=\"Resize notes height\"\n aria-controls={panelId}\n />\n </Text>\n </Card.Root>\n );\n};\n```\n\nThe application owns the value and can update it from other controls. Reflect live changes in `value`; use `onValueCommitted` to save the final size. Keep `value` and `defaultValue` separate and retain the same ownership mode throughout the component's lifetime.\n\n## Panel edges and gaps\n\n`edge=\"left\"`, `\"right\"`, `\"top\"` or `\"bottom\"` determines both the axis and the physical increasing direction. Leftward movement grows a left edge, upward movement grows a top edge, and the opposite applies to right and bottom edges. This behavior stays the same in right-to-left content. Use either `edge` or `axis` and `direction`.\n\nWith `edge`, placement defaults to `\"edge\"`. Put the handle inside a panel with `position: 'relative'` to position it along that boundary. `placement=\"inline\"` keeps it in normal flow. Use `placement=\"gap\"` between sibling panels and set its width or height through `style` when the layout needs a gap. Gap handles have no visible grip by default.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { ResizeHandle } from 'twenty-ui/primitives/layout';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ResizableDetails = ({\n saveWidth,\n}: {\n saveWidth: (value: number) => void;\n}) => {\n const detailsId = useId();\n const [width, setWidth] = useState(380);\n\n return (\n <div style={{ display: 'flex', height: 200 }}>\n <Card.Root style={{ flex: 1 }}>\n <Text>Activity</Text>\n </Card.Root>\n <ResizeHandle\n edge=\"left\"\n placement=\"gap\"\n value={width}\n onValueChange={setWidth}\n onValueCommitted={saveWidth}\n min={280}\n max={800}\n style={{ width: 12 }}\n aria-label=\"Resize details\"\n aria-controls={detailsId}\n />\n <Card.Root id={detailsId} style={{ width }}>\n <Text>Details</Text>\n </Card.Root>\n </div>\n );\n};\n```\n\n<StoryEmbed\n storyId=\"ui-layout-resizehandle-panels--documentation\"\n title=\"ResizeHandle panel edge example\"\n height={250}\n/>\n\n<StoryEmbed\n storyId=\"ui-layout-resizehandle-panels--gap\"\n title=\"ResizeHandle panel gap example\"\n height={520}\n/>\n\nThe application owns the layout, saved size, collapse state and focus destination when collapsing removes the handle. Use `onActivate` for an optional collapse action.\n\n## Keyboard and bounds\n\nFor `axis=\"y\"`, Down increases the size and Up decreases it. For `axis=\"x\"`, Right increases and Left decreases in left-to-right content; the directions reverse under [DirectionProvider](/ui/primitives/layout/direction-provider) with `direction=\"rtl\"`.\n\nArrow keys use `step`, which defaults to `10`. Home moves to `min`, and End moves to `max`. Keys pressed with Alt, Control or Meta are ignored. Pointer dragging uses the pixel movement and is not snapped to `step`. Both interactions stay within the bounds. Pointer presses do not move focus; keyboard users reach the handle with Tab. `disabled` prevents resizing and removes the handle from the tab order.\n\nThe separator orientation describes the dividing edge: horizontal for height resizing and vertical for width resizing.\n\n## Physical directions and zoom\n\nSet `direction=\"normal\"` or `direction=\"reverse\"` when increasing size must follow a fixed physical direction, regardless of text direction. Normal increases with rightward or downward movement. Reverse increases with leftward or upward movement. Omit `direction` to retain the text-direction behavior described above.\n\n`scale` accepts a positive zoom factor or a function returning one. The handle samples it at pointer down and divides pointer movement by that value. Keyboard steps remain unchanged.\n\n## Gesture lifecycle\n\n`onValueChange` reports live values. `onValueCommitted` reports the final value after a successful pointer drag or an effective keyboard change. Home, End and arrow keys commit immediately when they change the size.\n\n`onResizeStart` receives the first bounded candidate after the pointer passes `dragThreshold`. The threshold defaults to `5` with `edge` and `0` otherwise, measured in physical pixels. `onResizeEnd` receives `{ cancelled, value }` for a started drag. Escape, pointer cancellation, lost pointer capture and unmounting cancel the gesture without committing; disabling the handle cancels it on its next pointer event. Cancellation calls `onValueChange` with the starting value, clamped to the current bounds. `onResizeEnd` receives that restored value.\n\nSupply `onActivate` to handle a click without dragging, Enter or Space. Crossing the threshold prevents the following pointer click from activating, even when the pointer returns to its starting position.\n\nNative handlers run before the handle's interaction. Calling `preventDefault()` in `onPointerDown` or `onKeyDown` skips that interaction. Preventing `onPointerMove` skips only that update and leaves the gesture active. Preventing `onPointerUp` cancels the drag, restores the starting bounded value and skips `onValueCommitted`. Pointer cancellation and lost capture still end the gesture.\n\n## Custom handle\n\n`ref`, native attributes, `className`, `style` and native event handlers target the separator root, a `div` by default. The ref does not target the resized panel or the visible grip.\n\n`children` replaces the visible grip, and `children={null}` hides it; it does not replace the separator behavior. `render` can replace the root element, and the ref then targets that replacement. Custom wrappers must [forward the supplied props and ref](/ui/primitives/overview#custom-components) so focus, pointer capture, keyboard handlers, and accessibility attributes reach the same element.\n\n## Props\n\n<ResizeHandleReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"ResizeHandle","entryPoint":"twenty-ui/primitives/layout","slug":"layout/resize-handle","props":[{"name":"axis","type":"\"x\" | \"y\"","required":false,"defaultValue":"y without edge","description":"Pointer movement axis without `edge`: `y` for height or `x` for width."},{"name":"defaultValue","type":"number | (readonly string[] & number)","required":false,"defaultValue":"150","description":"Initial size when the handle owns its state."},{"name":"direction","type":"\"normal\" | \"reverse\"","required":false,"defaultValue":null,"description":"Physical increasing direction. Omit to follow the horizontal text direction; use `normal` or `reverse` for a fixed physical edge."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables resizing and removes the handle from the tab order."},{"name":"dragThreshold","type":"number","required":false,"defaultValue":"5 with edge; 0 otherwise","description":"Physical pointer distance required before resizing starts. Movement below the threshold remains a click. Defaults to 5 with `edge` and 0 otherwise."},{"name":"edge","type":"\"bottom\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Physical panel edge. Determines the movement axis and increasing direction, independently of text direction."},{"name":"max","type":"number","required":false,"defaultValue":"500","description":"Maximum allowed size."},{"name":"min","type":"number","required":false,"defaultValue":"50","description":"Minimum allowed size."},{"name":"onActivate","type":"(() => void)","required":false,"defaultValue":null,"description":"Called for a click without dragging, Enter, or Space."},{"name":"onResizeEnd","type":"((details: { cancelled: boolean; value: number; }) => void)","required":false,"defaultValue":null,"description":"Called after a started drag ends, with its final value and whether it was cancelled. Cancellation restores the starting value within the current bounds."},{"name":"onResizeStart","type":"((value: number) => void)","required":false,"defaultValue":null,"description":"Called once with the first bounded drag value after the threshold is crossed."},{"name":"onValueChange","type":"((value: number) => void)","required":false,"defaultValue":null,"description":"Called with the bounded size during pointer or keyboard interaction and with the restored value on cancellation."},{"name":"onValueCommitted","type":"((value: number) => void)","required":false,"defaultValue":null,"description":"Called with the final size after a successful drag or an effective keyboard size change. Cancellation does not commit."},{"name":"placement","type":"\"edge\" | \"gap\" | \"inline\"","required":false,"defaultValue":"edge with edge; inline otherwise","description":"Layout mode: `inline` stays in normal flow, `edge` positions the handle on the panel edge, and `gap` sits between panels. Defaults to `edge` when `edge` is set and `inline` otherwise."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"scale","type":"number | (() => number)","required":false,"defaultValue":"1","description":"Pointer scale or resolver sampled at pointer down. Movement is divided by this positive scale; keyboard steps are unchanged."},{"name":"step","type":"number","required":false,"defaultValue":"10","description":"Keyboard arrow increment. Pointer movement uses the pixel delta."},{"name":"value","type":"number","required":false,"defaultValue":null,"description":"Current controlled size. Update it in `onValueChange` and apply it to the element being resized."}]}},{"name":"DirectionProvider","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: DirectionProvider\ndescription: Coordinate directional keyboard and pointer interactions with the document direction.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport DirectionProviderReference from '/snippets/ui/generated/layout/direction-provider.mdx';\n\n## Overview\n\n`DirectionProvider` supplies `ltr` or `rtl` direction to Twenty UI controls. It does not render a DOM element or set an HTML `dir` attribute. Set both the provider direction and the matching document direction.\n\n<StoryEmbed\n storyId=\"ui-layout-directionprovider--display\"\n title=\"DirectionProvider example\"\n height={160}\n/>\n\n## Usage\n\n```tsx\nimport { SegmentedControl } from 'twenty-ui/components/input';\nimport { DirectionProvider } from 'twenty-ui/primitives/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype DirectionalChoicesProps = { direction: 'ltr' | 'rtl' };\n\nexport const DirectionalChoices = ({ direction }: DirectionalChoicesProps) => (\n <DirectionProvider direction={direction}>\n <Text dir={direction}>\n <SegmentedControl\n aria-label=\"Billing period\"\n defaultValue=\"annual\"\n options={[\n { label: 'Annual', value: 'annual' },\n { label: 'Monthly', value: 'monthly' },\n ]}\n />\n </Text>\n </DirectionProvider>\n);\n```\n\nThe host application supplies translated labels and chooses the direction. Direction context affects directional interactions; the HTML attribute handles text and layout. For example, [SegmentedControl](/ui/components/input/segmented-control) reverses horizontal arrow navigation, and [ResizeHandle](/ui/primitives/layout/resize-handle) reverses horizontal resizing.\n\n## Scope and state\n\nPlace one provider around the controls that share a direction. Nested providers can override the direction for a subtree; pair each override with a matching `dir` attribute. `direction` is application-owned and defaults to `ltr`, matching Base UI. Children are optional. Import `DirectionProviderProps` from the same entry point. The provider has no DOM target, native props, or ref. The provider does not translate content or choose direction from the locale automatically.\n\n## Portals and layout\n\nDropdown, Popover, Tooltip, Select, Dialog, and Toast portals carry the provider direction even when their container is outside the element with `dir`. Without a provider they inherit the direction of their container. Keep the provider direction and the trigger's HTML direction consistent. A scoped `ThemeProvider` continues to own the default portal container.\n\nSubmenus open toward `inline-end`. ArrowRight opens a submenu in LTR; ArrowLeft opens it in RTL. The opposite key returns to the parent. Explicit `left` and `right` popup placement still mean physical sides. Collision handling can move a popup when space is limited.\n\nText, indentation, attached button corners, and directional disclosure icons follow reading direction. Supplied icons retain their orientation. `AvatarGroup.overlap` still names a physical edge; the outer avatar does not extend beyond that edge in either direction.\n\n<StoryEmbed\n storyId=\"ui-layout-directionprovider--reading-directions\"\n title=\"Left-to-right and right-to-left layouts\"\n height={1260}\n/>\n\n## Props\n\n<DirectionProviderReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"DirectionProvider","entryPoint":"twenty-ui/primitives/layout","slug":"layout/direction-provider","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Controls that receive the direction context."},{"name":"direction","type":"\"ltr\" | \"rtl\"","required":false,"defaultValue":"ltr","description":"Reading direction used by directional interactions. Also set the matching HTML `dir` attribute on the content."}]}},{"name":"OverflowingTextWithTooltip","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: OverflowingTextWithTooltip\ndescription: Truncate long text and reveal its full value in a tooltip.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport OverflowingTextWithTooltipReference from '/snippets/ui/generated/typography/overflowing-text-with-tooltip.mdx';\n\n## Overview\n\n`OverflowingTextWithTooltip` truncates content within the available width. It checks for overflow on pointer entry and focus, then shows a tooltip only when needed. It manages tooltip visibility internally and exposes no controlled or uncontrolled open-state props. Use [OverflowingTextTooltipModeProvider](/ui/primitives/typography/overflowing-text-tooltip-mode-provider) to change when a subtree checks truncation or to turn the tooltip off.\n\n<StoryEmbed\n storyId=\"ui-surfaces-overflowingtextwithtooltip--display\"\n title=\"OverflowingTextWithTooltip example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport {\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const RecordTitle = () => (\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text=\"Quarterly account review and renewal preparation\"\n isFocusable\n />\n </Text>\n);\n```\n\nConstrain the width of the surrounding layout so truncation can occur. `isFocusable` gives the text a tab stop and opens the tooltip on focus or click. Keep essential information available to users who cannot hover.\n\n## Choose typography\n\n`size`, `weight` and `color` match [Text](/ui/primitives/typography/text). They are optional and inherit independently when omitted. Explicit typography applies to the displayed text; the tooltip retains its shared appearance.\n\n```tsx\nimport { OverflowingTextWithTooltip } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceCaption = () => (\n <OverflowingTextWithTooltip\n text=\"Quarterly account review and renewal preparation\"\n size=\"xs\"\n weight=\"semibold\"\n color=\"light\"\n style={{ maxWidth: 220 }}\n />\n);\n```\n\n## Multiline content\n\n```tsx\nimport {\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const RecordDescription = () => (\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text=\"Review the account history, confirm the renewal date, and prepare the next conversation with the customer.\"\n lineClamp={2}\n isTooltipMultiline\n isFocusable\n />\n </Text>\n);\n```\n\n`lineClamp` matches Text and limits the displayed lines; use a positive integer. `isTooltipMultiline` preserves whitespace and line breaks inside the tooltip. Without a row limit, text truncates on one line.\n\n## Custom content and timing\n\n```tsx\nimport {\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const ImportResult = () => (\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text={<strong>24 records imported successfully</strong>}\n tooltipContent=\"24 records imported successfully\"\n tooltipPlace=\"top\"\n tooltipDelay={300}\n isFocusable\n />\n </Text>\n);\n```\n\nReact content requires a plain-string `tooltipContent`. With string text, that prop can override the tooltip label; otherwise the text itself is used. An empty or missing label does not open a tooltip. String URLs remain plain text. Supply links explicitly in `text` or through `render`. Link content and navigation stay caller-owned.\n\n`alwaysShowTooltip` allows the tooltip even without truncation. `tooltipDelay` controls the hover delay and defaults to 500 milliseconds. `tooltipPlace` defaults to `bottom`.\n\nNative attributes, styles, class names, event handlers, and refs target the displayed Text element, a `div` by default. `render` can replace that element while retaining truncation and tooltip behavior. `OverflowingTextWithTooltipProps` is exported from `twenty-ui/primitives/typography`. Typography inherits from the surrounding layout unless an explicit typography prop is supplied. Set `truncate={false}` to wrap; choose either `truncate` or `lineClamp`. Focusable rendered elements and a caller-supplied `tabIndex` also reveal the tooltip on focus. Use [Text](/ui/primitives/typography/text) and [Tooltip](/ui/primitives/surfaces/tooltip) directly when you need custom composition. Interactive popup content belongs in [Popover](/ui/primitives/surfaces/popover).\n\n## Explicit links\n\n```tsx\nimport { OverflowingTextWithTooltip } from 'twenty-ui/primitives/typography';\n\nexport const DocumentationLink = () => (\n <OverflowingTextWithTooltip\n text=\"https://twenty.com/developers\"\n render={\n <a href=\"https://twenty.com/developers\" aria-label=\"Documentation\" />\n }\n style={{ maxWidth: 160, display: 'block' }}\n />\n);\n```\n\nUse a single anchor for the whole label, or supply individual anchors in React content with a plain `tooltipContent`. The component adds no anchors of its own. Keep tooltip content informational.\n\n## Migration\n\nReplace `displayedMaxRows` with `lineClamp`. The former `size=\"small\"` and `size=\"large\"` options controlled height, not font size. `large` set a 16px height. The new `size` selects theme font sizes and accepts no legacy aliases; use native `style` or `className` for height constraints. `color` now accepts semantic colors; move arbitrary CSS colors to `style={{ color: customColor }}`. Move intentional URL recognition into caller-owned content. No automatic linkification remains in this component.\n\n## Props\n\n<OverflowingTextWithTooltipReference />\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"OverflowingTextWithTooltip","entryPoint":"twenty-ui/primitives/typography","slug":"typography/overflowing-text-with-tooltip","props":[{"name":"alwaysShowTooltip","type":"boolean","required":false,"defaultValue":null,"description":"Allows the tooltip even when the text is not truncated."},{"name":"color","type":"\"light\" | \"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":null,"description":"Semantic text color. Omitted values inherit; native style supports runtime colors."},{"name":"isFocusable","type":"boolean","required":false,"defaultValue":null,"description":"Adds an optional tab stop. Native tabIndex and focusable render elements also open the tooltip on focus."},{"name":"isTooltipMultiline","type":"boolean","required":false,"defaultValue":null,"description":"Preserves whitespace and line breaks in the tooltip."},{"name":"lineClamp","type":"number","required":false,"defaultValue":null,"description":"Positive integer limiting visible lines, matching Text. Cannot be combined with `truncate`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default div. Native props, styles, handlers and ref target the displayed text, not the popup."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\" | \"xxs\"","required":false,"defaultValue":null,"description":"Font size from the theme scale. Omitted values inherit; this does not set height."},{"name":"text","type":"string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined","required":true,"defaultValue":null,"description":"Caller-owned text or React content. Non-string content requires `tooltipContent`. URLs stay plain text."},{"name":"tooltipContent","type":"string","required":false,"defaultValue":null,"description":"Plain text displayed in the tooltip. Defaults to nonempty string `text`."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":null,"description":"Hover delay in milliseconds."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Preferred side of the tooltip."},{"name":"truncate","type":"boolean","required":false,"defaultValue":null,"description":"Single-line ellipsis by default. Set false to wrap. Cannot be combined with `lineClamp`."},{"name":"weight","type":"\"medium\" | \"regular\" | \"semibold\"","required":false,"defaultValue":null,"description":"Theme font weight. Omitted values inherit."}]}},{"name":"OverflowingTextTooltipModeProvider","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: OverflowingTextTooltipModeProvider\ndescription: Choose when OverflowingTextWithTooltip checks truncation for a subtree.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport OverflowingTextTooltipModeProviderReference from '/snippets/ui/generated/typography/overflowing-text-tooltip-mode-provider.mdx';\n\n## Overview\n\n`OverflowingTextTooltipModeProvider` sets how every [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip) inside it handles its tooltip. It renders no DOM element.\n\n<StoryEmbed\n storyId=\"ui-typography-overflowingtexttooltipmodeprovider--display\"\n title=\"Overflowing text tooltip mode provider example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport {\n OverflowingTextTooltipModeProvider,\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const RecordCell = () => (\n <OverflowingTextTooltipModeProvider mode=\"measure-on-hover\">\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text=\"Quarterly account review and renewal preparation\"\n isFocusable\n />\n </Text>\n </OverflowingTextTooltipModeProvider>\n);\n```\n\nHover or focus the truncated label to read its full value. Change `mode` in the Storybook controls to compare when the tooltip is available.\n\n## Modes\n\n- `measure-on-hover`, the default without a provider, checks truncation on pointer entry and focus. A label that fits stays out of the way of a parent tooltip.\n- `measure-on-open` checks truncation when the tooltip tries to open. Use it for labels that mount under the pointer, such as a hover overlay, where no pointer entry happens.\n- `disabled` renders only the text, without any tooltip parts. Use it for many labels that a user cannot hover, such as content covered by an overlay.\n\n<StoryEmbed\n storyId=\"ui-typography-overflowingtexttooltipmodeprovider--disabled\"\n title=\"Tooltip disabled for a subtree\"\n height={90}\n/>\n\nNested providers override the mode for their subtree.\n\n## Props\n\n<OverflowingTextTooltipModeProviderReference />\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"OverflowingTextTooltipModeProvider","entryPoint":"twenty-ui/primitives/typography","slug":"typography/overflowing-text-tooltip-mode-provider","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Content whose OverflowingTextWithTooltip instances use the mode."},{"name":"mode","type":"\"disabled\" | \"measure-on-hover\" | \"measure-on-open\"","required":true,"defaultValue":null,"description":"`measure-on-hover` checks truncation on pointer entry and focus. `measure-on-open` checks it when the tooltip tries to open. `disabled` renders only the text."}]}},{"name":"LightIconButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: LightIconButton\ndescription: Present lightweight icon actions with standard or subtle emphasis.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport LightIconButtonReference from '/snippets/ui/generated/components/input/light-icon-button.mdx';\n\n## Overview\n\n`LightIconButton` composes [IconButton](/ui/components/input/icon-button) with a ghost surface and a small size. Supply an accessible name and decorative icon content.\n\n<StoryEmbed\n storyId=\"ui-input-button-lighticonbutton--display\"\n title=\"Light icon button\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\n\nexport const SearchAction = () => (\n <LightIconButton aria-label=\"Search\">\n <IconSearch />\n </LightIconButton>\n);\n```\n\nStandard emphasis uses secondary neutral text; subtle emphasis uses tertiary text. Explicit child appearance takes precedence over ButtonGroup values, followed by the component defaults. Semantic colors retain their own contrast treatment. Small controls are 24px with a 14px icon; medium controls are 32px with a 16px icon. Compact controls use `size=\"xs\"` and are 20px.\n\n## Visual options\n\nCompare emphasis at small and medium sizes, including selected, loading, and disabled states.\n\n<StoryEmbed\n storyId=\"ui-input-button-lighticonbutton--catalog\"\n title=\"Light icon button emphasis, sizes, and states\"\n height={410}\n/>\n\n## State and interaction\n\nButton owns keyboard activation, disabled and loading behavior, refs, native attributes, and render composition. The native default is `type=\"button\"`. Use `aria-pressed` for toggles and `aria-expanded` for disclosures. The application owns these states and can set `color=\"accent\"` to highlight a selected action. Keyboard focus uses the shared focus ring.\n\nTooltip text is optional and does not replace an accessible name from `aria-label` or `aria-labelledby`. Set `href` for a link. For application-owned routing, supply `render`, `nativeButton={false}`, and `role=\"link\"`.\n\n## Updating existing controls\n\nImport `LightIconButton` from `twenty-ui/components`. Replace `Icon={IconPlus}` with `<IconPlus />` children, `small`/`medium` with `sm`/`md`, `accent=\"tertiary\"` with `emphasis=\"subtle\"`, and `testId` with `data-testid`. Replace synthetic `active` and `focus` flags with semantic state and actual keyboard focus.\n\nReplace `LightIconButtonGroup` with [ButtonGroup](/ui/primitives/input/button-group) using `attached={false}` and explicit children. Set `disabled` on unavailable actions, including actions without a click handler. Wrappers and tooltip triggers can remain around each child.\n\n## Row actions\n\nUse a passive [ListItem](/ui/primitives/navigation/list-item) with an `actions` slot for independent controls. Pass one `LightIconButton` directly, or use `ButtonGroup` for multiple buttons. Each button owns its accessible name, click handler, and disabled state. Wrap dropdown triggers directly around the button.\n\n```tsx\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { IconEyeOff, IconTrash } from 'twenty-ui/icon';\nimport { ButtonGroup } from 'twenty-ui/primitives/input';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const RecordActions = () => (\n <ListItem\n actions={\n <ButtonGroup attached={false}>\n <LightIconButton aria-label=\"Hide record\">\n <IconEyeOff />\n </LightIconButton>\n <LightIconButton aria-label=\"Delete record\" disabled>\n <IconTrash />\n </LightIconButton>\n </ButtonGroup>\n }\n >\n Record\n </ListItem>\n);\n```\n\nA button without an `onClick` handler can remain enabled when a surrounding dropdown owns its interaction. Set `disabled` explicitly for unavailable buttons. Keep independent controls beside an actionable [ListItemButton](/ui/components/navigation/list-item-button) so each retains its own focus and activation.\n\n## Props\n\n<LightIconButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"LightIconButton","entryPoint":"twenty-ui/components/input","slug":"components/input/light-icon-button","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name describing the action. Required unless `aria-labelledby` supplies the name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element supplying the accessible name. Can be used instead of `aria-label`."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Icon content. Decorative and hidden from assistive technology."},{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"emphasis","type":"\"standard\" | \"subtle\"","required":false,"defaultValue":"standard","description":"Standard secondary text or subtle tertiary text. Semantic colors and solid surfaces keep their own colors."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":null,"description":"Square or round icon control."},{"name":"size","type":"\"md\" | \"sm\" | \"xs\"","required":false,"defaultValue":"sm","description":"Button size: `xs` (20px), `sm` (24px), or `md` (32px)."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"tooltip","type":"string","required":false,"defaultValue":null,"description":"Text displayed when hovering or focusing the button."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":null,"description":"Delay before showing the tooltip."},{"name":"tooltipOffset","type":"number","required":false,"defaultValue":null,"description":"Distance in pixels between the button and the tooltip."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Preferred placement of the tooltip relative to the button."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"ghost","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"IconButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: IconButton\ndescription: Trigger actions with accessible icon buttons.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport IconButtonReference from '/snippets/ui/generated/components/input/icon-button.mdx';\n\n## Overview\n\n`IconButton` composes [Button](/ui/primitives/input/button) with a square or round surface. Pass the icon as children and provide an accessible name with `aria-label` or `aria-labelledby`. Icon content is decorative and hidden from assistive technology.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--display\"\n title=\"Icon button with an accessible name\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\n\nexport const SearchButton = () => (\n <IconButton aria-label=\"Search\">\n <IconSearch />\n </IconButton>\n);\n```\n\nSizes are `xs` (20px), `sm` (24px), and `md` (32px). The defaults are `md`, `outline`, and `neutral`. Variants and colors match Button. Use `shape=\"round\"` for a circular button; the default shape is `square`.\n\n## Visual options\n\nCompare one visual choice at a time. Use the named tooltip, elevated, and grouped examples for composition.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--catalog\"\n title=\"Icon button variants, colors, sizes, shapes, elevation, and states\"\n height={810}\n/>\n\n## Accessible names\n\nUse `aria-label` for a name supplied directly on the control. When visible text already names the action, use `aria-labelledby` to reference it instead. At least one naming prop is required.\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const LabelledSearchButton = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>\n <Text render={<span />} id=\"records-search-label\">\n Search records\n </Text>\n <IconButton aria-labelledby=\"records-search-label\" tooltip=\"Find a record\">\n <IconSearch />\n </IconButton>\n </Text>\n);\n```\n\n<StoryEmbed\n title=\"Icon button named by visible text\"\n storyId=\"ui-components-iconbutton--labelled-by\"\n height={140}\n/>\n\n## Tooltip\n\nAdd `tooltip` to show text on hover and keyboard focus. Keep `aria-label` or `aria-labelledby` as the accessible name of the action. Disabled and loading buttons retain hover tooltips.\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\n\nexport const SearchRecordsButton = () => (\n <IconButton aria-label=\"Search\" tooltip=\"Search records\">\n <IconSearch />\n </IconButton>\n);\n```\n\n<StoryEmbed\n title=\"Icon button with tooltip\"\n storyId=\"ui-components-iconbutton--tooltip-documentation\"\n height={140}\n/>\n\nThe tooltip defaults to the bottom, with a 1000ms delay and a 5px offset. Use `tooltipPlace`, `tooltipDelay`, and `tooltipOffset` to adjust it. Omitting `tooltip` renders the button directly.\n\n## State ownership\n\nYour application supplies `loading` and `disabled`. Both prevent activation. Loading preserves the square dimensions and accessible label. The button does not track a selected value or set loading automatically after a click. Native keyboard focus follows the browser; use `aria-pressed` when your application owns a toggle state.\n\n## Elevated actions\n\nUse `elevated` to add a shadow and backdrop blur. The default neutral outline button also gains a bordered surface with matching icon and interaction colors. Other variants and semantic colors keep their existing palette.\n\n`elevated` defaults to `false`. It does not change positioning, visibility, or size. The size remains `md` (32px) by default; set `size=\"sm\"` for a 24px control.\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconPlus } from 'twenty-ui/icon';\n\nexport const AddWidgetButton = () => (\n <IconButton elevated size=\"sm\" aria-label=\"Add widget\">\n <IconPlus />\n </IconButton>\n);\n```\n\n<StoryEmbed\n title=\"Elevated icon action\"\n storyId=\"ui-components-iconbutton--elevated\"\n height={100}\n/>\n\nOmit `elevated` or set it to `false` to restore the standard appearance. Elevated buttons support the same tooltips, loading states, links, and keyboard interactions.\n\n<StoryEmbed\n title=\"Elevated icon action with tooltip\"\n storyId=\"ui-components-iconbutton--elevated-tooltip\"\n height={140}\n/>\n\nReplace existing `FloatingIconButton` controls with `IconButton elevated`. Pass the icon as children, use native `aria-label`, and map `small` to `sm` and `medium` to `md`. Supply `size=\"sm\"` when the previous control used its default size. Native focus and `aria-pressed` replace synthetic focus and active flags.\n\n`FloatingIconButtonGroup` is removed. Compose ButtonGroup with IconButton for grouped actions, and keep any shared floating surface in your layout.\n\n## Grouped actions\n\n```tsx\nimport { ButtonGroup } from 'twenty-ui/primitives/input';\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconPlus, IconSearch } from 'twenty-ui/icon';\n\nexport const RecordActions = () => (\n <ButtonGroup\n aria-label=\"Record actions\"\n size=\"sm\"\n variant=\"solid\"\n color=\"accent\"\n >\n <IconButton\n aria-label=\"Search records\"\n tooltip=\"Search records\"\n variant=\"outline\"\n color=\"neutral\"\n >\n <IconSearch />\n </IconButton>\n <IconButton aria-label=\"Create record\" tooltip=\"Create record\">\n <IconPlus />\n </IconButton>\n </ButtonGroup>\n);\n```\n\n[ButtonGroup](/ui/primitives/input/button-group) supplies defaults for size, variant, and color, plus adjoining corners. Explicit child props take precedence independently, including `size=\"xs\"`. Individual buttons do not need a position prop.\n\nKeep attached buttons the same size so their edges align. Set the size on the group and let each button inherit it.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--grouped-overrides\"\n title=\"Individual icon button appearance in a group\"\n height={140}\n/>\n\n## Links and forms\n\nWithout a custom `render`, `href` renders an anchor unless `nativeButton` is explicitly true. For a custom navigation anchor or router link, set `nativeButton={false}` and `role=\"link\"`. The renderer can own its destination without an IconButton `href`. Keep `nativeButton` true for a custom native button, and use false for a non-native action element. Explicit nativeButton and role props are preserved. Disabled and loading links cannot activate. Routing stays in the application.\n\nNative button and anchor attributes, event handlers, event details, refs, and render composition pass through to Button. The ref receives the actual root element. Tooltip composition preserves that root and its accessible name. The default is `type=\"button\"`; set `type=\"submit\"` explicitly for form submission.\n\n## Compact and round controls\n\nUse `size=\"xs\"` for a 20px control and `shape=\"round\"` for circular corners. Existing `RoundedIconButton` controls become `IconButton` with `shape=\"round\"`, `variant=\"solid\"`, and `color=\"accent\"`. Map their old `small` size to `xs` and `medium` size to `sm`. Supply icon children and an accessible name.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--round-documentation\"\n title=\"Round icon buttons in compact and regular sizes\"\n height={140}\n/>\n\n## Props\n\n<IconButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"IconButton","entryPoint":"twenty-ui/components/input","slug":"components/input/icon-button","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name describing the action. Required unless `aria-labelledby` supplies the name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element supplying the accessible name. Can be used instead of `aria-label`."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Icon content. Decorative and hidden from assistive technology."},{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":"neutral","description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true (false for the built-in href anchor)","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Square or round icon control."},{"name":"size","type":"\"md\" | \"sm\" | \"xs\"","required":false,"defaultValue":"md","description":"Button size: `xs` (20px), `sm` (24px), or `md` (32px)."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"tooltip","type":"string","required":false,"defaultValue":null,"description":"Text displayed when hovering or focusing the button."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":"1000","description":"Delay before showing the tooltip."},{"name":"tooltipOffset","type":"number","required":false,"defaultValue":"5","description":"Distance in pixels between the button and the tooltip."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Preferred placement of the tooltip relative to the button."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"outline","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"MainButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: MainButton\ndescription: Present prominent actions with shared design defaults.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport MainButtonReference from '/snippets/ui/generated/components/input/main-button.mdx';\n\n## Overview\n\nUse the shared `MainButton` component for a prominent action. It composes\n[Button](/ui/primitives/input/button) with a solid surface, elevation, semibold\ntext, and 12px horizontal padding. Its default color is neutral and size is `md`.\n\n<StoryEmbed\n storyId=\"ui-components-mainbutton--display\"\n title=\"MainButton example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { MainButton } from 'twenty-ui/components/input';\n\nexport const SaveAction = () => <MainButton>Save changes</MainButton>;\n```\n\n## Visual options\n\nCompare solid and outline appearances across default and small sizes, plus disabled and loading states.\n\n<StoryEmbed\n storyId=\"ui-components-mainbutton--catalog\"\n title=\"Main button variants and states\"\n height={230}\n/>\n\n## State ownership\n\n`MainButton` uses Button's state model and adds no state of its own. Your application supplies `loading` and `disabled`; there are no controlled and uncontrolled selection modes. See [Button's state ownership example](/ui/primitives/input/button#state-ownership) for managing an asynchronous action.\n\n## Forms and width\n\n```tsx\nimport { MainButton } from 'twenty-ui/components/input';\n\nexport const SaveProfile = () => (\n <MainButton type=\"submit\" fullWidth>\n Save profile\n </MainButton>\n);\n```\n\nWidth follows the content unless you set `fullWidth` or provide application\nlayout styling. Override `variant`, `color`, `size`, and `elevated` as needed;\nfor example, use `variant=\"outline\"` and `elevated={false}` for an outlined action.\n\nWith `color=\"inherit\"`, choose a non-solid variant explicitly or inherit one from ButtonGroup. The standalone solid default with inherited color throws a runtime error.\n\nKeep page layout in your application's styling.\n\n## Interaction\n\n`MainButton` accepts Button's native attributes, event handlers, refs, icon slots,\n`loading` and `disabled` props. Buttons default to `type=\"button\"`;\nset `type=\"submit\"` explicitly for form submission.\n\nUse `href` for a link. Supply `render` to choose a custom root, including an\napplication-owned router link. Set `nativeButton={false}` and `role=\"link\"` for\na navigation renderer. Custom native buttons keep `nativeButton` true.\n\n[ButtonGroup](/ui/primitives/input/button-group) can set a shared size, surface,\nand color. Explicit child appearance takes precedence over the group, followed by\nthe component defaults. Consumer classes, including state functions, pass through\nto the root.\n\n## Props\n\n<MainButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"MainButton","entryPoint":"twenty-ui/components/input","slug":"components/input/main-button","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":"true","description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Button height: `sm` (24px) or `md` (32px). The `link` variant uses its content height at either size."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"LightButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: LightButton\ndescription: Present lightweight actions with standard or subtle emphasis.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport LightButtonReference from '/snippets/ui/generated/components/input/light-button.mdx';\n\n## Overview\n\nUse the shared `LightButton` component for a lightweight action. It composes\n[Button](/ui/primitives/input/button) with a ghost surface, small size, regular\nfont weight, and no elevation.\n\n<StoryEmbed\n storyId=\"ui-components-lightbutton--display\"\n title=\"LightButton example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { LightButton } from 'twenty-ui/components/input';\n\nexport const FilterAction = () => <LightButton>Add filter</LightButton>;\n```\n\n## Visual options\n\nCompare standard and subtle emphasis across common action states.\n\n<StoryEmbed\n storyId=\"ui-components-lightbutton--catalog\"\n title=\"Light button emphasis and states\"\n height={230}\n/>\n\n## State ownership\n\n`LightButton` uses Button's state model and adds no state of its own. Your application supplies `loading` and `disabled`; `emphasis` only changes appearance. See [Button's state ownership example](/ui/primitives/input/button#state-ownership) for managing an asynchronous action. There are no controlled and uncontrolled selection modes.\n\n## Emphasis and icons\n\n```tsx\nimport { LightButton } from 'twenty-ui/components/input';\nimport { IconPlus } from 'twenty-ui/icon';\n\nexport const FilterActions = () => (\n <LightButton emphasis=\"subtle\" startIcon={<IconPlus />}>\n Add filter\n </LightButton>\n);\n```\n\nThe default `emphasis=\"standard\"` uses secondary neutral text.\n`emphasis=\"subtle\"` uses tertiary neutral text on ghost, outline, and soft\nsurfaces. Semantic colors and solid surfaces retain their contrast treatment.\n\nOverride `variant`, `color`, `size`, or `elevated` when needed.\n[ButtonGroup](/ui/primitives/input/button-group) can set a shared size, surface,\nand color. Explicit child appearance takes precedence over the group, followed by\nthe component defaults. Subtle emphasis does not replace the semantic color.\n\n## Interaction\n\n`LightButton` accepts Button's native attributes, refs, event handlers, icon\nslots, loading and disabled states, and render composition. Its native default\nis `type=\"button\"`. Set `type=\"submit\"` for submission or use `href` for a link.\nSupply `render` to choose a custom root, including an application-owned router\nlink. Set `nativeButton={false}` and `role=\"link\"` for a navigation renderer.\nCustom native buttons keep `nativeButton` true.\n\n## Props\n\n<LightButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"LightButton","entryPoint":"twenty-ui/components/input","slug":"components/input/light-button","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"emphasis","type":"\"standard\" | \"subtle\"","required":false,"defaultValue":"standard","description":"Uses secondary or tertiary text for neutral buttons. Semantic colors and solid surfaces retain their contrast treatment."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Button height: `sm` (24px) or `md` (32px). The `link` variant uses its content height at either size."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"ghost","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"EmojiPicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: EmojiPicker\ndescription: Search and select an emoji using caller-hosted Emojibase data.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport EmojiPickerReference from '/snippets/ui/generated/components/input/emoji-picker.mdx';\n\n## Overview\n\n`EmojiPicker` provides emoji search, category browsing, and keyboard selection. Your application supplies its labels, emoji data location, and selection handler.\n\n<StoryEmbed\n storyId=\"ui-input-emojipicker--display\"\n title=\"Search emojis and choose a reaction\"\n height={400}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { EmojiPicker } from 'twenty-ui/components/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { themeCssVariables } from 'twenty-ui/theme';\nimport { isDefined } from 'twenty-ui/utilities';\n\nexport const EmojiPickerExample = () => {\n const [emoji, setEmoji] = useState<string | undefined>();\n\n return (\n <Text\n style={{\n display: 'flex',\n flexDirection: 'column',\n gap: themeCssVariables.spacing[2],\n width: 296,\n }}\n >\n <EmojiPicker\n emojibaseUrl=\"/emojibase\"\n searchLabel=\"Search emojis\"\n loadingLabel=\"Loading emojis\"\n emptyLabel=\"No emoji found\"\n onEmojiSelect={setEmoji}\n />\n <Text role=\"status\">\n {isDefined(emoji) ? `Selected emoji: ${emoji}` : 'Choose an emoji'}\n </Text>\n </Text>\n );\n};\n```\n\nThe preview uses a small fixture catalogue. The usage example expects your application to serve Emojibase data at `/emojibase`.\n\n## Data and labels\n\n`emojibaseUrl` is required. The picker loads both `${emojibaseUrl}/${locale}/data.json` and `${emojibaseUrl}/${locale}/messages.json`. Host those files from the Emojibase data package for each supported locale. The default locale is `en`; supplying translated interface labels does not change the emoji catalogue locale.\n\nProvide localized `searchLabel`, `loadingLabel`, and `emptyLabel`. `searchLabel` names the search field and supplies its placeholder unless `searchPlaceholder` overrides it. Emoji names, categories, and search tags come from the selected Emojibase locale.\n\n## Selection and composition\n\n`onEmojiSelect` receives the selected Unicode emoji string. The picker keeps its search and active emoji internally. Your application owns any selected value, reaction counts, message identifiers, permissions, persistence, and popup visibility. Compose it inside [Dropdown](/ui/components/navigation/dropdown) when it needs a popup.\n\nThe picker uses eight columns and a 280px height. Set its container width to fit the grid. Native div attributes, handlers, styles, class names, and refs target its outer container.\n\n## Accessibility\n\nThe search input has the supplied accessible name. Focus it with Tab, or set `autoFocus` when opening a popup. Arrow keys navigate the emoji grid, and Enter selects the active emoji. Each emoji has an accessible name from the selected catalogue. `autoFocus` defaults to `false`.\n\n## Props\n\n<EmojiPickerReference />\n\n<PageBanner illustration=\"page-cover-emoji\" />\n","api":{"name":"EmojiPicker","entryPoint":"twenty-ui/components/input","slug":"components/input/emoji-picker","props":[{"name":"autoFocus","type":"boolean","required":false,"defaultValue":"false","description":"Focuses the search input when the picker mounts."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional class name applied to the picker root div."},{"name":"emojibaseUrl","type":"string","required":true,"defaultValue":null,"description":"Base URL for caller-hosted Emojibase data. The picker loads data.json and messages.json from the selected locale directory."},{"name":"emptyLabel","type":"string","required":true,"defaultValue":null,"description":"Caller-supplied message displayed when no emoji matches the search."},{"name":"loadingLabel","type":"string","required":true,"defaultValue":null,"description":"Caller-supplied message displayed while emoji data loads."},{"name":"locale","type":"string","required":false,"defaultValue":"en","description":"Emoji catalogue locale. The caller must host its data and message files. Interface labels are supplied separately."},{"name":"onEmojiSelect","type":"(emoji: string) => void","required":true,"defaultValue":null,"description":"Called with the selected Unicode emoji string. The application owns the selected value, persistence, and popup visibility."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref for the picker root div."},{"name":"searchLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name for the search input. Also supplies its placeholder unless searchPlaceholder is set."},{"name":"searchPlaceholder","type":"string","required":false,"defaultValue":"searchLabel","description":"Optional placeholder overriding the search label."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native inline styles applied to the picker root div."}]}},{"name":"ReactionButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: ReactionButton\ndescription: Toggle an emoji reaction with a count and controlled pressed state.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ReactionButtonReference from '/snippets/ui/generated/components/input/reaction-button.mdx';\n\n## Overview\n\n`ReactionButton` composes [Button](/ui/primitives/input/button) into a compact emoji reaction with a count. Your application supplies the pressed state, accessible name, and change handler.\n\n<StoryEmbed\n storyId=\"ui-components-reactionbutton--display\"\n title=\"Controlled helpful reaction with a tooltip and reset action\"\n height={160}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport {\n ReactionButton,\n type ReactionButtonProps,\n} from 'twenty-ui/components/input';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const ReactionButtonExample = ({\n emoji = '👍',\n disabled,\n loading,\n}: Partial<Pick<ReactionButtonProps, 'emoji' | 'disabled' | 'loading'>>) => {\n const [pressed, setPressed] = useState(false);\n const count = pressed ? 3 : 2;\n\n return (\n <Text\n style={{\n display: 'flex',\n flexDirection: 'column',\n gap: themeCssVariables.spacing[2],\n }}\n >\n <Text>Was this helpful?</Text>\n <Text\n render={<span />}\n style={{\n display: 'flex',\n alignItems: 'center',\n gap: themeCssVariables.spacing[1],\n }}\n >\n <Tooltip content={`${count} people found this helpful`}>\n <ReactionButton\n aria-label=\"Helpful\"\n emoji={emoji}\n count={count}\n pressed={pressed}\n onPressedChange={setPressed}\n disabled={disabled}\n loading={loading}\n />\n </Tooltip>\n <Button size=\"sm\" variant=\"ghost\" onClick={() => setPressed(false)}>\n Reset\n </Button>\n </Text>\n </Text>\n );\n};\n```\n\n## Appearance\n\nThe control is 24px tall, with rounded corners, a 16px emoji, and a small count. Pressed reactions use the theme's accent surface and text. Unpressed reactions use a transparent surface and secondary text.\n\n`count` accepts a number or a caller-formatted string. Your application owns number formatting, abbreviation, and whether to display a reaction with a zero count.\n\n<StoryEmbed\n storyId=\"ui-components-reactionbutton--catalog\"\n title=\"Reaction selection, counts, and unavailable states\"\n height={300}\n/>\n\n## State ownership\n\n`pressed` is required and controlled by your application. Activation calls `onPressedChange` with the requested next value. The component keeps showing the supplied `pressed` and `count` until your application updates them.\n\nSet `loading` while a mutation is pending to show Button's loading indicator and prevent repeated activation. It preserves the supplied `pressed` value and marks the control busy. Use `disabled` when the reaction is unavailable. Selection, counts, permissions, persistence, and any optimistic updates stay in the application.\n\nNative `onClick` runs before the change request. Calling `event.preventDefault()` in that handler cancels the request. Other native button attributes, handlers, styles, class names, and refs pass through to the button. The control always uses `type=\"button\"`.\n\n## Accessibility and tooltips\n\nProvide `aria-label` or `aria-labelledby` with a localized reaction name. Emoji and count are decorative and hidden from assistive technology, so include count or participant information in the supplied name or description when needed. Keep the reaction name stable as its state changes; `aria-pressed` communicates selection.\n\nThe native button supports Tab focus and activation with Enter or Space. Both `disabled` and `loading` prevent activation. The ref points to the native button.\n\nCompose [Tooltip](/ui/primitives/surfaces/tooltip) for participant details on hover and keyboard focus, as shown above, or pass a native `title`. Tooltip content belongs to the caller and does not replace the accessible name. Long accessible labels do not enlarge the visible control.\n\n## Props\n\n<ReactionButtonReference />\n\n<PageBanner illustration=\"page-cover-emoji\" />\n","api":{"name":"ReactionButton","entryPoint":"twenty-ui/components/input","slug":"components/input/reaction-button","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name describing the reaction. Required unless `aria-labelledby` supplies the name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element supplying the accessible name. Can be used instead of `aria-label`."},{"name":"count","type":"string | number","required":true,"defaultValue":null,"description":"Displayed count. Pass a string for localized or abbreviated formatting. Hidden from assistive technology."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the native button and prevents activation."},{"name":"emoji","type":"string","required":true,"defaultValue":null,"description":"Emoji displayed beside the count. Hidden from assistive technology."},{"name":"loading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a loading indicator, sets `aria-busy`, and prevents activation without changing the supplied pressed state."},{"name":"onClick","type":"MouseEventHandler<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Native click handler called before `onPressedChange`. Calling `preventDefault()` cancels the change request."},{"name":"onPressedChange","type":"(pressed: boolean) => void","required":true,"defaultValue":null,"description":"Requests the next pressed state after activation. The caller updates `pressed` and `count`."},{"name":"pressed","type":"boolean","required":true,"defaultValue":null,"description":"Controlled selection state. Sets the selected appearance and `aria-pressed`."},{"name":"title","type":"string","required":false,"defaultValue":null,"description":"Optional native tooltip text supplied by the caller."}]}},{"name":"Button","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Button\ndescription: Trigger actions or navigate with styled buttons.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ButtonReference from '/snippets/ui/generated/input/button.mdx';\n\n## Overview\n\nUse `Button` for an action and supply its visible label as children. Use [IconButton](/ui/components/input/icon-button) for icon-only controls, with an accessible name from `aria-label` or `aria-labelledby`.\n\nFor recurring design defaults, use [MainButton](/ui/components/input/main-button)\nor [LightButton](/ui/components/input/light-button) from `twenty-ui/components`.\nBoth share Button's native props, refs, state, and rendering behavior.\n\n<StoryEmbed\n title=\"Button display\"\n storyId=\"ui-input-button-button--display\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveChanges = () => <Button>Save changes</Button>;\n```\n\n## Appearance\n\nCompare variants, semantic colors, sizes, and common states separately. Each group changes one choice while keeping the others fixed.\n\n<StoryEmbed\n storyId=\"ui-input-button-button--catalog\"\n title=\"Appearance for button\"\n height={630}\n/>\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { IconPlus } from 'twenty-ui/icon';\n\nexport const CreateRecord = () => (\n <Button variant=\"solid\" color=\"accent\" size=\"sm\" startIcon={<IconPlus />}>\n Create record\n </Button>\n);\n```\n\nChoose `solid`, `outline`, `soft`, `ghost`, or `link` independently of the `neutral`, `accent`, `danger`, or `success` color. Sizes are `sm` and `md`; the defaults are `outline`, `neutral`, and `md`. `fullWidth` fills the available width. `startIcon` and `endIcon` accept elements and are decorative. `elevated` adds a shadow and backdrop blur. Neutral outline buttons also gain a bordered surface with matching text and interaction colors. Other variants and semantic colors keep their existing palette. It defaults to `false` and does not change size or position. `shortcut` displays keyboard hints on larger screens; bind the shortcuts in your application.\n\nUse `color=\"inherit\"` for controls on a colored surface. The label, icons, loader, and outline border follow the surrounding text color. Interaction fills use translucent black. Outline buttons rest on a transparent surface with a 25% currentColor border and use 10% and 20% black fills on hover and press. Ghost uses transparent, 10%, and 20% black fills; soft uses 10%, 20%, and 30%. Link stays unfilled.\n\n`inherit` supports `outline`, `ghost`, `soft`, and `link`. A resolved `solid` and `inherit` combination throws a runtime error, including defaults supplied by ButtonGroup or a wrapper. `MainButton` defaults to solid, so supply a non-solid variant when inheriting color.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SurfaceActions = () => (\n <>\n <Button color=\"inherit\" variant=\"outline\">\n Save\n </Button>\n <Button color=\"inherit\" variant=\"ghost\">\n Cancel\n </Button>\n </>\n);\n```\n\n`link` uses compact text with no border or filled background. It follows its content height at either size, with a smaller font and narrower padding. Its neutral color uses stronger text on hover. The appearance does not determine semantics: use `onClick` for actions and `href` for navigation.\n\n`disabled` and `loading` prevent activation. Loading keeps the label accessible and communicates a busy state. By default, `loadingPosition=\"center\"` hides the content while preserving its layout space and centers the spinner. Set `loadingPosition` to `start` or `end` to keep children and the opposite icon visible while replacing the corresponding icon with the spinner.\n\nYour application owns progress formatting and the translated label. Pass the complete status phrase as children, for example `Installing (42%)`.\n\n<StoryEmbed\n title=\"Button loading at end\"\n storyId=\"ui-input-button-button--loading-at-end\"\n height={100}\n/>\n\n## State ownership\n\n`Button` triggers an action and does not manage a selected value, so it has no controlled or uncontrolled selection mode. Its native `value` prop supplies form data, not selection state.\n\nYour application owns `loading` and `disabled`, which default to `false`. Clicking a button does not change these props or automatically show loading while an asynchronous handler runs. Pass the current application state explicitly.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveRecordProps = { onSave: () => Promise<void> };\n\nexport const SaveRecord = ({ onSave }: SaveRecordProps) => {\n const [loading, setLoading] = useState(false);\n const [hasError, setHasError] = useState(false);\n\n const handleSave = async () => {\n setLoading(true);\n setHasError(false);\n\n try {\n await onSave();\n } catch {\n setHasError(true);\n } finally {\n setLoading(false);\n }\n };\n\n return (\n <>\n <Button loading={loading} onClick={handleSave}>\n Save record\n </Button>\n {hasError && <p role=\"alert\">Unable to save the record. Try again.</p>}\n </>\n );\n};\n```\n\nThe application starts and clears loading around the save operation. The button prevents activation while loading and becomes available again when the operation finishes, including after an error. `MainButton` and `LightButton` use the same state model.\n\n## Popup triggers\n\nCompose a popup trigger with `Button`, `LightButton`, or another Button wrapper through `render`. The trigger supplies `data-popup-open`, so the button keeps its hover background while the popup is open and uses its active background on hover or press. Each variant and color keeps its own palette. Link backgrounds remain transparent, and disabled or loading buttons keep their disabled appearance. Buttons with `aria-pressed=\"true\"` retain their existing toggle styling. Popup state does not set `aria-pressed` or represent a selected value.\n\n```tsx\nimport { LightButton } from 'twenty-ui/components/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const DetailsPopup = () => (\n <Popover.Root>\n <Popover.Trigger render={<LightButton>Show details</LightButton>} />\n <Popover.Portal>\n <Popover.Positioner>\n <Popover.Popup>\n <Popover.Title>Details</Popover.Title>\n <Popover.Description>\n More information about this record.\n </Popover.Description>\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n);\n```\n\n## Upcoming features\n\nYour application owns feature availability and its label. Compose a disabled button with `Badge` as children so the label remains part of the button's accessible name. Supply localized text from your application.\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const UpcomingAction = () => (\n <Button disabled>\n <Text\n render={<span />}\n style={{\n display: 'inline-flex',\n alignItems: 'center',\n gap: 'var(--t-spacing-1)',\n }}\n >\n Upcoming action\n <Badge>Coming soon</Badge>\n </Text>\n </Button>\n);\n```\n\nThis composition also works with `MainButton` and `LightButton`. It replaces the removed `soon` and `soonLabel` props.\n\n## Animated icons\n\nCompose `Button` with `AnimatedIconCrossfade` to change its icon when application state changes. Pass the animated element to `startIcon` and the label as children.\n\n```tsx\nimport { useState } from 'react';\nimport { IconPencil, IconX } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AnimatedIconCrossfade } from 'twenty-ui/components/layout';\n\nexport const EditActions = () => {\n const [isEditing, setIsEditing] = useState(false);\n\n return (\n <Button\n size=\"sm\"\n aria-expanded={isEditing}\n onClick={() => setIsEditing(!isEditing)}\n startIcon={\n <AnimatedIconCrossfade\n isActive={isEditing}\n activeIcon={<IconX size={14} />}\n inactiveIcon={<IconPencil size={14} />}\n />\n }\n >\n Edit actions\n </Button>\n );\n};\n```\n\nWhen an icon is itself an action, use `IconButton` or `LightIconButton` and animate its icon content. When a disclosure header owns expansion, keep its chevron decorative and expose `aria-expanded` on the header control. Keep animation styles with the feature and respect `prefers-reduced-motion`.\n\n<StoryEmbed\n title=\"Button with an animated icon\"\n storyId=\"ui-components-layout-animatediconcrossfade--display\"\n height={100}\n/>\n\n## Links and forms\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DocumentationLink = () => (\n <Button\n variant=\"link\"\n href=\"https://twenty.com\"\n target=\"_blank\"\n rel=\"noreferrer\"\n hrefLang=\"en\"\n referrerPolicy=\"no-referrer\"\n >\n Read documentation\n </Button>\n);\n```\n\nWithout a custom `render`, `href` renders an anchor with link semantics, unless you explicitly set `nativeButton` to `true`. Native anchor attributes such as `download`, `hrefLang`, `ping`, and `referrerPolicy` reach the anchor. Props shared with native buttons retain their Base UI types. To supply an anchor MIME type, put it on the renderer, for example `render={<a href=\"/records.csv\" type=\"text/csv\">Download records</a>}` with `nativeButton={false}` and `role=\"link\"`. Disabled and loading links cannot activate.\n\nUse `render` to compose another element or a router link. `nativeButton` describes the rendered element and defaults to `true` for custom renderers. Set `nativeButton={false}` and `role=\"link\"` for a navigation anchor. The anchor or router component can own its destination without a `Button` `href`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const RecordsLink = () => (\n <Button nativeButton={false} role=\"link\" render={<a href=\"/records\" />}>\n Open records\n </Button>\n);\n```\n\nFor a custom native `<button>`, keep `nativeButton` true. For a non-native action element such as a `<div>`, use `nativeButton={false}`; Base UI supplies button keyboard behavior. An explicit `nativeButton` or `role` is preserved even when `href` is also supplied.\n\nButtons default to `type=\"button\"`. Set `type=\"submit\"` or `type=\"reset\"` explicitly for forms. Native attributes, event handlers, event details, and refs reach the rendered root. A ref receives the actual button, anchor, or custom root element. Keyboard handlers retain Base UI event methods, including `preventBaseUIHandler()` to cancel its built-in keyboard action. Base UI's render callback receives both root props and the current disabled state; spread the props onto your root to retain composition behavior.\n\n## Group defaults\n\n[ButtonGroup](/ui/primitives/input/button-group) supplies a shared variant, color, and size. An explicit prop on a child takes precedence over the group default. When neither sets a prop, the component default applies.\n\n## Migration from ClickToActionLink\n\nImport `Button` from `twenty-ui/primitives/input` and replace `ClickToActionLink` with `Button variant=\"link\"`. Keep `href`, `target`, and `rel` for navigation. Actions without `href` now render a native button with keyboard activation. Native attributes, events, and refs pass through to the root.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype LogOutProps = { onLogOut: () => void };\n\nexport const LogOut = ({ onLogOut }: LogOutProps) => (\n <Button variant=\"link\" onClick={onLogOut}>\n Log out\n </Button>\n);\n```\n\n## Props\n\n<ButtonReference />\n\nPass `shortcut={['Mod', 'Enter']}` for simultaneous keys or `shortcut={[['G'], ['P']]}` for successive presses. See [Shortcut](/ui/primitives/typography/shortcut) for nested combinations and the shared string formatter.\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"Button","entryPoint":"twenty-ui/primitives/input","slug":"input/button","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":"neutral","description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":"false","description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true (false for the built-in href anchor)","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Button height: `sm` (24px) or `md` (32px). The `link` variant uses its content height at either size."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"outline","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"ButtonGroup","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: ButtonGroup\ndescription: Group related buttons with shared appearance and an optional frame.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ButtonGroupReference from '/snippets/ui/generated/input/button-group.mdx';\n\n## Overview\n\nGive a group an accessible name and place related buttons inside it. The group joins adjacent borders and can apply defaults for size, variant, and color. Buttons retain their own tab stops.\n\n<StoryEmbed\n storyId=\"ui-input-button-buttongroup--display\"\n title=\"Button group\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { IconCheckbox, IconNotes, IconTimelineEvent } from 'twenty-ui/icon';\nimport { Button, ButtonGroup } from 'twenty-ui/primitives/input';\n\nexport const ActivityActions = () => (\n <ButtonGroup aria-label=\"Create activity\" size=\"sm\">\n <Button startIcon={<IconNotes />}>Note</Button>\n <Button startIcon={<IconCheckbox />}>Task</Button>\n <Button startIcon={<IconTimelineEvent />}>Activity</Button>\n </ButtonGroup>\n);\n```\n\n## State ownership\n\n`ButtonGroup` coordinates appearance, not selection. It has no controlled or uncontrolled selection mode. Each button receives its own action handler and application state; see [Button's state ownership example](/ui/primitives/input/button#state-ownership) for loading behavior.\n\nFor a mutually exclusive choice, use [RadioGroup](/ui/primitives/input/radio-group), which owns selection for its radio controls.\n\n## Appearance precedence\n\nEach appearance prop resolves independently: the child's explicit prop, then the group default, then the component default. This applies to both Button and IconButton, including an explicit `IconButton size=\"xs\"`. Defaults reach children through fragments, wrappers, and tooltip anchors.\n\nA group can supply `color=\"inherit\"` on a colored surface. A child that resolves to inherited color must also resolve to a non-solid variant. Explicit child color and variant overrides take precedence, so a child may choose a non-solid variant or a semantic color when the group supplies solid and inherit together.\n\nKeep attached buttons at the same size so their edges align. This example overrides variant and color while inheriting the group size.\n\n```tsx\nimport { Button, ButtonGroup } from 'twenty-ui/primitives/input';\n\nexport const ActivityActions = () => (\n <ButtonGroup\n aria-label=\"Activity actions\"\n variant=\"solid\"\n color=\"accent\"\n size=\"sm\"\n >\n <Button variant=\"ghost\" color=\"danger\">\n Delete activity\n </Button>\n <Button color=\"neutral\">Duplicate activity</Button>\n <Button>New activity</Button>\n </ButtonGroup>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-input-button-buttongroup--appearance-overrides\"\n title=\"Individual appearance in a button group\"\n height={100}\n/>\n\n## Detached controls\n\nSet `attached={false}` to keep each control's rounded corners and a 2px gap. Group defaults still apply through wrappers and tooltip anchors; explicit child props take precedence.\n\n## Framed controls\n\nSet `framed` to add a translucent background, border, 2px padding, and concentric corners. The frame works with attached or detached controls and preserves explicit child appearance. Use `size=\"xs\"` on [IconButton](/ui/components/input/icon-button) for compact 20px actions.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--framed-group-documentation\"\n title=\"Framed button group\"\n height={100}\n/>\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconPlus, IconTrash } from 'twenty-ui/icon';\nimport { ButtonGroup } from 'twenty-ui/primitives/input';\n\nexport const CompactRecordActions = () => (\n <ButtonGroup framed attached={false} aria-label=\"Record actions\">\n <IconButton size=\"xs\" aria-label=\"Add\" variant=\"ghost\">\n <IconPlus />\n </IconButton>\n <IconButton size=\"xs\" aria-label=\"Delete\" variant=\"ghost\" disabled>\n <IconTrash />\n </IconButton>\n </ButtonGroup>\n);\n```\n\n## Updating existing groups\n\nReplace `IconButtonGroup` and its `iconButtons` array with `ButtonGroup framed attached={false}` and explicit children. Replace `InsideButton` with `LightIconButton size=\"xs\"`. Each button owns its accessible name, action handler, disabled state, and optional tooltip.\n\n## Props\n\n<ButtonGroupReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"ButtonGroup","entryPoint":"twenty-ui/primitives/input","slug":"input/button-group","props":[{"name":"attached","type":"boolean","required":false,"defaultValue":"true","description":"Join adjacent controls. Set to false for independently rounded buttons with a 2px gap."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Default semantic color for children without an explicit color. Inherited color requires each child to resolve to a non-solid variant; explicit child overrides take precedence."},{"name":"framed","type":"boolean","required":false,"defaultValue":"false","description":"Add a translucent frame with padding and concentric corners. Button sizes and appearance remain independent unless set on the group."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Default button height for children without an explicit size."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":null,"description":"Default surface treatment for children without an explicit variant."}]}},{"name":"Field","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Field\ndescription: Connect a form control to its label, description, and validation feedback.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport FieldReference from '/snippets/ui/generated/input/field.mdx';\n\n## Overview\n\nUse `Field` to group one control with its accessible label and helper text. Components such as [Input](/ui/primitives/input/input) integrate with the field directly.\n\n<StoryEmbed\n storyId=\"ui-input-field--display\"\n title=\"Field example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => (\n <Field.Root name=\"email\" validationMode=\"onBlur\">\n <Field.Label>Work email</Field.Label>\n <Input type=\"email\" required placeholder=\"[email protected]\" />\n <Field.Description>\n We send account updates to this address.\n </Field.Description>\n <Field.Error match=\"valueMissing\">Enter your email address.</Field.Error>\n <Field.Error match=\"typeMismatch\">Enter a valid email address.</Field.Error>\n </Field.Root>\n);\n```\n\n`Field.Root` manages the control's name, disabled state, and validity. `Field.Label` and `Field.Description` connect their content to the control. Set validation timing with `validationMode`; use `validate` for custom validation.\n\n## Anatomy\n\nPlace one control and its supporting parts inside `Field.Root`. This tree shows a field built with the styled `Input` component.\n\n```text\nField.Root\n├── Field.Label\n├── Input\n├── Field.Description\n└── Field.Error\n```\n\n| Part | Requirement | Purpose |\n| ------------------------------------- | ------------------- | ---------------------------------------------------------------------------- |\n| `Root` | Required | Shares the name, disabled state, and validation with the control. |\n| `Item` | Optional for groups | Associates each radio or checkbox with its own label and description. |\n| `Label` | Recommended | Supplies a visible, associated label. An accessible name is always required. |\n| `Input` or another integrated control | Required | Receives user input and connects to the field. |\n| `Control` | Alternative control | Provides an unstyled input when you do not use an integrated control. |\n| `Description` | Optional | Adds persistent helper text associated with the control. |\n| `Error` | Optional | Shows feedback for a matching validation state. |\n| `Validity` | Optional | Exposes validity through a children render function. |\n\n`Input` and `Textarea` already integrate with the field. Place them directly inside `Root`; they supply the control behavior themselves. Compound controls such as [Select](/ui/primitives/input/select#compose-with-a-field) keep their own root and parts inside the field.\n\n## External errors\n\nUse `invalid` when your application owns the error state. An explicit `match` makes the error message visible.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\ntype UsernameFieldProps = { error?: string };\n\nexport const UsernameField = ({ error }: UsernameFieldProps) => (\n <Field.Root name=\"username\" invalid={Boolean(error)}>\n <Field.Label>Username</Field.Label>\n <Input autoComplete=\"username\" />\n <Field.Error match={Boolean(error)}>{error}</Field.Error>\n </Field.Root>\n);\n```\n\nKeep error messages actionable and provide a visible label even when the control has a placeholder.\n\n## Grouped controls\n\nUse `Field.Item` inside a radio or checkbox group to associate each choice with its own label and description. Keep the group's label outside the items. An item can be disabled independently; a disabled `Field.Root` disables every item.\n\n<StoryEmbed\n storyId=\"ui-input-field--grouped-items\"\n title=\"Field items\"\n height={220}\n/>\n\n```tsx\nimport { Field, Radio, RadioGroup } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const NotificationsField = () => (\n <Field.Root name=\"notifications\">\n <Field.Label>Notifications</Field.Label>\n <RadioGroup defaultValue=\"important\" style={{ gap: 16, marginTop: 12 }}>\n <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>\n <Radio value=\"important\" />\n <Text>\n <Field.Label>Important updates</Field.Label>\n <Field.Description>\n Only messages that need your attention\n </Field.Description>\n </Text>\n </Field.Item>\n <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>\n <Radio value=\"all\" />\n <Text>\n <Field.Label>All updates</Field.Label>\n <Field.Description>Every change to your records</Field.Description>\n </Text>\n </Field.Item>\n <Field.Item\n disabled\n style={{ display: 'flex', alignItems: 'start', gap: 12 }}\n >\n <Radio value=\"digest\" />\n <Text>\n <Field.Label>Daily digest</Field.Label>\n <Field.Description>Coming soon</Field.Description>\n </Text>\n </Field.Item>\n </RadioGroup>\n </Field.Root>\n);\n```\n\n## Native integration and types\n\nField preserves Base UI validation timing, custom validation, controlled and uncontrolled control values, and value-change event details. `Validity` exposes the validation result through its children function. Integrated controls retain their native form behavior.\n\n`Root`, `Item`, `Label`, `Control`, `Description`, and `Error` forward native props, refs, and `render` composition. Their default elements are a div, div, label, input, paragraph, and div respectively. `Validity` does not render its own element.\n\nImport `FieldRootProps`, `FieldItemProps`, `FieldLabelProps`, `FieldControlProps`, `FieldDescriptionProps`, `FieldErrorProps`, and `FieldValidityProps` from `twenty-ui/primitives/input` for the corresponding upstream part contracts.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<FieldReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Field","entryPoint":"twenty-ui/primitives/input","slug":"input/field","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<FieldRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `validate`: Validates the field when called."},{"name":"className","type":"string | ((state: FieldRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"dirty","type":"boolean","required":false,"defaultValue":null,"description":"Whether the field's value has been changed from its initial value.\nUseful when the field state is controlled by an external library."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction.\nTakes precedence over the `disabled` prop on the `<Field.Control>` component."},{"name":"invalid","type":"boolean","required":false,"defaultValue":null,"description":"Whether the field is invalid.\nUseful when the field state is controlled by an external library."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted.\nTakes precedence over the `name` prop on the `<Field.Control>` component."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"touched","type":"boolean","required":false,"defaultValue":null,"description":"Whether the field has been touched.\nUseful when the field state is controlled by an external library."},{"name":"validate","type":"((value: unknown, formValues: Record<string, any>) => string | void | string[] | Promise<string | void | string[] | null> | null)","required":false,"defaultValue":null,"description":"A function for custom validation. Return a string or an array of strings with\nthe error message(s) if the value is invalid. Returning nothing, `null`, an empty\nstring, or an empty array means the value is valid.\nAsynchronous functions are supported, but they do not prevent form submission\nwhen using `validationMode=\"onSubmit\"`."},{"name":"validationDebounceTime","type":"number","required":false,"defaultValue":"0","description":"How long to wait between `validate` callbacks if\n`validationMode=\"onChange\"` is used. Specified in milliseconds."},{"name":"validationMode","type":"\"onBlur\" | \"onChange\" | \"onSubmit\"","required":false,"defaultValue":"onSubmit","description":"Determines when the field should be validated.\nThis takes precedence over the `validationMode` prop on `<Form>`.\n\n- `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission.\n- `onBlur`: triggers validation when the control loses focus.\n- `onChange`: triggers validation on every change to the control value."}]},{"name":"Item","props":[{"name":"className","type":"string | ((state: FieldItemState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the wrapped control should ignore user interaction.\nThe `disabled` prop on `<Field.Root>` takes precedence over this."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldItemState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldItemState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Label","props":[{"name":"className","type":"string | ((state: FieldLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeLabel","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<label>` element when replacing it via the `render` prop.\nSet to `false` if the rendered element is not a label (for example, `<div>`).\n\nThis is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldLabelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Control","props":[{"name":"className","type":"string | ((state: FieldControlState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Callback fired when the `value` changes. Use when controlled."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldControlState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldControlState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: FieldDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Error","props":[{"name":"className","type":"string | ((state: FieldErrorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"match","type":"boolean | keyof ValidityState","required":false,"defaultValue":null,"description":"Determines whether to show the error message according to the field's\n[ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState).\nSpecifying `true` will always show the error message, and lets external libraries\ncontrol the visibility."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldErrorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldErrorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Validity","props":[{"name":"children","type":"(state: FieldValidityState) => ReactNode","required":true,"defaultValue":null,"description":"A function that accepts the field validity state as an argument.\n\n```jsx\n<Field.Validity>\n {(validity) => {\n return <div>...</div>\n }}\n</Field.Validity>\n```"}]}]}},{"name":"Input","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Input\ndescription: A text input with native attributes, field integration, and two sizes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport InputReference from '/snippets/ui/generated/input/input.mdx';\n\n## Overview\n\n`Input` renders a text input and accepts native input attributes such as `type`, `name`, `required`, `disabled`, and `autoComplete`.\n\n<StoryEmbed\n storyId=\"ui-input-input--display\"\n title=\"Input example\"\n height={140}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial email address. The input owns subsequent changes.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => (\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input\n name=\"email\"\n type=\"email\"\n autoComplete=\"email\"\n defaultValue=\"[email protected]\"\n />\n <Field.Description>Use your work email address.</Field.Description>\n </Field.Root>\n);\n```\n\n## Visual choices\n\nCompare small and medium inputs in their default, focused, invalid, and disabled states. Use validation feedback alongside invalid styling.\n\n<StoryEmbed\n storyId=\"ui-input-input--catalog\"\n title=\"Visual choices for input\"\n height={380}\n/>\n\n## Plain appearance\n\nUse `variant=\"plain\"` inside an existing row or surface. It removes the fill, border, rounded corners and padding and uses natural height. The parent supplies spacing and row dimensions. Text, placeholder and disabled styling remain shared. The blue outline follows the browser's native `:focus-visible` behavior. For text controls this can include pointer focus and autofocus as well as keyboard focus. Invalid state uses a danger outline without changing layout.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const InlineSubject = () => (\n <Field.Root>\n <Field.Label>Subject</Field.Label>\n <Input variant=\"plain\" placeholder=\"Add a subject\" />\n </Field.Root>\n);\n```\n\n`InputGroup` automatically gives its input the plain appearance and keeps the group as the only focus and validation frame. Its `sm` and `md` heights remain 24px and 32px. Standalone plain inputs do not use the fixed height associated with `size`.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same email address in React state. The callback receives the next string value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => {\n const [email, setEmail] = useState('[email protected]');\n\n return (\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input\n name=\"email\"\n type=\"email\"\n autoComplete=\"email\"\n value={email}\n onValueChange={setEmail}\n />\n <Field.Description>Use your work email address.</Field.Description>\n </Field.Root>\n );\n};\n```\n\n## Add an adornment\n\n`InputGroup` owns the surrounding border and layout height. Input size resolves from the explicit child `size`, then the group default, then `md`. The grouped input stretches within the shared border, so use the group's `size` to change the overall field height.\n\n```tsx\nimport { IconSearch } from 'twenty-ui/icon';\nimport { Input, InputGroup } from 'twenty-ui/primitives/input';\n\nexport const CompactSearch = () => (\n <InputGroup size=\"sm\" startElement={<IconSearch size={16} aria-hidden />}>\n <Input aria-label=\"Search contacts\" />\n </InputGroup>\n);\n```\n\n## Native control and wrapper customization\n\nNative attributes, handlers, `className`, `style`, and `ref` target the input. The ref receives an `HTMLInputElement`. Use `render` to compose another input component and forward the supplied props and ref to its native input.\n\n`onChange` receives a React change event for the native input. `onValueChange(value, details)` receives the next string and Base UI event details, including `event`, `reason`, `cancel`, and `allowPropagation`. The event targets the input. Canceling the details preserves Base UI's validation policy; it does not undo a native edit. Controlled callers decide which value to commit.\n\nPut layout styles, attributes, and refs on `InputGroup` when customizing the surrounding wrapper. The group owns no value. Native `name`, `form`, `required`, `readOnly`, `disabled`, submission, and reset behavior remain on the input, with Field naming and validation supplied through `Field.Root`.\n\n## Props\n\nThe reference includes component-specific and inherited Base UI props. Native input attributes are also accepted. A standalone input defaults to `md`; inside a group, an omitted input `size` inherits the group's size.\n\n<InputReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Input","entryPoint":"twenty-ui/primitives/input","slug":"input/input","props":[{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"true","description":"Set false to hide the focus border or outline while keeping errors visible. Defaults to true. InputGroup controls grouped focus styling."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Receives the next string value and Base UI details, including the native event, reason and cancellation methods."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the native input element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, InputState>","required":false,"defaultValue":null,"description":"Composes the native input with a custom element or render callback. Forward the supplied props and ref to an input."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Visual size. Explicit input size takes precedence over the InputGroup default, then md applies. Group layout still sets the surrounding height."},{"name":"style","type":"CSSProperties | ((state: InputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"textAlign","type":"\"end\" | \"start\"","required":false,"defaultValue":null,"description":"Aligns text to the logical start or end of the input. Follows the text direction."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The value of the input. Use when controlled."},{"name":"variant","type":"\"default\" | \"plain\"","required":false,"defaultValue":"default","description":"default keeps the field frame. plain removes fill, border, radius and padding and uses natural height. Its outline follows native :focus-visible, including pointer focus or autofocus on text inputs; invalid state uses a danger outline. InputGroup always owns the grouped frame."}]}},{"name":"InputGroup","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: InputGroup\ndescription: Add prefixes, suffixes, and actions around a text input.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport InputGroupReference from '/snippets/ui/generated/input/input-group.mdx';\n\n## Overview\n\n`InputGroup` gives an [Input](/ui/primitives/input/input) a shared border and optional leading or trailing content. Set `size` on the group to size the container and provide a default for its input. Explicit child size takes precedence over that default; the group still controls the shared layout height.\n\n<StoryEmbed\n storyId=\"ui-input-inputgroup--display\"\n title=\"InputGroup example\"\n height={140}\n/>\n\n## Usage\n\n```tsx\nimport { Field, Input, InputGroup } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const WebsiteField = () => (\n <Field.Root name=\"website\">\n <Field.Label>Website</Field.Label>\n <InputGroup\n startElement={\n <Text render={<span />} aria-hidden>\n https://\n </Text>\n }\n >\n <Input placeholder=\"example.com\" />\n </InputGroup>\n <Field.Description>Enter the domain without https://.</Field.Description>\n </Field.Root>\n);\n```\n\n`startElement` and `endElement` accept React nodes. Prefixes and suffixes are visual content; the input's submitted value contains only what the user enters.\n\n## Visual choices\n\nCompare prefix, suffix, and combined adornments at both input sizes. The group shares its size with the input.\n\n<StoryEmbed\n storyId=\"ui-input-inputgroup--catalog\"\n title=\"Visual choices for input group\"\n height={300}\n/>\n\n## Anatomy\n\nPlace the input inside `InputGroup` and keep field labels and messages outside the shared border.\n\n```text\nField.Root\n├── Field.Label\n├── InputGroup\n│ └── Input\n└── Field.Description\n```\n\n| Part or slot | Requirement | Purpose |\n| --------------------------------------------- | -------------------- | ------------------------------------------------------------------------ |\n| `InputGroup` | Required | Supplies the shared border, layout, and size. |\n| `Input` as `children` | Required | Owns the input value, native attributes, and editing behavior. |\n| `startElement` | Optional prop | Adds a prefix, icon, or other content before the input. |\n| `endElement` | Optional prop | Adds a suffix or action after the input. |\n| `Field.Root`, `Label`, `Description`, `Error` | Optional composition | Associates a label, helper text, and validation feedback with the input. |\n\n`startElement` and `endElement` are React node props, not separate components. `InputGroup` does not supply a label or manage validation. Give the input an accessible name, either through `Field.Label` or its own labeling attributes.\n\n## Trailing action\n\n```tsx\nimport { useState } from 'react';\nimport { Button, Field, Input, InputGroup } from 'twenty-ui/primitives/input';\n\nexport const PasswordField = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <Field.Root name=\"password\">\n <Field.Label>Password</Field.Label>\n <InputGroup\n endElement={\n <Button\n type=\"button\"\n aria-label={visible ? 'Hide password' : 'Show password'}\n variant=\"ghost\"\n size=\"sm\"\n onClick={() => setVisible(!visible)}\n >\n {visible ? 'Hide' : 'Show'}\n </Button>\n }\n >\n <Input\n type={visible ? 'text' : 'password'}\n autoComplete=\"current-password\"\n />\n </InputGroup>\n </Field.Root>\n );\n};\n```\n\nPut labels, validation, and value handling on the field or input. Give adornment buttons their own accessible names and use `type=\"button\"` when they should not submit the form. The group supports `sm` and `md` sizes and defaults to `md`.\n\n## Customize the layout\n\nNative props, `className`, `style`, `render`, and `ref` target the layout div. A custom `render` element receives the layout props and children. Keep the supplied ref on that layout element.\n\nPut `value`, `defaultValue`, `onValueChange`, `name`, `required`, `readOnly`, `disabled`, and the native control ref on `Input`. The group does not manage input state or replace Field label association.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<InputGroupReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"InputGroup","entryPoint":"twenty-ui/primitives/input","slug":"input/input-group","props":[{"name":"endElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered after the input, such as a suffix or a button."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"true","description":"Set false to keep the group border unchanged on focus. Defaults to true. Error styling remains visible."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the layout element, a div by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the layout element. Forward its props, children and ref. Native control props belong on the child input."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the layout and default size for inputs that omit size. Defaults to md."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered before the input, such as a prefix or an icon."}]}},{"name":"NumberField","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: NumberField\ndescription: Compose a numeric field with locale formatting, stepping, native forms, and scrubbing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport NumberFieldReference from '/snippets/ui/generated/input/number-field.mdx';\n\n## Overview\n\n`NumberField` exposes all seven parts of the installed Base UI Number Field: `Root`, `Group`, `Input`, `Decrement`, `Increment`, `ScrubArea`, and `ScrubAreaCursor`. Import it from `twenty-ui/primitives/input`. It retains Base UI's numeric state, formatting, stepping, event details, and native form integration with Twenty UI styling for the input, group, and adjustment controls.\n\nFor the compact preset with fixed formatting and modifier-step defaults, use [NumberStepper](/ui/components/input/number-stepper) from `twenty-ui/components/input`.\n\n<StoryEmbed\n storyId=\"ui-input-numberfield--display\"\n title=\"NumberField example\"\n height={140}\n/>\n\n## Usage\n\n`Root` owns numeric state. `Input` is the visible text input. Use `Group` to arrange optional decrement and increment controls around it. Supply content and accessible names for the controls; the primitive does not inject icons or labels.\n\n```tsx\nimport { IconMinus, IconPlus } from 'twenty-ui/icon';\nimport { Field, NumberField } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => (\n <Field.Root>\n <Field.Label>Quantity</Field.Label>\n <NumberField.Root name=\"quantity\" defaultValue={3} min={0} max={10}>\n <NumberField.Group>\n <NumberField.Decrement aria-label=\"Decrease quantity\">\n <IconMinus size={16} />\n </NumberField.Decrement>\n <NumberField.Input />\n <NumberField.Increment aria-label=\"Increase quantity\">\n <IconPlus size={16} />\n </NumberField.Increment>\n </NumberField.Group>\n </NumberField.Root>\n <Field.Description>Choose up to ten items.</Field.Description>\n </Field.Root>\n);\n```\n\n`Field.Label`, `Field.Description`, and `Field.Error` associate with the visible input. Alternatively, pass `aria-label` or `aria-labelledby` to `Input`. The default `aria-roledescription` is `Number field`; it does not provide an accessible name.\n\n## Values and callbacks\n\nOmit `value` for an uncontrolled field, and supply a numeric `defaultValue` when an initial value is needed. Omitting `defaultValue` starts empty. For a controlled field, pass a number or `null` through `value` and update it from `onValueChange`.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, NumberField } from 'twenty-ui/primitives/input';\n\nexport const PriceInput = () => {\n const [price, setPrice] = useState<number | null>(null);\n const [savedPrice, setSavedPrice] = useState<number | null>(null);\n\n return (\n <Field.Root>\n <Field.Label>Price</Field.Label>\n <NumberField.Root\n value={price}\n onValueChange={setPrice}\n onValueCommitted={setSavedPrice}\n >\n <NumberField.Input placeholder=\"Enter a price\" />\n </NumberField.Root>\n <Field.Description>\n Last committed price: {savedPrice ?? 'empty'}\n </Field.Description>\n </Field.Root>\n );\n};\n```\n\nClearing reports `null`, including when `min` is set. Incomplete drafts such as `-` remain editable without reporting an invalid number. Parseable typing updates the numeric value before the edit is committed. The first step from an empty value starts at zero clamped to the bounds; subsequent steps use the active step amount.\n\n`onValueChange(value, details)` retains the native `event`, `reason`, `cancel`, `allowPropagation`, `isCanceled`, `isPropagationAllowed`, `trigger`, and optional `direction`. Reasons distinguish typing (`input-change`), clearing (`input-clear`), blur normalization (`input-blur`), paste (`input-paste`), keyboard, increment or decrement presses, wheel, scrubbing, and native autofill (`none`). Calling `cancel()` prevents the numeric state update; controlled callers still choose their accepted value.\n\n`onValueCommitted(value, details)` runs on blur after editing, on pointer release after stepping or scrubbing, and immediately for keyboard and wheel adjustments. Clearing commits `null` on blur. Commit details contain `event` and `reason`; they are generic details without change cancellation methods. Focusing and blurring an untouched field does not itself commit a value when no numeric normalization is needed. Explicit rounding options can normalize and commit an untouched value.\n\n## Locale and formatting\n\nSet `locale` and `format` on `Root`. They retain the installed Base UI contract: `locale` accepts `Intl.LocalesArgument`, and `format` accepts `Intl.NumberFormatOptions`. Display formatting is separate from the raw numeric value submitted by the form. The primitive does not force Latin digits, grouping, precision, or modifier steps.\n\n<StoryEmbed\n storyId=\"ui-input-numberfield--locale-currency\"\n title=\"Locale and currency formatting\"\n height={140}\n/>\n\n```tsx\nimport { Field, NumberField } from 'twenty-ui/primitives/input';\n\nexport const AmountInput = () => (\n <Field.Root>\n <Field.Label>Amount in euros</Field.Label>\n <NumberField.Root\n name=\"amount\"\n defaultValue={1234.5}\n locale=\"de-DE\"\n format={{ style: 'currency', currency: 'EUR' }}\n step={0.5}\n smallStep={0.01}\n largeStep={10}\n >\n <NumberField.Input />\n </NumberField.Root>\n </Field.Root>\n);\n```\n\nTyping and paste use the configured locale and supported format symbols. Blur normalizes the displayed text. Explicit precision or rounding options can also normalize the committed number; without those options, formatting alone does not replace an untouched numeric value with rounded display text.\n\n## Stepping and bounds\n\n`step` defaults to `1`, `smallStep` to `0.1` while Alt is held, and `largeStep` to `10` while Shift is held. The active step applies to buttons, Arrow Up and Arrow Down, wheel, and scrub-area movement. `snapOnStep` defaults to `false`; enable it to snap adjustments to the active step. Home and End select the corresponding explicit bound. Native key handlers can call `event.preventBaseUIHandler()` when the owner needs to override Base UI's keyboard behavior.\n\n`min` and `max` are inclusive. Step interactions stay bounded. By default, typed and pasted values also clamp numerically, with the draft normalized on blur. Set `allowOutOfRange` to accept direct edits outside those bounds and let native range validation or application validation report the problem.\n\n`step=\"any\"` disables native step validation while interactive stepping uses `1` and the configured modifier steps. With a numeric step, provide `min` explicitly when native submission must validate step alignment. The numeric step does not round every typed value to a step.\n\n## Scrubbing\n\n`ScrubArea` changes the numeric value as the pointer moves. It supports horizontal or vertical movement, `pixelSensitivity`, and optional `teleportDistance`. The active step and bounds also apply to scrubbing. Use a visible label as the scrub target while keeping the input available for keyboard editing.\n\n<StoryEmbed\n storyId=\"ui-input-numberfield--with-scrubbing\"\n title=\"Scrub the width label\"\n height={150}\n/>\n\nCompose `ScrubAreaCursor` inside `ScrubArea` for a custom cursor during pointer-lock scrubbing. It portals to the document body while active. Base UI falls back to the normal cursor for touch input, denied pointer lock, and WebKit. Set `allowWheelScrub` on `Root` to allow wheel adjustment while the input is focused and hovered; it defaults to `false`.\n\n## Forms and disabled state\n\n`Root` renders a hidden native `input type=\"number\"` for raw numeric submission and native validation. Set `name`, `form`, `required`, `min`, `max`, and `step` on `Root`. `form` can associate the field with a form elsewhere in the document. The default adjustment controls use `type=\"button\"`, so stepping does not submit the form.\n\n`disabled` prevents interaction and excludes the value from submission. `readOnly` prevents changes while keeping the visible input focusable and its form value available. Use a controlled value when the application must reset numeric state; native form reset does not reset it.\n\n## DOM targets and customization\n\n| Part or prop | Default DOM and ref target |\n| ------------------------- | ------------------------------------------------------------------------------ |\n| `Root` / `Root.ref` | The outer `div` |\n| `Root.inputRef` | The hidden native number input |\n| `Root.id` | Associates the visible text input's ID |\n| `Group` / `Group.ref` | The group `div` |\n| `Input` / `Input.ref` | The visible `input type=\"text\"` |\n| `Decrement` / `Increment` | Native buttons |\n| `ScrubArea` | A `span` |\n| `ScrubAreaCursor` | A `span` portaled to the document body while active; its ref is otherwise null |\n\nNative attributes, `className`, `style`, and `render` target the part receiving them. Input customization applies to the visible control; wrapper customization belongs on `Root` or `Group`. To focus the control, use `Input.ref`, rather than `Root.inputRef`.\n\nEach part accepts an element or callback through `render`, with the corresponding public state type. Forward the supplied props and ref to the appropriate DOM element so editing, focus, labels, and validation keep working. When a stepping control renders a non-button element, set `nativeButton={false}`. `className` and `style` also accept state callbacks. State includes numeric `value`, formatted `inputValue`, `required`, `disabled`, `readOnly`, `scrubbing`, and inherited Field state.\n\nThe public entry points export the props and state type for every part, plus `NumberFieldRootChangeEventDetails`, `NumberFieldRootChangeEventReason`, `NumberFieldRootCommitEventDetails`, and `NumberFieldRootCommitEventReason`.\n\n## Front component renderer\n\nReact and Preact sandbox fixtures verify initial locale formatting, localized paste, raw numeric form values, accessible labels, refs, render composition, blur commits, keyboard change and commit details, and pointer change details.\n\nSequential typing after clearing a controlled localized field currently resets the caret in the renderer: typing `2` and then `3` can produce `32`. A formatted pointer adjustment can also race with blur and leave the visible input showing the previous value. Pointer adjustments report changes, but pointer release does not deliver the corresponding commit callback; later blur can commit with `input-blur` instead. Dragging the scrub area and using its custom cursor are also unavailable in the sandbox. These limitations do not affect ordinary React hosts.\n\n## Props\n\nThe reference is generated from the installed public component types. Native attributes and event handlers are also accepted on parts that render elements.\n\n<NumberFieldReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"NumberField","entryPoint":"twenty-ui/primitives/input","slug":"input/number-field","props":[],"parts":[{"name":"Root","props":[{"name":"allowOutOfRange","type":"boolean","required":false,"defaultValue":"false","description":"Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded."},{"name":"allowWheelScrub","type":"boolean","required":false,"defaultValue":"false","description":"Allows wheel adjustments while the visible input is focused and hovered. Defaults to false."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Composed NumberField parts and supporting content."},{"name":"className","type":"string | ((state: NumberFieldRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"defaultValue","type":"number","required":false,"defaultValue":"empty","description":"Initial uncontrolled number. Omit to start empty; the public type accepts a number."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Prevents interaction and excludes the value from form submission."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"ID of the form owning the hidden native number input."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for display and parsing, including currency, units, percent, grouping, and precision. Explicit rounding options can normalize the committed value on blur."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID associated with the visible input. Generated when omitted."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the hidden native number input used for submission and validation. Use Input.ref to focus the visible text input."},{"name":"largeStep","type":"number","required":false,"defaultValue":"10","description":"Amount used while Shift is held. Defaults to 10."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format and parse numbers. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":null,"description":"Inclusive maximum for stepping and native range validation."},{"name":"min","type":"number","required":false,"defaultValue":null,"description":"Inclusive minimum for stepping and native range validation."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name of the raw numeric value submitted by the hidden input."},{"name":"onValueChange","type":"((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the next number or null and change details with the native event, reason, cancellation and propagation methods, and optional stepping direction."},{"name":"onValueCommitted","type":"((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the committed number or null and generic details containing event and reason. Typing commits on blur; pointer steps and scrubbing commit on release; keyboard and wheel changes commit immediately."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Prevents changes while keeping the visible input focusable."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through Root.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldRootState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Requires a numeric value for native form submission."},{"name":"smallStep","type":"number","required":false,"defaultValue":"0.1","description":"Amount used while Alt is held. Defaults to 0.1."},{"name":"snapOnStep","type":"boolean","required":false,"defaultValue":"false","description":"Snaps step interactions to multiples of the active step. Defaults to false."},{"name":"step","type":"number | \"any\"","required":false,"defaultValue":"1","description":"Base amount for buttons, arrow keys, wheel, and scrubbing. Use any to disable native step validation while stepping by 1."},{"name":"style","type":"CSSProperties | ((state: NumberFieldRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."},{"name":"value","type":"number | null","required":false,"defaultValue":null,"description":"Controlled raw numeric value. Use null for an empty field."}]},{"name":"Group","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The visible input and any increment or decrement controls."},{"name":"className","type":"string | ((state: NumberFieldGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the group div, or the element composed through Group.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldGroupState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"Input","props":[{"name":"aria-roledescription","type":"string","required":false,"defaultValue":"Number field","description":"Describes the role to assistive technology. Defaults to Number field; use Field.Label, aria-label, or aria-labelledby for the accessible name."},{"name":"className","type":"string | ((state: NumberFieldInputState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the visible native text input."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState>","required":false,"defaultValue":null,"description":"Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Customize layout through Root or Group."},{"name":"size","type":"number","required":false,"defaultValue":null,"description":"Native input size attribute. Use styles to customize visual dimensions."},{"name":"style","type":"CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"Increment","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Visible content for the increment control. Supply its accessible name."},{"name":"className","type":"string | ((state: NumberFieldIncrementState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the increment button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldIncrementState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldIncrementState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"Decrement","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Visible content for the decrement control. Supply its accessible name."},{"name":"className","type":"string | ((state: NumberFieldDecrementState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the decrement button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldDecrementState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldDecrementState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"ScrubArea","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content the user can drag to adjust the number, plus an optional ScrubAreaCursor."},{"name":"className","type":"string | ((state: NumberFieldScrubAreaState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"direction","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"Pointer movement direction used for scrubbing."},{"name":"pixelSensitivity","type":"number","required":false,"defaultValue":"2","description":"Pixels of pointer movement needed for a step. Larger values reduce sensitivity."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the scrub area span, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldScrubAreaState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."},{"name":"teleportDistance","type":"number","required":false,"defaultValue":null,"description":"Optional distance from the scrub area center at which the pointer loops around."}]},{"name":"ScrubAreaCursor","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Custom cursor content shown during supported pointer-lock scrubbing."},{"name":"className","type":"string | ((state: NumberFieldScrubAreaCursorState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the cursor span portaled to the document body while active. Null while absent."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaCursorState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldScrubAreaCursorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]}]}},{"name":"NumberStepper","entryPoint":"twenty-ui/components/input","content":"---\ntitle: NumberStepper\ndescription: Edit a number with optional bounds and increment or decrement buttons.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport NumberStepperReference from '/snippets/ui/generated/components/input/number-stepper.mdx';\n\n## Overview\n\n`NumberStepper` is the compact convenience preset built from [NumberField](/ui/primitives/input/number-field). It combines a numeric text input with optional decrement and increment buttons. Import it from `twenty-ui/components/input`. Use `NumberField` when you need locale or formatting options, different modifier steps, scrubbing, or independent part composition.\n\n<StoryEmbed\n storyId=\"ui-input-numberstepper--display\"\n title=\"NumberStepper example\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { NumberStepper } from 'twenty-ui/components/input';\nimport { Field } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => (\n <Field.Root>\n <Field.Label style={{ color: 'var(--t-font-color-primary)' }}>\n Quantity\n </Field.Label>\n <NumberStepper defaultValue={3} min={0} max={10} />\n <Field.Description style={{ color: 'var(--t-font-color-secondary)' }}>\n Choose up to ten items.\n </Field.Description>\n </Field.Root>\n);\n```\n\n## Visual options\n\nCompare default, bound, disabled, read-only, and invalid states with or without step buttons.\n\n<StoryEmbed\n storyId=\"ui-input-numberstepper--catalog\"\n title=\"Number stepper bounds and states\"\n height={220}\n/>\n\n## Uncontrolled value\n\nUse `defaultValue` to set the initial quantity. The input owns subsequent changes.\n\n```tsx\nimport { NumberStepper } from 'twenty-ui/components/input';\nimport { Field } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => (\n <Field.Root>\n <Field.Label>Quantity</Field.Label>\n <NumberStepper name=\"quantity\" defaultValue={3} min={0} max={10} step={1} />\n <Field.Description>Choose up to ten items.</Field.Description>\n </Field.Root>\n);\n```\n\n## Controlled value\n\nPass a number or `null` through `value` and update it in `onValueChange` to own the same quantity in React state. The callback receives the next numeric value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { NumberStepper } from 'twenty-ui/components/input';\nimport { Field } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => {\n const [quantity, setQuantity] = useState<number | null>(3);\n\n return (\n <Field.Root>\n <Field.Label>Quantity</Field.Label>\n <NumberStepper\n name=\"quantity\"\n value={quantity}\n onValueChange={setQuantity}\n min={0}\n max={10}\n step={1}\n />\n <Field.Description>Choose up to ten items.</Field.Description>\n </Field.Root>\n );\n};\n```\n\nClearing the field reports `null`. Incomplete text such as `-` or `+` remains editable without reporting an invalid number until it is replaced or stepped. By default, parseable numeric edits report the bounded value; the displayed draft is normalized on blur. Values equal to the current value do not call `onValueChange` again.\n\n`onValueCommitted(value, details)` reports the value after an edit is committed: on blur after typing or clearing, on pointer release after a button adjustment, and immediately for keyboard adjustments. Its details contain the native `event` and `reason`. `onValueChange` retains change details, including cancellation methods and the optional stepping direction.\n\n## Application validation\n\nSet `allowOutOfRange` when the application needs the parsed value before applying its own limits or validation. `onValueChange` then receives typed and pasted numbers outside the range. Uncontrolled fields, or controlled fields that accept those values, preserve them on blur. Controlled fields that reject them return to their accepted value on blur. For example, replacing `60` with `45` reports `4` and then `45`, even when `min={30}`. The application can ignore the intermediate value without accidentally saving the minimum.\n\nButtons and keyboard adjustments still stop at `min` and `max`. Native form validation prevents submission while an accepted value is outside that range. `allowOutOfRange` defaults to `false`.\n\n## Bounds and interaction\n\n`min` and `max` are inclusive. Increment and decrement buttons stop at the matching bound. Arrow Up and Arrow Down adjust the focused input by `step`, which defaults to `1`. Home and End select the corresponding bound when provided; call `event.preventBaseUIHandler()` in `onKeyDown` to keep a key's text editing behavior instead. The same step applies when Shift or Alt is held. Displayed values support up to 15 fraction digits; use a positive step within that precision for decimal adjustments.\n\nValues use Latin digits and show grouping separators from five integer digits, such as `12,500`. Typed and pasted group separators of the browser's locale are accepted.\n\n`step` controls adjustments; it does not round typed values to a step. When `min` is set, native form validation also requires `min` plus a multiple of `step`: with the default `step` of `1`, a typed `2.5` blocks submission. Set `showButtons={false}` for text editing with the same keyboard behavior.\n\nEach button has a default accessible name. Use `decrementLabel` and `incrementLabel` to provide contextual or translated names. Give the input a visible `Field.Label`, `aria-label`, or `aria-labelledby`.\n\n## Forms and focus\n\nUse `name` to include the numeric value in a form. `form` associates it with a form elsewhere in the document. The adjustment buttons use `type=\"button\"`, so adjusting a value does not submit the form. `required` participates in native validation.\n\nUse a controlled `value` when your application needs to reset the field. A native form reset does not reset the numeric state.\n\n`disabled` prevents changes and excludes the value from form submission. `readOnly` prevents changes while keeping the input focusable and its value available to the form.\n\nNative input attributes and handlers, `className`, `style`, `ref`, and `render` apply to the visible text input. The ref receives an `HTMLInputElement`; call `ref.current?.focus()` to focus it. When composing through `render`, forward the supplied props and ref to a native input. Customize the surrounding layout with a separate element, or use the `NumberField.Root` and `NumberField.Group` parts when wrapper access is required. Combine the input with `Field.Description` and `Field.Error` for guidance and validation messages.\n\nThe preset deliberately uses compact styling, Latin digits, up to 15 fraction digits, grouping from five integer digits, and the same `step` for ordinary, Shift, and Alt adjustments. These choices apply only to `NumberStepper`. The full `NumberField` primitive retains Base UI's formatting and stepping options.\n\n## Front component renderer\n\nThe React and Preact renderer sandboxes support typing, keyboard adjustments, bounds, form values, pointer stepping, and pasting over selected text. The renderer gallery verifies these interactions in both runtimes. As with `NumberField`, pointer adjustments report changes, but the sandbox does not currently deliver the corresponding commit callback on pointer release. Ordinary React hosts retain the complete commit behavior.\n\n## Props\n\n<NumberStepperReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"NumberStepper","entryPoint":"twenty-ui/components/input","slug":"components/input/number-stepper","props":[{"name":"allowOutOfRange","type":"boolean","required":false,"defaultValue":"false","description":"Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded."},{"name":"aria-roledescription","type":"string","required":false,"defaultValue":"Number field","description":"A user-friendly description of the input's role for assistive tech. This is a role\ndescription, not an accessible name — use `Field.Label` or `aria-label` to name the control."},{"name":"className","type":"string | ((state: NumberFieldInputState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the visible input."},{"name":"decrementLabel","type":"string","required":false,"defaultValue":"Decrease value","description":"Accessible name for the decrement button."},{"name":"defaultValue","type":"number","required":false,"defaultValue":null,"description":"Initial number when the field owns its value."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the input and both buttons, and omits the form value."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"ID of the form that owns the submitted numeric value."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the visible input. Generated when omitted."},{"name":"incrementLabel","type":"string","required":false,"defaultValue":"Increase value","description":"Accessible name for the increment button."},{"name":"max","type":"number","required":false,"defaultValue":null,"description":"Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur."},{"name":"min","type":"number","required":false,"defaultValue":null,"description":"Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name of the numeric value submitted with a form."},{"name":"onValueChange","type":"((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number."},{"name":"onValueCommitted","type":"((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the committed number or null and generic event details after an edit is committed. Details contain the native event and reason, without change cancellation methods."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Prevents numeric changes while keeping the input focusable."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the visible input element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState>","required":false,"defaultValue":null,"description":"Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Use a separate element to customize the surrounding layout."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Requires a numeric value for native form submission."},{"name":"showButtons","type":"boolean","required":false,"defaultValue":"true","description":"Shows the decrement and increment buttons."},{"name":"step","type":"number","required":false,"defaultValue":"1","description":"Amount added or subtracted by the buttons and arrow keys."},{"name":"style","type":"CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the visible input."},{"name":"value","type":"number | null","required":false,"defaultValue":null,"description":"Controlled numeric value. Use null for an empty field."}]}},{"name":"Textarea","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Textarea\ndescription: Enter multiple lines of text with optional automatic resizing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TextareaReference from '/snippets/ui/generated/input/textarea.mdx';\n\n## Overview\n\nUse `Textarea` for notes, descriptions, and other multiline values. It integrates with [Field](/ui/primitives/input/field) for labels and validation.\n\n<StoryEmbed\n storyId=\"ui-input-textarea--display\"\n title=\"Textarea example\"\n height={190}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial notes. The textarea owns subsequent changes.\n\n```tsx\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const NotesField = () => (\n <Field.Root name=\"notes\">\n <Field.Label>Notes</Field.Label>\n <Textarea rows={4} defaultValue=\"Follow up next week.\" />\n <Field.Description>Add context for your team.</Field.Description>\n </Field.Root>\n);\n```\n\nNative textarea attributes such as `rows`, `maxLength`, `required`, and `readOnly` are available. `size` accepts `sm` or `md` and defaults to `md`.\n\n## Visual choices\n\nCompare the two sizes in default, focused, invalid, and disabled states. Automatic resizing is demonstrated separately below.\n\n<StoryEmbed\n storyId=\"ui-input-textarea--catalog\"\n title=\"Visual choices for textarea\"\n height={440}\n/>\n\n## Plain appearance\n\nUse `variant=\"plain\"` for multiline text inside an existing surface. It removes the fill, border, rounded corners and all padding while keeping the shared text, placeholder and disabled styling. The blue outline follows the browser's native `:focus-visible` behavior. For text controls this can include pointer focus and autofocus as well as keyboard focus. Invalid state uses a danger outline without changing layout.\n\n```tsx\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const InlineNotes = () => (\n <Field.Root>\n <Field.Label>Notes</Field.Label>\n <Textarea variant=\"plain\" autoResize rows={1} maxRows={6} />\n </Field.Root>\n);\n```\n\nThe parent supplies spacing. `rows`, `maxRows` and automatic sizing still control the content height. The row limit excludes padding and borders in the plain appearance. Changing `variant` while automatic sizing is enabled measures the new layout.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same notes in React state. The callback receives the next string value and event details; native `onChange` is also available.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const NotesField = () => {\n const [notes, setNotes] = useState('Follow up next week.');\n\n return (\n <Field.Root name=\"notes\">\n <Field.Label>Notes</Field.Label>\n <Textarea rows={4} value={notes} onValueChange={setNotes} />\n <Field.Description>Add context for your team.</Field.Description>\n </Field.Root>\n );\n};\n```\n\n## Automatic resizing\n\nAutomatic resizing works in either state mode. This example also uses the controlled value for a character count.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const DescriptionField = () => {\n const [description, setDescription] = useState('');\n\n return (\n <Field.Root name=\"description\">\n <Field.Label>Description</Field.Label>\n <Textarea\n value={description}\n onValueChange={setDescription}\n autoResize\n rows={2}\n maxRows={6}\n maxLength={500}\n />\n <Field.Description>\n {description.length} of 500 characters\n </Field.Description>\n </Field.Root>\n );\n};\n```\n\n`autoResize` measures the committed value after controlled updates and measures uncontrolled edits directly. Rejected controlled edits do not change the height. It also updates after native form resets, `rows`, `size`, `variant`, `maxRows`, and available width changes. Use `maxRows` to cap growth and scroll longer content.\n\nAutomatic sizing owns inline `blockSize` while enabled. Turning it off restores the current `style.blockSize`, or clears the automatic size if none is supplied. With automatic sizing off, `rows` and native styles control height. Manual resizing is disabled by default; set `style={{ resize: 'vertical' }}` when callers should resize the control themselves.\n\n## Native control and render composition\n\nNative textarea attributes and handlers, `className`, `style`, and `ref` target the textarea. The ref receives an `HTMLTextAreaElement`. `render` accepts a textarea element or a callback receiving native textarea props and Field state. Forward the supplied props and ref to the native textarea so labels, validation, events, and automatic measurement keep working. Add a separate layout element when wrapper customization is needed.\n\n`onChange` receives a React change event for the native textarea. `onValueChange(value, details)` retains the Base UI signature, including the native `event`, `reason`, `cancel`, and `allowPropagation`. The native event targets the textarea. Canceling the details preserves Base UI's validation policy; it does not undo the native value. Controlled callers choose the committed value.\n\nNative `name`, `form`, `required`, `readOnly`, `disabled`, submission, and reset behavior remain available. Field supplies label, description, name, and validation association. Enter inserts a line break in the textarea.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<TextareaReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Textarea","entryPoint":"twenty-ui/primitives/input","slug":"input/textarea","props":[{"name":"autoResize","type":"boolean","required":false,"defaultValue":"false","description":"Measures committed controlled values or uncontrolled edits, form resets, row, size and variant changes, and width changes. Overrides blockSize while enabled."},{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the textarea, or a function that returns a class\nbased on the input state."},{"name":"maxRows","type":"number","required":false,"defaultValue":null,"description":"Caps automatic height growth. Content beyond this row limit scrolls."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Receives the next string value and Base UI details, including the native event, reason and cancellation methods."},{"name":"ref","type":"Ref<HTMLTextAreaElement>","required":false,"defaultValue":null,"description":"Ref to the native textarea element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, InputState>","required":false,"defaultValue":null,"description":"Composes the native textarea with a custom element or callback receiving textarea props and Field state. Forward the supplied props and ref to a textarea."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the textarea."},{"name":"variant","type":"\"default\" | \"plain\"","required":false,"defaultValue":"default","description":"default keeps the field frame. plain removes fill, border, radius and padding while retaining rows, automatic sizing and maximum rows. Its outline follows native :focus-visible, including pointer focus or autofocus on textareas; invalid state uses a danger outline."}]}},{"name":"Checkbox","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Checkbox\ndescription: Select independent options with checked and indeterminate states.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CheckboxReference from '/snippets/ui/generated/input/checkbox.mdx';\n\n## Overview\n\nUse `Checkbox` when each option can be selected independently. For a mutually exclusive choice, use [RadioGroup](/ui/primitives/input/radio-group).\n\n<StoryEmbed\n storyId=\"ui-input-checkbox-checkbox--display\"\n title=\"Checkbox example\"\n height={100}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultChecked` to set the initial checked state. The checkbox owns subsequent changes.\n\n```tsx\nimport { useId } from 'react';\nimport { Checkbox } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const EmailPreference = () => {\n const checkboxId = useId();\n\n return (\n <label\n htmlFor={checkboxId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Checkbox id={checkboxId} name=\"updates\" value=\"email\" defaultChecked />\n <Text render={<span />}>Receive product updates</Text>\n </label>\n );\n};\n```\n\nA checked, named checkbox contributes its value to a form. Set `uncheckedValue` if the form should also submit a value when it is unchecked.\n\n## Appearance and interaction\n\nCompare checked, indeterminate, and disabled states, then choose the color, size, shape, and variant independently. The enabled examples can be toggled.\n\n<StoryEmbed\n storyId=\"ui-input-checkbox-checkbox--catalog\"\n title=\"Appearance and interaction for checkbox\"\n height={400}\n/>\n\n| Prop | Values | Default |\n| --------- | ------------------------------ | -------- |\n| `size` | `sm`, `md` | `sm` |\n| `variant` | `solid`, `outline`, `soft` | `solid` |\n| `shape` | `square`, `round` | `square` |\n| `color` | `accent`, `success`, `warning` | `accent` |\n\nTab focuses the checkbox and Space toggles it. Clicking its label also toggles it. Use `disabled` to prevent interaction, or `readOnly` when the value should remain unchanged while the control stays focusable. Keep meaning in the label rather than communicating it through color alone.\n\n## Controlled state\n\nPass `checked` and update it with `onCheckedChange` to own the same preference in React state. The callback receives the next boolean and event details.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { Checkbox } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const EmailPreference = () => {\n const checkboxId = useId();\n const [checked, setChecked] = useState(true);\n\n return (\n <label\n htmlFor={checkboxId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Checkbox\n id={checkboxId}\n name=\"updates\"\n value=\"email\"\n checked={checked}\n onCheckedChange={setChecked}\n />\n <Text render={<span />}>Receive product updates</Text>\n </label>\n );\n};\n```\n\n## Indeterminate state\n\nAn indeterminate checkbox represents a partial selection. Derive it from the child options independently of the checkbox's checked state.\n\n```tsx\nimport { useState } from 'react';\nimport { Checkbox } from 'twenty-ui/primitives/input';\n\nexport const ColumnSelection = () => {\n const [showEmail, setShowEmail] = useState(true);\n const [showPhone, setShowPhone] = useState(false);\n\n return (\n <fieldset>\n <legend>Visible columns</legend>\n <label>\n <Checkbox\n checked={showEmail && showPhone}\n indeterminate={showEmail !== showPhone}\n onCheckedChange={(checked) => {\n setShowEmail(checked);\n setShowPhone(checked);\n }}\n />\n All columns\n </label>\n <label>\n <Checkbox checked={showEmail} onCheckedChange={setShowEmail} />\n Email\n </label>\n <label>\n <Checkbox checked={showPhone} onCheckedChange={setShowPhone} />\n Phone\n </label>\n </fieldset>\n );\n};\n```\n\n## Parts and custom content\n\n`Checkbox` assembles the styled root and its default check and indeterminate icons. Use `Checkbox.Root` with `Checkbox.Indicator` to own the indicator content. Root owns state and box appearance; Indicator renders the content you supply.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Checkbox } from 'twenty-ui/primitives/input';\n\nexport const CustomPreference = () => (\n <Checkbox.Root aria-label=\"Updates\" defaultChecked>\n <Checkbox.Indicator>\n <IconCheck aria-hidden />\n </Checkbox.Indicator>\n </Checkbox.Root>\n);\n```\n\n`CheckboxRootProps` and `CheckboxIndicatorProps` are public types exported from `twenty-ui/primitives/input`. Both parts accept native attributes, handlers, refs, `render`, and state-based `className` and `style` callbacks. Root's `ref` targets the visible control; `inputRef` targets the native input. The part ref targets its rendered element. Pass `nativeButton` with `render={<button />}` when replacing Root with a button. Appearance props belong on Root; explicit classes and styles are merged with the defaults.\n\nIndicator receives checked and indeterminate state, including transition state. Set `keepMounted` to retain an unchecked indicator in the DOM; the default styling hides it with opacity. Override its `style` or `className` for custom transitions.\n\n<StoryEmbed\n storyId=\"ui-input-checkbox-parts--composition\"\n title=\"Checkbox part composition\"\n height={100}\n/>\n\nThe callable assembly and its `CheckboxProps` type remain supported. Replace the assembly with Root and its part when supplying custom icons instead of appending another part to the assembly's children.\n\nFor controlled form reset, handle the form's `onReset` and restore `checked` to your initial value. Base UI 1.8 does not restore uncontrolled component state on native form reset. `required`, `form`, `value`, and `uncheckedValue` keep the upstream native input behavior.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<CheckboxReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Checkbox","entryPoint":"twenty-ui/primitives/input","slug":"input/checkbox","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the checkbox is currently ticked.\n\nTo render an uncontrolled checkbox, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: CheckboxRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"success\" | \"warning\"","required":false,"defaultValue":"accent","description":"Color used while the checkbox is checked or indeterminate."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is initially ticked.\n\nTo render a controlled checkbox, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the checkbox is rendered outside the form."},{"name":"hoverable","type":"boolean","required":false,"defaultValue":"true","description":"Adds padding and a hover background around the box."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the input element."},{"name":"indeterminate","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is in a mixed state: neither ticked, nor unticked."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the checkbox is ticked or unticked."},{"name":"parent","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox controls a group of child checkboxes.\n\nMust be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group)."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to tick or untick the checkbox."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must tick the checkbox before submitting a form."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Corner shape of the box."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the checkbox."},{"name":"style","type":"CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the checkbox is unchecked.\nBy default, unchecked checkboxes do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.\nWhen submitting a form, a checked box submits `value`; with no `value`, it submits the native \"on\"."},{"name":"variant","type":"\"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Visual style of the box: filled, outlined, or tinted."}],"parts":[{"name":"Root","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the checkbox is currently ticked.\n\nTo render an uncontrolled checkbox, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: CheckboxRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"success\" | \"warning\"","required":false,"defaultValue":"accent","description":"Color used while the checkbox is checked or indeterminate."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is initially ticked.\n\nTo render a controlled checkbox, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the checkbox is rendered outside the form."},{"name":"hoverable","type":"boolean","required":false,"defaultValue":"true","description":"Adds padding and a hover background around the box."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the input element."},{"name":"indeterminate","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is in a mixed state: neither ticked, nor unticked."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the checkbox is ticked or unticked."},{"name":"parent","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox controls a group of child checkboxes.\n\nMust be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group)."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to tick or untick the checkbox."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must tick the checkbox before submitting a form."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Corner shape of the box."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the checkbox."},{"name":"style","type":"CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the checkbox is unchecked.\nBy default, unchecked checkboxes do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.\nWhen submitting a form, a checked box submits `value`; with no `value`, it submits the native \"on\"."},{"name":"variant","type":"\"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Visual style of the box: filled, outlined, or tinted."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: CheckboxIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the element in the DOM when the checkbox is not checked."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: CheckboxIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Radio","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Radio\ndescription: Render one option in a mutually exclusive radio group.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport RadioReference from '/snippets/ui/generated/input/radio.mdx';\n\n## Overview\n\n`Radio` represents one option inside [RadioGroup](/ui/primitives/input/radio-group). Give each option a distinct `value` and a visible label. The group owns the selected value.\n\n<StoryEmbed\n storyId=\"ui-input-radio--display\"\n title=\"Radio example\"\n height={140}\n/>\n\n## Usage\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const ContactMethod = () => (\n <RadioGroup\n name=\"contactMethod\"\n defaultValue=\"email\"\n aria-label=\"Preferred contact method\"\n >\n <Radio value=\"email\">Email</Radio>\n <Radio value=\"phone\">Phone</Radio>\n <Radio value=\"post\" disabled>\n Postal mail (unavailable)\n </Radio>\n </RadioGroup>\n);\n```\n\nThe `size` prop accepts `sm` or `md` and defaults to `sm`. Use the same size for options in a group.\n\n## Visual choices\n\nCompare selected and disabled states, sizes, and the default and card appearances. Use a labeled group of options for an actual choice.\n\n<StoryEmbed\n storyId=\"ui-input-radio--catalog\"\n title=\"Visual choices for radio\"\n height={380}\n/>\n\n## Complete parts\n\n`Radio.Root` and `Radio.Indicator` expose the installed Base UI parts without the styled assembly. Compose them when you need custom content or indicator placement. The callable `Radio` supplies Twenty's radio appearance and indicator for common options.\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const StorageChoice = () => (\n <RadioGroup aria-label=\"Storage\" defaultValue=\"ssd\">\n <Radio.Root value=\"ssd\">\n <Radio.Indicator keepMounted render={<span />}>\n ✓\n </Radio.Indicator>\n SSD\n </Radio.Root>\n <Radio.Root value=\"hdd\">HDD</Radio.Root>\n </RadioGroup>\n);\n```\n\nStandard radios and `Radio.Root` render a span with radio semantics and an adjacent hidden native input. Card radios render a div. `ref` targets the rendered root; `inputRef` targets the input. `Radio.Indicator` renders a span and its ref targets that element. `render`, state-based `className` and `style`, native attributes and event handlers retain their upstream contracts. The public types include `RadioProps`, `RadioRootProps`, `RadioRootState`, `RadioIndicatorProps` and `RadioIndicatorState`.\n\n## Card options\n\nUse `variant=\"card\"` for full-width options with an inset radio indicator. Card radios keep their div root by default. Use `render` to choose another element explicitly. When that element is a native button, also set `nativeButton`. Keep interactive controls outside the card content.\n\nGive the group enough width for its content and leave space for the indicator at the top right. A title, icon, and short description help explain each choice.\n\n<StoryEmbed\n storyId=\"ui-input-radio--cards-documentation\"\n title=\"Radio card options\"\n height={290}\n/>\n\n```tsx\nimport { IconLayoutKanban, IconTable } from 'twenty-ui/icon';\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nconst VIEWS = [\n {\n value: 'table',\n title: 'Table view',\n description: 'Browse records in rows.',\n Icon: IconTable,\n },\n {\n value: 'board',\n title: 'Board view',\n description: 'Track progress across columns.',\n Icon: IconLayoutKanban,\n },\n];\n\nexport const ViewChoice = () => (\n <RadioGroup\n aria-label=\"Default view\"\n defaultValue=\"table\"\n style={{ width: 280 }}\n >\n {VIEWS.map(({ value, title, description, Icon }) => (\n <Radio key={value} variant=\"card\" value={value}>\n <span style={{ display: 'grid', gap: 8, paddingInlineEnd: 24 }}>\n <Icon size={20} aria-hidden />\n <Text\n render={<span />}\n style={{ fontWeight: 'var(--t-font-weight-medium)' }}\n >\n {title}\n </Text>\n <Text\n render={<span />}\n style={{ color: 'var(--t-font-color-secondary)', lineHeight: 1.5 }}\n >\n {description}\n </Text>\n </span>\n </Radio>\n ))}\n </RadioGroup>\n);\n```\n\n## Explicit native composition\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const BillingChoice = () => (\n <RadioGroup aria-label=\"Billing interval\" defaultValue=\"monthly\">\n <Radio\n variant=\"card\"\n value=\"monthly\"\n nativeButton\n render={<button type=\"button\" />}\n >\n Monthly\n </Radio>\n <Radio\n variant=\"card\"\n value=\"yearly\"\n nativeButton\n render={<button type=\"button\" />}\n >\n Yearly\n </Radio>\n </RadioGroup>\n);\n```\n\nThe ref targets the composed button. For custom non-button roots, leave `nativeButton` false and forward the supplied render props and ref to the actual element.\n\n## Keyboard and selection\n\nTab enters or leaves the group. Arrow keys move between enabled options and select the focused option. Space selects the focused radio. The installed Base UI radio suppresses Enter selection for both default roots and composed native buttons. Selection and change handlers belong on `RadioGroup`; see its [uncontrolled example](/ui/primitives/input/radio-group#uncontrolled-state) and [controlled example](/ui/primitives/input/radio-group#controlled-state).\n\nRadio arrows change selection as they move focus. [Dropdown.SelectionGroup](/ui/components/navigation/dropdown) moves focus with arrows and commits a choice with Enter or Space.\n\n`Radio` and `Radio.Root` are generic over the value type. Keep that type consistent with its group. Native attributes such as `aria-describedby` can associate an option with additional help text.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<RadioReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"Radio","entryPoint":"twenty-ui/primitives/input","slug":"input/radio","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Option content. Card options wrap it in a padded full-width content area."},{"name":"className","type":"string | ((state: RadioRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the component should ignore user interaction."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user should be unable to select the radio button."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user must choose a value before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the radio."},{"name":"style","type":"CSSProperties | ((state: RadioRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"TValue","required":true,"defaultValue":null,"description":"The unique identifying value of the radio in a group."},{"name":"variant","type":"\"card\" | \"default\"","required":false,"defaultValue":"default","description":"Appearance of the styled assembly: a standard radio or a full-width card. Standard radios use a span and card radios use a div unless render replaces the root."}],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: RadioRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the component should ignore user interaction."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user should be unable to select the radio button."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user must choose a value before submitting a form."},{"name":"style","type":"CSSProperties | ((state: RadioRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"Value","required":true,"defaultValue":null,"description":"The unique identifying value of the radio in a group."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: RadioIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM when the radio button is inactive."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: RadioIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"RadioGroup","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: RadioGroup\ndescription: Manage a single selection across a set of radio options.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport RadioGroupReference from '/snippets/ui/generated/input/radio-group.mdx';\n\n## Overview\n\n`RadioGroup` coordinates the value, keyboard navigation, and form submission of its [Radio](/ui/primitives/input/radio) children.\n\n<StoryEmbed\n storyId=\"ui-input-radiogroup--display\"\n title=\"RadioGroup example\"\n height={110}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial billing frequency. The group owns subsequent changes.\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const BillingFrequency = () => (\n <RadioGroup\n name=\"billingFrequency\"\n defaultValue=\"monthly\"\n aria-label=\"Billing frequency\"\n >\n <Radio value=\"monthly\">Monthly</Radio>\n <Radio value=\"yearly\">Yearly</Radio>\n </RadioGroup>\n);\n```\n\nThe group's `name` identifies the selected value in form submission. Give the group an accessible name as well as labeling each radio.\n\n### Horizontal layout\n\nGroups use a vertical column by default. Set `orientation=\"horizontal\"` for a row. The prop controls visual layout through `data-orientation`; it does not set `aria-orientation` or change keyboard navigation. Both horizontal and vertical arrow keys retain the existing Base UI behavior, including right-to-left navigation through [DirectionProvider](/ui/primitives/layout/direction-provider).\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const HorizontalBillingFrequency = () => (\n <RadioGroup\n orientation=\"horizontal\"\n name=\"billingFrequency\"\n defaultValue=\"monthly\"\n aria-label=\"Billing frequency\"\n >\n <Radio value=\"monthly\">Monthly</Radio>\n <Radio value=\"yearly\">Yearly</Radio>\n </RadioGroup>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-input-radiogroup--horizontal\"\n title=\"Horizontal RadioGroup\"\n height={80}\n/>\n\nThe default gap stays the same in either direction.\n\n## Anatomy\n\nPut each `Radio` or `Radio.Root` inside the group and associate it with a label. Use `Radio.Indicator` to compose a custom indicator. `RadioGroup` and `Radio` are separate exports.\n\n```text\nfieldset\n├── legend\n└── RadioGroup\n ├── label\n │ └── Radio\n └── label\n └── Radio\n```\n\n| Part | Requirement | Purpose |\n| -------------------- | --------------------------- | ---------------------------------------------------------- |\n| `RadioGroup` | Required | Owns selection, keyboard navigation, and form integration. |\n| `Radio` | One per option | Supplies an option with a distinct `value`. |\n| `label` | Recommended for each option | Provides a visible, clickable name for its radio. |\n| `fieldset`, `legend` | Optional grouping | Groups related controls under a visible heading. |\n\nGive the group its own accessible name using `aria-label` or `aria-labelledby`. In the examples below, `aria-labelledby` connects the group to the legend. Each radio also needs its own name. Put selection props on `RadioGroup` and option values on `Radio`.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same billing frequency in React state. Selection belongs to the group, not to individual radio controls.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const BillingFrequency = () => {\n const labelId = useId();\n const [billingFrequency, setBillingFrequency] = useState('monthly');\n\n return (\n <fieldset>\n <legend id={labelId}>Billing frequency</legend>\n <RadioGroup\n name=\"billingFrequency\"\n value={billingFrequency}\n onValueChange={setBillingFrequency}\n aria-labelledby={labelId}\n >\n <label>\n <Radio value=\"monthly\" />\n Monthly\n </label>\n <label>\n <Radio value=\"yearly\" />\n Yearly\n </label>\n </RadioGroup>\n </fieldset>\n );\n};\n```\n\n`onValueChange` receives the next value and event details. The generic value type is inferred from the props. Use `disabled` on the group to disable every option, or on an individual radio to disable one choice. Arrow keys navigate and select enabled options; Tab moves out of the group. The installed Base UI version supports both horizontal and vertical arrow keys. RadioGroup adds the visual-only `orientation` prop without changing that keyboard contract.\n\n## Native integration and event details\n\n`RadioGroup` renders a div by default. Native props and `ref` target that element; `render` composes another element and changes the actual ref target. `inputRef` targets the representative hidden input of a child radio, using the selected enabled option or an enabled fallback. The public types include generic `RadioGroupProps`, `RadioGroupState`, `RadioGroupChangeEventReason` and `RadioGroupChangeEventDetails`.\n\nThe callback receives the original event details, including the native `event`, `reason`, `cancel()` and `allowPropagation()`. Cancel a proposed change before updating controlled state when the choice should be rejected.\n\nKeep `name`, `form`, `required`, `disabled` and `readOnly` on the group for the existing Base UI form contract. The selected value is submitted under `name`; disabled groups are excluded and read-only groups keep their selection. `form` supports a group outside its owning form. The installed version does not restore group state automatically on native form reset. Reset controlled state from the form's `onReset` handler when your workflow requires it.\n\nIn sandboxed front components, put the group inside its owning form. The renderer forwards `required` validation and blocks explicit `form` references, which otherwise resolve across the host document.\n\n[SegmentedControl](/ui/components/input/segmented-control) is a convenience preset assembled from these primitives for a short exclusive choice. It uses radio semantics and requires an accessible group name. Tabs and tab-panel navigation are separate controls.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<RadioGroupReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"RadioGroup","entryPoint":"twenty-ui/primitives/input","slug":"input/radio-group","props":[{"name":"className","type":"string | ((state: RadioGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"TValue","required":false,"defaultValue":null,"description":"The uncontrolled value of the radio button that should be initially selected.\n\nTo render a controlled radio group, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the radio inputs.\nUseful when the radio group is rendered outside the form."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onValueChange","type":"((value: TValue, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Callback fired when the value changes."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"vertical","description":"Visual layout direction, reflected in data-orientation. Does not change arrow-key navigation or set aria-orientation."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to select a different radio button in the group."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"style","type":"CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"TValue","required":false,"defaultValue":null,"description":"The controlled value of the radio item that should be currently selected.\n\nTo render an uncontrolled radio group, use the `defaultValue` prop instead."}]}},{"name":"Autocomplete","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Autocomplete\ndescription: Suggest values while the user types and keeps focus in the input.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AutocompleteReference from '/snippets/ui/generated/input/autocomplete.mdx';\n\n## Overview\n\nUse `Autocomplete` for suggestions attached to a text input. The input keeps its caret and keyboard focus while arrow keys highlight suggestions. Use [Select](/ui/primitives/input/select) when the user must choose a value from a fixed list. [Dropdown](/ui/components/navigation/dropdown) remains the higher-level component for menus and pickers.\n\n<StoryEmbed\n storyId=\"ui-input-autocomplete--display\"\n title=\"Autocomplete example\"\n height={360}\n/>\n\n## Usage\n\nPass `items` to `Root` and render them through `List` so filtering updates the visible suggestions. `autoHighlight=\"always\"` highlights the first result whenever the list opens.\n\n```tsx\nimport { Autocomplete } from 'twenty-ui/primitives/input';\n\nconst FRUITS = ['Apple', 'Banana', 'Cherry'];\n\nexport const FruitInput = () => (\n <Autocomplete.Root items={FRUITS} autoHighlight=\"always\">\n <Autocomplete.InputGroup>\n <Autocomplete.Input aria-label=\"Fruit\" placeholder=\"Search fruits\" />\n </Autocomplete.InputGroup>\n <Autocomplete.Portal>\n <Autocomplete.Positioner>\n <Autocomplete.Popup>\n <Autocomplete.Empty>No fruits found</Autocomplete.Empty>\n <Autocomplete.List>\n {(fruit: string) => (\n <Autocomplete.Item key={fruit} value={fruit}>\n {fruit}\n </Autocomplete.Item>\n )}\n </Autocomplete.List>\n </Autocomplete.Popup>\n </Autocomplete.Positioner>\n </Autocomplete.Portal>\n </Autocomplete.Root>\n);\n```\n\n`value` and `onValueChange` control the input text. Use `defaultValue` for an uncontrolled initial value. Open state is independent: use `open` and `onOpenChange`, or `defaultOpen`. `Item.onClick` handles both pointer selection and Enter from the input.\n\n`mode=\"list\"` filters without changing input text on highlight. `mode=\"both\"` also supplies inline completion. `mode=\"inline\"` keeps all items and supplies inline completion; `mode=\"none\"` keeps all items without inline completion. `readOnly` prevents inline completion from changing the input.\n\n## Anatomy\n\nKeep related parts inside a mounted `Autocomplete.Root`. Compose the portal destination, positioning wrapper, and content separately. `InputGroup` optionally groups the input with adjacent controls and anchors the popup to that group.\n\n```text\nAutocomplete.Root\n├── Autocomplete.InputGroup (optional)\n│ ├── Autocomplete.Input\n│ ├── Autocomplete.Clear (optional)\n│ └── Autocomplete.Trigger (optional)\n│ └── Autocomplete.Icon (optional)\n├── Autocomplete.Portal\n│ ├── Autocomplete.Backdrop (optional)\n│ └── Autocomplete.Positioner\n│ └── Autocomplete.Popup\n│ ├── Autocomplete.Arrow (optional)\n│ ├── Autocomplete.Empty\n│ └── Autocomplete.List\n│ ├── Autocomplete.Item\n│ ├── Autocomplete.Group (optional)\n│ │ ├── Autocomplete.GroupLabel\n│ │ └── Autocomplete.Collection\n│ │ └── Autocomplete.Item\n│ ├── Autocomplete.Row (optional, with Root.grid)\n│ │ └── Autocomplete.Item\n│ └── Autocomplete.Separator (optional)\n├── Autocomplete.Status (optional)\n└── Autocomplete.Value (optional)\n```\n\n| Part | Purpose and native target |\n| ------------ | ------------------------------------------------------------------------------- |\n| `Root` | Owns input value, filtering, highlights, and open state. Renders no element. |\n| `Value` | Reads the input text through children or a render function. Renders no element. |\n| `InputGroup` | Groups the input and adjacent controls. Targets a div. |\n| `Input` | Renders the combobox input and retains keyboard focus. Targets an input. |\n| `Trigger` | Opens or closes suggestions. Targets a button. |\n| `Icon` | Contains a trigger indicator. Targets a span. |\n| `Clear` | Clears the input value. Targets a button. |\n| `Portal` | Chooses the destination and mounting policy. Targets its portal div. |\n| `Backdrop` | Supplies an optional overlay beneath the popup. Targets a div. |\n| `Positioner` | Owns anchor, alignment, offsets, and collision handling. Targets its div. |\n| `Popup` | Renders the suggestion content and optional focus behavior. Targets its div. |\n| `Arrow` | Supplies an optional positioned arrow inside Popup. Targets a div. |\n| `List` | Renders filtered items. Targets a div with the listbox or grid role. |\n| `Item` | Renders a suggestion and handles pointer or keyboard selection. Targets a div. |\n| `Group` | Groups related items. Targets a div. |\n| `GroupLabel` | Labels its parent group. Targets a div. |\n| `Row` | Groups a row of items when `Root.grid` is enabled. Targets a div. |\n| `Collection` | Renders filtered items through a function child. Renders no element. |\n| `Separator` | Separates items or groups visually. Targets a div. |\n| `Empty` | Announces when no matching items are available. Targets a div. |\n| `Status` | Announces changes such as asynchronous loading status. Targets a div. |\n\nRendered parts retain native attributes, handlers, refs, state-based `className` and `style`, and element/function `render` composition from the installed Base UI API. Native props and refs target the part's own element. Custom components must forward supplied props and refs. Public part props and state types are exported from `twenty-ui/primitives/input`, together with Root actions and change/highlight event detail types.\n\n`Autocomplete.useFilter()` supplies locale-aware `contains`, `startsWith`, and `endsWith` matching. `Autocomplete.useFilteredItems<TItem>()` reads the internally filtered collection under Root. Treat that result as read-only.\n\n## Object and grouped items\n\nItems can be strings or arbitrary objects. Use `itemToStringValue` to supply the text used for filtering, completion, and form submission. Objects shaped as `{ value, label }` use their label automatically. Render the same item value supplied through Root; no Twenty-specific item shape or selection equality prop is required. Autocomplete owns text input rather than a separate selected object value.\n\nFor grouped data, pass groups with an `items` array. Root preserves the item type for `itemToStringValue` and `onItemHighlighted`. Render each group's filtered children through `Group` and `Collection`:\n\n```tsx\nimport { Autocomplete } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype City = { id: number; name: string; country: string };\ntype CityGroup = { label: string; items: City[] };\n\nconst CITY_GROUPS: CityGroup[] = [\n {\n label: 'Europe',\n items: [\n { id: 1, name: 'Paris', country: 'France' },\n { id: 2, name: 'Lisbon', country: 'Portugal' },\n ],\n },\n];\n\nexport const GroupedCityInput = () => (\n <Text\n style={{ display: 'grid', alignContent: 'start', gap: 8, width: '100%' }}\n >\n <label htmlFor=\"grouped-city\">\n <Text render={<span />}>City</Text>\n </label>\n <Autocomplete.Root\n items={CITY_GROUPS}\n itemToStringValue={(city) => city.name}\n autoHighlight=\"always\"\n >\n <Autocomplete.Input id=\"grouped-city\" placeholder=\"Search cities\" />\n <Autocomplete.Portal>\n <Autocomplete.Positioner>\n <Autocomplete.Popup>\n <Autocomplete.Empty>No matching cities</Autocomplete.Empty>\n <Autocomplete.List>\n {(group: CityGroup) => (\n <Autocomplete.Group key={group.label} items={group.items}>\n <Autocomplete.GroupLabel>\n {group.label}\n </Autocomplete.GroupLabel>\n <Autocomplete.Collection>\n {(city: City) => (\n <Autocomplete.Item\n key={city.id}\n value={city}\n description={city.country}\n >\n {city.name}\n </Autocomplete.Item>\n )}\n </Autocomplete.Collection>\n </Autocomplete.Group>\n )}\n </Autocomplete.List>\n </Autocomplete.Popup>\n </Autocomplete.Positioner>\n </Autocomplete.Portal>\n </Autocomplete.Root>\n </Text>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-input-autocomplete-collections--grouped-objects\"\n title=\"Grouped object suggestions\"\n height={440}\n/>\n\n`Item.startIcon`, `Item.endIcon`, and `Item.description` provide supporting content. Compose `Trigger` and `Clear` with Twenty UI [Button](/ui/primitives/input/button) through `render`. `Icon` can contain an icon from `twenty-ui/icon`. Keep `Status` and `Empty` mounted while updating their children so screen readers can announce changes.\n\n## External filtering and server suggestions\n\nUse `filteredItems` when your application owns filtering. It must preserve the flat or grouped structure of `items`. `filter` accepts a custom matching function; `filter={null}` disables internal filtering for results already filtered by a server.\n\n```tsx\nimport { useState } from 'react';\nimport { Autocomplete } from 'twenty-ui/primitives/input';\n\nconst CITIES = ['Paris', 'London', 'Lisbon'];\n\nexport const CityPrefixInput = () => {\n const [value, setValue] = useState('');\n const { startsWith } = Autocomplete.useFilter();\n const filteredItems = CITIES.filter((city) => startsWith(city, value));\n\n return (\n <Autocomplete.Root\n items={CITIES}\n filteredItems={filteredItems}\n value={value}\n onValueChange={setValue}\n autoHighlight=\"always\"\n >\n <Autocomplete.Input aria-label=\"City prefix\" />\n <Autocomplete.Portal>\n <Autocomplete.Positioner>\n <Autocomplete.Popup>\n <Autocomplete.Empty>No matching cities</Autocomplete.Empty>\n <Autocomplete.List>\n {(city: string) => (\n <Autocomplete.Item key={city} value={city}>\n {city}\n </Autocomplete.Item>\n )}\n </Autocomplete.List>\n </Autocomplete.Popup>\n </Autocomplete.Positioner>\n </Autocomplete.Portal>\n </Autocomplete.Root>\n );\n};\n```\n\nKeep Root mounted when results arrive asynchronously. Control `open` independently so a response can open suggestions while the input remains focused. A mounted `Status` can announce loading; update `Empty` when the completed response has no results. The parent owns debounce, request cancellation, and stale response protection.\n\n`onValueChange` and `onOpenChange` receive the upstream event details, including `reason`, native `event`, `trigger`, `cancel()`, and `allowPropagation()`. Controlled callers decide which requested updates to commit. For example, ignore the `escape-key` value change to keep a server query, or ignore `input-change` opening until results arrive. `onItemHighlighted` receives the original typed item and its highlight reason. Cancellation keeps the installed Base UI semantics; it does not replace the application's controlled-state policy.\n\n## Input composition and native forms\n\n`Input` accepts `size=\"sm\"` or `size=\"md\"` and uses the same styles as [Input](/ui/primitives/input/input). Compose it with an existing input using `render`. The composed control then owns its look: `Input` adds no Input styles and ignores `size`, but still passes your `className`, native attributes, handlers, ref, and state attributes. Forward them to the actual input element. Render Twenty UI `Input` to keep the standard look.\n\n`InputGroup` provides layout and an anchor without adding input borders. It can contain chips or render an existing wrapper. Use [InputGroup](/ui/primitives/input/input-group) through its `render` prop when the whole group needs input styling, as the grouped object suggestions story does. An `Input` without `render` inside it drops its own border. Give the input an accessible label or compose it with [Field](/ui/primitives/input/field).\n\nRoot preserves the upstream `name`, `form`, `disabled`, `readOnly`, and native form behavior. Input's native attributes and ref target its input. `submitOnItemClick` opts into form submission when selecting a suggestion; the default does not submit.\n\nInput preserves Base UI's native IME handling, including composition events and its keyboard confirmation guard.\n\nThe installed Base UI version retains an uncontrolled query on native form reset. For a controlled query, handle the form's `onReset` and restore the application's initial value.\n\n## Placement, portal destination, and dismissal\n\n`Positioner` defaults to `side=\"bottom\"`, `align=\"start\"`, and `sideOffset={8}`. It retains the installed Base UI anchor and positioning contract, including element/ref/function/virtual anchors, functional offsets, `positionMethod`, `collisionBoundary`, `collisionPadding`, `collisionAvoidance`, `arrowPadding`, `sticky`, and `disableAnchorTracking`. Configure these on Positioner. DirectionProvider controls logical placement and DOM direction.\n\n`Popup` uses the anchor width as its minimum width. Set its `width` to supply a fixed content width. Its native props, styles, render composition, and ref target the content element independently of Positioner and Portal. Popup's `initialFocus` and `finalFocus` retain upstream focus options. By default, suggestions keep focus in the input.\n\nConfigure `container` and `keepMounted` on `Portal`. Omitting the container uses the nearest scoped ThemeProvider destination, then Base UI's parent portal or document body. An explicit `null` waits without rendering until a container is supplied. Element, ShadowRoot, and ref destinations pass through to Base UI. An unresolved ref retains Base UI's parent-portal/body fallback.\n\nThe default scoped destination preserves its CSS tokens and color scheme. An explicit destination inherits CSS from its actual DOM scope, so place it inside the intended theme scope or supply those styles there. React context and direction remain available across portals. ShadowRoot targets need the library's CSS and theme styles in that shadow tree.\n\nArrow keys change the highlighted item while the input keeps focus. Enter selects it; Escape and outside interaction request dismissal using upstream semantics. An outside press can activate the destination control. Higher-level pickers can own a different activation policy in their adapter. Call `event.preventBaseUIHandler()` in Input's `onKeyDown` to skip the built-in handler for a key you handle yourself. Use `event.preventDefault()` as well when suppressing the browser's native action.\n\n`Root.inline` with `open` renders suggestions without the popup assembly. Inline items retain their `onClick` selection callbacks, but the installed upstream component fills the input automatically only when its Popup is present. Handle `Item.onClick` when inline selection should update your controlled text. `Root.grid` and `Row` support grid navigation. These modes retain the upstream collection and rendering APIs.\n\n## Migration\n\nWrap Popup with `Autocomplete.Positioner` and `Autocomplete.Portal`. Positioner requires the Portal context; inline suggestions omit the whole popup assembly. Move placement, anchor, and collision props from Popup to Positioner. Move `container` and mounting configuration to Portal. Keep width, content styles, native props, handlers, and refs on Popup. Use an explicit `Arrow` child for an arrow.\n\nInside front components, keep the existing scoped portal policy. This API does not expand renderer portal destinations or geometry, scrolling, and dismissal capabilities; those renderer capabilities have separate ownership. Production picker adapters retain their deliberate activation workflows.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, accessible names, and event handlers are also accepted on rendered parts.\n\n<AutocompleteReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Autocomplete","entryPoint":"twenty-ui/primitives/input","slug":"input/autocomplete","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<AutocompleteRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the autocomplete after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the autocomplete completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the autocomplete imperatively when called."},{"name":"autoHighlight","type":"boolean | \"always\"","required":false,"defaultValue":"false","description":"Whether the first matching item is highlighted automatically.\n- `true`: highlight after the user types and keep the highlight while the query changes.\n- `'always'`: always highlight the first item."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popup is initially open.\n\nTo render a controlled popup, use the `open` prop instead."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The uncontrolled input value of the autocomplete when it's initially rendered.\n\nTo render a controlled autocomplete, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"filter","type":"AutocompleteRootProps<TItem>[\"filter\"]","required":false,"defaultValue":null,"description":"Filter function used to match items against the input query."},{"name":"filteredItems","type":"readonly TItem[] | readonly { items: readonly TItem[] }[]","required":false,"defaultValue":null,"description":"Filtered items to display in the list.\nWhen provided, the list uses these items instead of filtering the `items` prop internally.\nWhen `items` is also provided, this array must preserve its flat or grouped structure.\nNullish entries are not supported, as in `items`.\nUse when you want to control filtering logic externally with the `useFilter()` hook."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the internal input.\nUseful when the autocomplete is rendered outside the form."},{"name":"grid","type":"boolean","required":false,"defaultValue":"false","description":"Whether list items are presented in a grid layout.\nWhen enabled, arrow keys navigate across rows and columns inferred from DOM rows."},{"name":"highlightItemOnHover","type":"boolean","required":false,"defaultValue":"true","description":"Whether moving the pointer over items should highlight them.\nDisabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the component."},{"name":"inline","type":"boolean","required":false,"defaultValue":"false","description":"Whether the list is rendered inline without using the component's own popup.\n\nSpecify `open` unconditionally in conjunction with this prop so the list is considered\nvisible: `<Autocomplete.Root inline open>`"},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to the hidden input element."},{"name":"items","type":"readonly TItem[] | readonly { items: readonly TItem[] }[]","required":false,"defaultValue":null,"description":"Flat items or groups with an items array. Preserves the upstream item type; nullish entries are not supported."},{"name":"itemToStringValue","type":"(itemValue: TItem) => string","required":false,"defaultValue":null,"description":"When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission.\nIf the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop."},{"name":"keepHighlight","type":"boolean","required":false,"defaultValue":"false","description":"Whether the highlighted item should be preserved when the pointer leaves the list."},{"name":"limit","type":"number","required":false,"defaultValue":"-1","description":"The maximum number of items to display in the list."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"The locale to use for string comparison.\nDefaults to the user's runtime locale."},{"name":"loopFocus","type":"boolean","required":false,"defaultValue":"true","description":"Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input.\nThe input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).\nWhen disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>."},{"name":"modal","type":"boolean","required":false,"defaultValue":"false","description":"Determines if the popup enters a modal state when open.\n- `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n\nOn touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior."},{"name":"mode","type":"\"both\" | \"inline\" | \"list\" | \"none\"","required":false,"defaultValue":"list","description":"Controls how the autocomplete behaves with respect to list filtering and inline autocompletion.\n- `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.\n- `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion).\n- `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion).\n- `none`: items are static (not filtered), and the input value will not change based on the active item."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onItemHighlighted","type":"(highlightedValue: TItem | undefined, eventDetails: AutocompleteRootHighlightEventDetails) => void","required":false,"defaultValue":null,"description":"Callback fired when an item is highlighted or unhighlighted.\nReceives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.\nThe `reason` can be:\n- `'keyboard'`: the highlight changed due to keyboard navigation.\n- `'pointer'`: the highlight changed due to pointer hovering. The event may be a `MouseEvent`\n rather than a `PointerEvent`.\n- `'none'`: the highlight changed for another reason, such as typing, `autoHighlight`, the\n item list changing, or the popup opening or closing."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: AutocompleteRootOpenChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Event handler called when the popup is opened or closed."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the popup is opened or closed."},{"name":"onValueChange","type":"((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Event handler called when the input value of the autocomplete changes."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is currently open. Use when controlled."},{"name":"openOnInputClick","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popup opens when clicking the input."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to choose a different option from the popup."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"submitOnItemClick","type":"boolean","required":false,"defaultValue":"false","description":"Whether clicking an item should submit the autocomplete's owning form.\nBy default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form.\nUseful when the autocomplete is used as a single-field form search input."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The input value of the autocomplete. Use when controlled."},{"name":"virtualized","type":"boolean","required":false,"defaultValue":"false","description":"Whether the items are being externally virtualized."}]},{"name":"Value","props":[{"name":"children","type":"ReactNode | ((value: string) => ReactNode)","required":false,"defaultValue":null,"description":"Content or render function receiving the current input text."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: AutocompleteTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: AutocompleteTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"InputGroup","props":[{"name":"className","type":"string | ((state: AutocompleteInputGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteInputGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: AutocompleteInputGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Input","props":[{"name":"className","type":"string | ((state: ComboboxInputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxInputState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Visual size of the input. Inside an InputGroup, the group size applies. Not accepted with render."},{"name":"style","type":"CSSProperties | ((state: ComboboxInputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Icon","props":[{"name":"className","type":"string | ((state: ComboboxIconState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxIconState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxIconState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Clear","props":[{"name":"className","type":"string | ((state: ComboboxClearState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should remain mounted in the DOM when not visible."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxClearState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxClearState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: ComboboxPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Omitted uses the scoped theme container; explicit null waits without rendering. Element, ShadowRoot and ref targets pass through to Base UI."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the portal mounted in the DOM while the popup is hidden."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: ComboboxBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"start","description":"Alignment relative to the anchor. Defaults to start."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: ComboboxPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div, separate from Popup and Portal."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"8","description":"Distance from the anchor. Defaults to 8; supports functional offsets."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: ComboboxPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"className","type":"string | ((state: ComboboxPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popup is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popup is opened.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"width","type":"string | number","required":false,"defaultValue":null,"description":"Width of the popup. Overrides its default minimum anchor width."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: ComboboxArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"List","props":[{"name":"className","type":"string | ((state: ComboboxListState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxListState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxListState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Status","props":[{"name":"className","type":"string | ((state: ComboboxStatusState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxStatusState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxStatusState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Group","props":[{"name":"className","type":"string | ((state: ComboboxGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"items","type":"readonly any[]","required":false,"defaultValue":null,"description":"Items to be rendered within this group.\nWhen provided, child `Collection` components will use these items."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"GroupLabel","props":[{"name":"className","type":"string | ((state: ComboboxGroupLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxGroupLabelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxGroupLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Item","props":[{"name":"className","type":"string | ((state: AutocompleteItemState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"end\" | \"inline\"","required":false,"defaultValue":"inline","description":"Where the description renders: inline after the content or at the end of the row."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"index","type":"number","required":false,"defaultValue":null,"description":"The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onClick","type":"((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)","required":false,"defaultValue":null,"description":"An optional click handler for the item when selected.\nIt fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteItemState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties | ((state: AutocompleteItemState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":false,"defaultValue":"null","description":"A unique value that identifies this item."}]},{"name":"Row","props":[{"name":"className","type":"string | ((state: ComboboxRowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxRowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxRowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Collection","props":[{"name":"children","type":"(item: any, index: number) => ReactNode","required":true,"defaultValue":null,"description":"Render function receiving each filtered item and its index."}]},{"name":"Empty","props":[{"name":"className","type":"string | ((state: ComboboxEmptyState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxEmptyState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxEmptyState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Separator","props":[{"name":"className","type":"string | ((state: AutocompleteSeparatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The orientation of the separator."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteSeparatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: AutocompleteSeparatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Select","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Select\ndescription: Choose one or more values from a popup list of options.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SelectReference from '/snippets/ui/generated/input/select.mdx';\n\n## Overview\n\nUse `Select` for a form value chosen from a list. [Dropdown](/ui/components/navigation/dropdown) remains the main higher-level API for menus, pickers, panels, and pages that combine those workflows.\n\n<StoryEmbed\n storyId=\"ui-input-select--display\"\n title=\"Select example\"\n height={240}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial priority. The select owns subsequent selection changes.\n\n```tsx\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PrioritySelect = () => (\n <Select.Root name=\"priority\" defaultValue=\"normal\" items={PRIORITIES}>\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value placeholder=\"Choose a priority\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n);\n```\n\nSupply `items` on `Root` so `Value` renders the selected item's label; without it, the trigger shows the raw value. The selected value can be `null` when nothing is selected.\n\n## Anatomy\n\nCompose the public parts inside `Select.Root`. `Trigger` and `Item` render only their children. Add `Icon`, `ItemText`, and `ItemIndicator` explicitly when you want the default chevron, label, and checkmark.\n\n```text\nSelect.Root\n├── Select.Label\n├── Select.Trigger\n│ ├── Select.Value\n│ └── Select.Icon\n└── Select.Portal\n ├── Select.Backdrop\n └── Select.Positioner\n └── Select.Popup\n ├── Select.Arrow\n ├── Select.ScrollUpArrow\n ├── Select.List\n │ ├── Select.Group\n │ │ ├── Select.GroupLabel\n │ │ └── Select.Item\n │ │ ├── Select.ItemText\n │ │ └── Select.ItemIndicator\n │ └── Select.Separator\n └── Select.ScrollDownArrow\n```\n\n| Part | Purpose |\n| ---------------------------------- | ----------------------------------------------------------------------------- |\n| `Root` | Owns selection, open state, generic values, and native form integration. |\n| `Label` | Associates a visible label with the trigger. |\n| `Trigger` | Opens the list and contains the displayed value. |\n| `Value` | Renders the selected label or a placeholder. |\n| `Icon` | Renders a default chevron or custom children in the trigger. |\n| `Portal` | Moves popup content to the theme's portal container or an explicit container. |\n| `Backdrop` | Provides an optional backdrop while the popup is open. |\n| `Positioner` | Owns anchor geometry, placement, offsets, and collision behavior. |\n| `Popup` | Renders the popup surface without adding a portal or positioner. |\n| `List` | Provides a separate scrolling container for options. |\n| `Item` | Provides selection behavior for one option. |\n| `ItemText` | Identifies the option label used for typeahead and selected-value alignment. |\n| `ItemIndicator` | Renders the selected option's default checkmark or custom children. |\n| `Arrow` | Positions an optional arrow against the popup anchor. |\n| `ScrollUpArrow`, `ScrollDownArrow` | Scroll a long list when hovered. |\n| `Group`, `GroupLabel` | Group related options under a label. |\n| `Separator` | Separates groups visually. |\n\n`Portal`, `List`, `Backdrop`, arrows, and indicators are optional. Use `Positioner` around `Popup` for positioning, including when you render the popup inline without a portal.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same priority in React state. The callback receives the next value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PrioritySelect = () => {\n const [priority, setPriority] = useState<string | null>('normal');\n\n return (\n <Select.Root\n name=\"priority\"\n value={priority}\n onValueChange={setPriority}\n items={PRIORITIES}\n >\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value placeholder=\"Choose a priority\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\n## Multiple selection\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst LANGUAGES = [\n { value: 'en', label: 'English' },\n { value: 'fr', label: 'French' },\n { value: 'es', label: 'Spanish' },\n];\n\nexport const LanguageSelect = () => {\n const [languages, setLanguages] = useState<string[]>(['en']);\n\n return (\n <Select.Root\n multiple\n value={languages}\n onValueChange={setLanguages}\n items={LANGUAGES}\n >\n <Select.Trigger aria-label=\"Languages\">\n <Select.Value placeholder=\"Choose languages\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {LANGUAGES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\nWith `multiple`, the value is an array. Use `defaultValue={['en']}` instead of `value` and `onValueChange` for an uncontrolled multiple selection. The generic root types represent the option value and whether multiple selection is enabled.\n\n## Open state\n\nSelection and popup visibility are independent. The examples above leave popup visibility uncontrolled. Selecting a single value closes the popup; multiple selection keeps it open. Use `defaultOpen` to set its initial visibility; it defaults to `false`.\n\nPass `open` and update it with `onOpenChange` to control visibility. This example controls the popup while leaving the selected priority uncontrolled.\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PrioritySelect = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Select.Root\n name=\"priority\"\n defaultValue=\"normal\"\n items={PRIORITIES}\n open={open}\n onOpenChange={setOpen}\n >\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value placeholder=\"Choose a priority\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\n## Compose with a field\n\nWrap the select in `Field.Root` to associate its trigger with a visible label and helper text. The field handles labeling and validation; the select keeps its own selection and popup state.\n\n```tsx\nimport { Field, Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PriorityField = () => (\n <Field.Root name=\"priority\">\n <Field.Label>Priority</Field.Label>\n <Select.Root name=\"priority\" defaultValue=\"normal\" items={PRIORITIES}>\n <Select.Trigger>\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n <Field.Description>\n Choose how soon this record needs attention.\n </Field.Description>\n </Field.Root>\n);\n```\n\n## Item composition\n\nCompose arbitrary content inside `Item`. Put the searchable label in `ItemText`; additional content does not become its typeahead label. Provide children to `Icon` or `ItemIndicator` to replace their default icons, or omit those parts altogether.\n\n```tsx\nimport { Select } from 'twenty-ui/primitives/input';\n\nexport const PrioritySelect = () => (\n <Select.Root defaultValue=\"high\" items={{ high: 'High' }}>\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n <Select.Item value=\"high\">\n <Select.ItemText>High</Select.ItemText>\n <span>Needs attention today</span>\n <Select.ItemIndicator />\n </Select.Item>\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n);\n```\n\nAll parts that render elements accept native attributes, refs, and Base UI's `render`, `className`, and `style` composition APIs. For example, use `render={<Button />}` on `Trigger` to compose it with a Twenty UI button. For a non-button render element, also set `nativeButton={false}`.\n\n## Placement\n\nSet `size=\"sm\"` or `size=\"md\"` on `Trigger`. Placement belongs on `Positioner`; portal destination belongs on `Portal`.\n\n`Positioner` preserves Base UI's defaults: `side=\"bottom\"`, `align=\"center\"`, `sideOffset={0}`, and `alignItemWithTrigger={true}`. Selected-item alignment applies to pointer input when there is enough space. Set `alignItemWithTrigger={false}` to use anchored positioning consistently. The examples above choose `align=\"start\"` and `sideOffset={8}` explicitly.\n\n```tsx\nimport { useRef, useState } from 'react';\nimport { Button, Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PositionedPrioritySelect = () => {\n const anchorRef = useRef<HTMLButtonElement>(null);\n const boundaryRef = useRef<HTMLDivElement>(null);\n const [portalContainer, setPortalContainer] = useState<HTMLDivElement | null>(\n null,\n );\n\n return (\n <div ref={boundaryRef}>\n <Button ref={anchorRef}>Position anchor</Button>\n <Select.Root defaultValue=\"normal\" items={PRIORITIES}>\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal container={portalContainer}>\n <Select.Positioner\n anchor={anchorRef}\n positionMethod=\"fixed\"\n side=\"inline-end\"\n align=\"start\"\n alignItemWithTrigger={false}\n sideOffset={({ anchor }) => anchor.width / 4}\n alignOffset={4}\n collisionBoundary={boundaryRef.current ?? undefined}\n collisionPadding={12}\n collisionAvoidance={{ side: 'flip', align: 'shift' }}\n sticky\n >\n <Select.Popup>\n <Select.Arrow />\n <Select.List>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.List>\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n <div ref={setPortalContainer} />\n </div>\n );\n};\n```\n\n`Positioner` also supports virtual anchors, offset functions, `arrowPadding`, and `disableAnchorTracking`. `Portal` uses the [theme's portal container](/ui/theming#scope-an-override) unless you provide `container`. An explicit `container={null}` waits until that container is available.\n\n<StoryEmbed\n storyId=\"ui-input-select-portals--positioning-documentation\"\n title=\"Select with a custom anchor and scrollable list\"\n height={480}\n/>\n\n## Native forms and callback details\n\nSet `name` on `Root` to include the selected value in `FormData`. Multiple selection submits one entry per selected value. `form` associates the hidden input with an external form, and `inputRef` gives access to that input. `required`, `disabled`, and `autoComplete` retain Base UI's native form behavior.\n\n`onValueChange` and `onOpenChange` receive the next state and upstream event details, including `reason`, the native `event`, `cancel()`, and `allowPropagation()`. Calling `cancel()` prevents the corresponding internal state change. Controlled roots still require you to update `value` or `open`.\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\ntype PrioritySelectProps = { canSetHighPriority: boolean };\n\nexport const PrioritySelect = ({ canSetHighPriority }: PrioritySelectProps) => {\n const [priority, setPriority] = useState<string | null>('normal');\n\n return (\n <Select.Root\n items={PRIORITIES}\n value={priority}\n onValueChange={(nextPriority, details) => {\n if (nextPriority === 'high' && !canSetHighPriority) {\n details.cancel();\n return;\n }\n setPriority(nextPriority);\n }}\n >\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\nThe generic root types represent the option value and whether multiple selection is enabled. Object values support `itemToStringLabel`, `itemToStringValue`, and `isItemEqualToValue`. Use `null` for an empty single selection and an empty array for an empty multiple selection.\n\n## Keyboard\n\nKeyboard users can open the list from the trigger, navigate options with arrow keys, and type to find an option. Home and End jump to the first and last options. Enter selects an option; Escape dismisses the popup and restores trigger focus. Multiple selection keeps the popup open while options are toggled.\n\nLabel the trigger with `Select.Label`, an accessible name, or [Field](/ui/primitives/input/field). A placeholder alone does not name the control.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<SelectReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Select","entryPoint":"twenty-ui/primitives/input","slug":"input/select","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<SelectRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the select after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the select completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the select imperatively when called."},{"name":"autoComplete","type":"string","required":false,"defaultValue":null,"description":"Provides a hint to the browser for autofill."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Select parts sharing selection, open state and accessible relationships. Root renders no DOM node."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the select popup is initially open.\n\nTo render a controlled select popup, use the `open` prop instead."},{"name":"defaultValue","type":"SelectInputValue<Value, Multiple> | null","required":false,"defaultValue":null,"description":"The uncontrolled value of the select when it's initially rendered.\n\nTo render a controlled select, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the select is rendered outside the form."},{"name":"highlightItemOnHover","type":"boolean","required":false,"defaultValue":"true","description":"Whether moving the pointer over items should highlight them.\nDisabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the Select."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the native hidden input used for form submission."},{"name":"isItemEqualToValue","type":"((itemValue: Value, value: Value) => boolean)","required":false,"defaultValue":null,"description":"Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially.\nDefaults to `Object.is` comparison."},{"name":"items","type":"Record<string, ReactNode> | readonly { label: ReactNode; value: any; }[] | readonly Group<any>[]","required":false,"defaultValue":null,"description":"Data structure of the items rendered in the select popup.\nWhen specified, `<Select.Value>` renders the label of the selected item instead of the raw value."},{"name":"itemToStringLabel","type":"((itemValue: Value) => string)","required":false,"defaultValue":null,"description":"When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for display in the trigger.\nIf the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop."},{"name":"itemToStringValue","type":"((itemValue: Value) => string)","required":false,"defaultValue":null,"description":"When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for form submission.\nIf the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop."},{"name":"modal","type":"boolean","required":false,"defaultValue":"true","description":"Determines if the select enters a modal state when open.\n- `true`: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n\nOn touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior."},{"name":"multiple","type":"boolean","required":false,"defaultValue":"false","description":"Whether multiple items can be selected."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the select popup is opened or closed."},{"name":"onValueChange","type":"((value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested generic value and unchanged Base UI event details, including reason, event and cancel(). Multiple selection receives an array; a cleared single value is null."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the select popup is currently open."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to choose a different option from the select popup."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"value","type":"SelectInputValue<Value, Multiple> | null","required":false,"defaultValue":null,"description":"The value of the select. Use when controlled."}]},{"name":"Label","props":[{"name":"className","type":"string | ((state: FieldRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Trigger","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Trigger content rendered as supplied. Compose Value and Icon explicitly."},{"name":"className","type":"string | ((state: SelectTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the component should ignore user interaction."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the rendered trigger element, a button by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the trigger. Defaults to md."},{"name":"style","type":"CSSProperties | ((state: SelectTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Value","props":[{"name":"children","type":"ReactNode | ((value: any) => ReactNode)","required":false,"defaultValue":null,"description":"Accepts a function that returns a `ReactNode` to format the selected value.\nTreat the value as read-only: in `multiple` mode it may be a shared frozen array\nwhen nothing is selected."},{"name":"className","type":"string | ((state: SelectValueState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"placeholder","type":"ReactNode","required":false,"defaultValue":null,"description":"The placeholder value to display when no value is selected.\nThis is overridden by `children` if specified, or by a null item's label in `items`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectValueState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectValueState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Icon","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":"<IconChevronDown />","description":"Trigger icon content. Defaults to the Twenty chevron; explicit children replace it."},{"name":"className","type":"string | ((state: SelectIconState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectIconState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectIconState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: SelectPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Defaults to the current theme container, then the document body. Explicit null waits for a container before mounting."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div. Native props and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: SelectBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"How to align the popup relative to the specified side."},{"name":"alignItemWithTrigger","type":"boolean","required":false,"defaultValue":"true","description":"Uses the upstream selected-item alignment by default. Set false to use side, align and offsets without overlapping the trigger."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: SelectPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div. Native props, styles and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Distance between the anchor and the popup in pixels.\nAlso accepts a function that returns the distance to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: SelectPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Popup content rendered as supplied. Compose inside Positioner and choose Portal separately."},{"name":"className","type":"string | ((state: SelectPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the select popup is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div. Native props, styles and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"List","props":[{"name":"className","type":"string | ((state: SelectListState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectListState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectListState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Item","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Option content rendered as supplied. Compose ItemText and an optional ItemIndicator explicitly."},{"name":"className","type":"string | ((state: SelectItemState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Specifies the text label to use when the item is matched during keyboard text navigation.\n\nDefaults to the item text content if not provided."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"ref","type":"Ref<HTMLElement>","required":false,"defaultValue":null,"description":"Ref to the rendered option element. Native props and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectItemState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":false,"defaultValue":"null","description":"A unique value that identifies this select item."}]},{"name":"ItemIndicator","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":"<IconCheck className={listItemStyles.checkIndicator} />","description":"Selected indicator content. Defaults to the Twenty check icon; explicit children replace it."},{"name":"className","type":"string | ((state: SelectItemIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":null,"description":"Whether to keep the HTML element in the DOM when the item is not selected."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectItemIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"ItemText","props":[{"name":"className","type":"string | ((state: SelectItemTextState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemTextState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectItemTextState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: SelectArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"ScrollDownArrow","props":[{"name":"className","type":"string | ((state: SelectScrollDownArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM while the select popup is not scrollable."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollDownArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectScrollDownArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"ScrollUpArrow","props":[{"name":"className","type":"string | ((state: SelectScrollUpArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM while the select popup is not scrollable."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollUpArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectScrollUpArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Group","props":[{"name":"className","type":"string | ((state: SelectGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"GroupLabel","props":[{"name":"className","type":"string | ((state: SelectGroupLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupLabelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectGroupLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Separator","props":[{"name":"className","type":"string | ((state: SelectSeparatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The orientation of the separator."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectSeparatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectSeparatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Slider","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Slider\ndescription: Choose a numeric value or range with draggable, keyboard-accessible thumbs.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SliderReference from '/snippets/ui/generated/input/slider.mdx';\n\n## Overview\n\n`Slider` supports a single number or an array of numbers for a range. Compose its label, track, indicator, and thumbs inside `Root`.\n\n<StoryEmbed\n storyId=\"ui-input-slider--display\"\n title=\"Slider example\"\n height={120}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial volume. The slider owns subsequent changes.\n\n```tsx\nimport { Slider } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const VolumeSlider = () => (\n <Slider.Root name=\"volume\" defaultValue={40} min={0} max={100} step={1}>\n <Text\n render={<div />}\n style={{ display: 'flex', justifyContent: 'space-between' }}\n >\n <Slider.Label>Volume</Slider.Label>\n <Slider.Value />\n </Text>\n <Slider.Control>\n <Slider.Track>\n <Slider.Indicator />\n <Slider.Thumb />\n </Slider.Track>\n </Slider.Control>\n </Slider.Root>\n);\n```\n\n## Visual choices\n\nCompare the accent and success colors at minimum, middle, maximum, and disabled values. The enabled sliders remain interactive.\n\n<StoryEmbed\n storyId=\"ui-input-slider--catalog\"\n title=\"Visual choices for slider\"\n height={340}\n/>\n\n## Anatomy\n\nPut the track and thumbs inside `Slider.Control`, which handles pointer interaction. This tree shows a single-thumb slider.\n\n```text\nSlider.Root\n├── Slider.Label\n├── Slider.Value\n└── Slider.Control\n └── Slider.Track\n ├── Slider.Indicator\n └── Slider.Thumb\n```\n\n| Part | Requirement | Purpose |\n| ----------- | ----------------------------- | --------------------------------------------------------------- |\n| `Root` | Required | Owns the value, bounds, step, and orientation. |\n| `Control` | Required | Handles pointer interaction and positions the thumbs. |\n| `Track` | Required for the styled track | Shows the full value range. |\n| `Thumb` | One per adjustable value | Provides a focusable handle with keyboard interaction. |\n| `Label` | Recommended | Supplies a visible label; every thumb needs an accessible name. |\n| `Value` | Optional | Displays the current numeric value. |\n| `Indicator` | Optional | Shows the selected portion of the track. |\n\nFor a range, add a thumb for each value with its matching `index` and a distinct accessible name. Labels and numeric output stay outside `Control`, so they do not become part of the draggable area.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same volume in React state. The callback receives the next value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { Slider } from 'twenty-ui/primitives/input';\n\nexport const VolumeSlider = () => {\n const [volume, setVolume] = useState(40);\n\n return (\n <Slider.Root\n name=\"volume\"\n value={volume}\n onValueChange={setVolume}\n min={0}\n max={100}\n step={1}\n >\n <Slider.Label>Volume</Slider.Label>\n <Slider.Value />\n <Slider.Control>\n <Slider.Track>\n <Slider.Indicator />\n <Slider.Thumb />\n </Slider.Track>\n </Slider.Control>\n </Slider.Root>\n );\n};\n```\n\nUse `onValueChange` to keep the controlled value current during an interaction. `onValueCommitted` handles the final value when the interaction finishes, for example to save it. Both callbacks are also available in uncontrolled mode without taking ownership of the value.\n\nChange details include the originating `event`, the interaction `reason`, the `activeThumbIndex`, and `cancel()`. Commit details use Base UI's generic event contract and do not include change cancellation. A canceled change does not commit.\n\n## Range\n\n```tsx\nimport { Slider } from 'twenty-ui/primitives/input';\n\nexport const PriceRange = () => (\n <Slider.Root\n defaultValue={[25, 75]}\n min={0}\n max={100}\n minStepsBetweenValues={10}\n >\n <Slider.Label>Price range</Slider.Label>\n <Slider.Value />\n <Slider.Control>\n <Slider.Track>\n <Slider.Indicator />\n <Slider.Thumb index={0} aria-label=\"Minimum price\" />\n <Slider.Thumb index={1} aria-label=\"Maximum price\" />\n </Slider.Track>\n </Slider.Control>\n </Slider.Root>\n);\n```\n\nGive range thumbs distinct accessible names and an `index` corresponding to their value. `minStepsBetweenValues` sets the minimum gap in steps. The root's generic value type is a number or a readonly array of numbers.\n\nTo control a range, store the array in React state and pass it through `value` and `onValueChange`, just as for a single value.\n\n## Keyboard and appearance\n\nArrow keys adjust a focused thumb by a step. Home and End move it toward the bounds while respecting range constraints. `orientation=\"vertical\"` changes the layout and keyboard direction. Use `disabled` on `Root` to prevent changes.\n\nSet `color=\"success\"` for the alternative palette; the default is `accent`.\n\nThe default `thumbAlignment` is `edge`. Pass `center` or `edge-client-only` to override it. Native `className`, `style`, and `render` composition remain available on each part, including state functions.\n\n<Note>\n With `edge` and `edge-client-only` alignment, Base UI 1.8 and 1.9 never\n re-measure a thumb after its `Slider.Control` resizes, and a slider mounted\n while hidden keeps its thumbs hidden once shown\n ([mui/base-ui#5995](https://github.com/mui/base-ui/issues/5995)). React front\n components hit the same issue on their first render. Use\n `thumbAlignment=\"center\"` until a Base UI release includes the fix\n ([mui/base-ui#6000](https://github.com/mui/base-ui/pull/6000)).\n</Note>\n\n## Native integration and types\n\n`Slider.Root` infers a number or a readonly numeric array from `value` or `defaultValue`, retaining that type in both callbacks. `SliderRootProps` accepts both by default; use `SliderRootProps<number>` for single-value helpers or `SliderRootProps<readonly number[]>` for range helpers.\n\nEvery part has an exported props type in `twenty-ui/primitives/input`: `SliderRootProps`, `SliderControlProps`, `SliderTrackProps`, `SliderIndicatorProps`, `SliderThumbProps`, `SliderLabelProps`, and `SliderValueProps`.\n\nRefs target div elements for Root, Control, Track, Indicator, Thumb, and Label, and an output element for Value. A Thumb's ref targets its visible handle; its accessible name and native form value belong to the nested range input. Use `name` and `form` on Root for native submission, with one input per range value.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<SliderReference />\n\n<PageBanner illustration=\"section-apps-config\" />\n","api":{"name":"Slider","entryPoint":"twenty-ui/primitives/input","slug":"input/slider","props":[],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: SliderRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"success\"","required":false,"defaultValue":"accent","description":"Color of the indicator and thumbs."},{"name":"defaultValue","type":"number | readonly number[]","required":false,"defaultValue":null,"description":"The uncontrolled value of the slider when it's initially rendered.\n\nTo render a controlled slider, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the slider should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the slider inputs.\nUseful when the slider is rendered outside the form."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Options to format the value."},{"name":"largeStep","type":"number","required":false,"defaultValue":"10","description":"The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"The locale used by `Intl.NumberFormat` when formatting the value.\nDefaults to the user's runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"The maximum allowed value of the slider.\nShould not be equal to min."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"The minimum allowed value of the slider.\nShould not be equal to max."},{"name":"minStepsBetweenValues","type":"number","required":false,"defaultValue":"0","description":"The minimum steps between values in a range slider."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onValueChange","type":"((value: TValue extends number ? number : TValue, eventDetails: SliderRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Callback function that is fired when the slider's value changed.\nReceives the new value as the first argument; the originating event is\navailable as `eventDetails.event`. The value is also reflected on\n`eventDetails.event.target.value` for form integration.\n\nThe `eventDetails.reason` indicates what triggered the change:\n\n- `'input-change'` when the hidden range input emits a change event (for example, via form integration)\n- `'track-press'` when the control track is pressed\n- `'drag'` while dragging a thumb\n- `'keyboard'` for keyboard input\n- `'none'` when the change is triggered without a specific interaction"},{"name":"onValueCommitted","type":"((value: TValue extends number ? number : TValue, eventDetails: SliderRootCommitEventDetails) => void)","required":false,"defaultValue":null,"description":"Callback function that is fired when a value change is committed.\nDoes not fire if the value did not change, or if the change was canceled.\n**Warning**: This is a generic event, not a change event.\n\nThe `eventDetails.reason` indicates what triggered the commit:\n\n- `'drag'` while dragging a thumb\n- `'track-press'` when the control track is pressed\n- `'keyboard'` for keyboard input\n- `'input-change'` when the hidden range input emits a change event (for example, via form integration)\n- `'none'` when the commit occurs without a specific interaction"},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The component orientation."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"step","type":"number","required":false,"defaultValue":"1","description":"The granularity with which the slider can step through values. (A \"discrete\" slider.)\nThe `min` prop serves as the origin for the valid values.\nWe recommend (max - min) to be evenly divisible by the step."},{"name":"style","type":"CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"thumbAlignment","type":"\"center\" | \"edge-client-only\" | \"edge\"","required":false,"defaultValue":"edge","description":"How the thumb(s) are aligned relative to `Slider.Control` when the value is at `min` or `max`:\n- `center`: The center of the thumb is aligned with the control edge\n- `edge`: The thumb is inset within the control such that its edge is aligned with the control edge\n- `edge-client-only`: Same as `edge` but renders after React hydration on the client, reducing bundle size in return"},{"name":"thumbCollisionBehavior","type":"\"none\" | \"push\" | \"swap\"","required":false,"defaultValue":"push","description":"Controls how thumbs behave when they collide during pointer interactions.\n\n- `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back.\n- `'swap'`: Thumbs swap places when dragged past each other.\n- `'none'`: Thumbs cannot move past each other; excess movement is ignored."},{"name":"value","type":"number | readonly number[]","required":false,"defaultValue":null,"description":"The value of the slider.\nFor range sliders, provide an array with one value per thumb."}]},{"name":"Control","props":[{"name":"className","type":"string | ((state: SliderControlState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderControlState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderControlState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Track","props":[{"name":"className","type":"string | ((state: SliderTrackState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderTrackState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderTrackState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: SliderIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Thumb","props":[{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"A string value forwarded to the [`aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute of the `input`.\nIgnored when `getAriaValueText` is provided."},{"name":"className","type":"string | ((state: SliderThumbState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the thumb should ignore user interaction."},{"name":"getAriaLabel","type":"((index: number) => string) | null","required":false,"defaultValue":null,"description":"A function which returns a string value for the [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute of the `input`."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number, index: number) => string) | null","required":false,"defaultValue":null,"description":"A function which returns a string value for the [`aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute of the `input`.\nThis is important for screen reader users."},{"name":"index","type":"number","required":false,"defaultValue":null,"description":"The index of the thumb which corresponds to the index of its value in the\n`value` or `defaultValue` array.\nThis prop is required to support server-side rendering for range sliders\nwith multiple thumbs."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the nested input element."},{"name":"onBlur","type":"FocusEventHandler<HTMLInputElement>","required":false,"defaultValue":null,"description":"A blur handler forwarded to the `input`."},{"name":"onFocus","type":"FocusEventHandler<HTMLInputElement>","required":false,"defaultValue":null,"description":"A focus handler forwarded to the `input`."},{"name":"onKeyDown","type":"KeyboardEventHandler<HTMLInputElement>","required":false,"defaultValue":null,"description":"A keydown handler forwarded to the `input`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderThumbState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderThumbState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"tabIndex","type":"number","required":false,"defaultValue":null,"description":"Optional tab index attribute forwarded to the `input`."}]},{"name":"Label","props":[{"name":"className","type":"string | ((state: SliderRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Value","props":[{"name":"className","type":"string | ((state: SliderValueState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderValueState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderValueState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Switch","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Switch\ndescription: A labeled on or off control with controlled and uncontrolled state.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SwitchReference from '/snippets/ui/generated/input/switch.mdx';\n\n## Overview\n\nUse `Switch` for an on or off preference. Give the control a visible label or an accessible name.\n\n<StoryEmbed\n storyId=\"ui-input-switch-switch--display\"\n title=\"Switch example\"\n height={90}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultChecked` to set the initial checked state. The switch owns subsequent changes.\n\n```tsx\nimport { useId } from 'react';\nimport { Switch } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const NotificationsPreference = () => {\n const switchId = useId();\n\n return (\n <label\n htmlFor={switchId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Switch id={switchId} name=\"notifications\" />\n <Text render={<span />}>Email notifications</Text>\n </label>\n );\n};\n```\n\n## Visual choices\n\nCompare the two sizes in on, off, disabled, read-only, and focus states. Use the enabled examples to try toggling.\n\n<StoryEmbed\n storyId=\"ui-input-switch-switch--catalog\"\n title=\"Visual choices for switch\"\n height={440}\n/>\n\n## Controlled state\n\nPass `checked` and update it with `onCheckedChange` to own the same preference in React state.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { Switch } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const NotificationsPreference = () => {\n const switchId = useId();\n const [checked, setChecked] = useState(false);\n\n return (\n <label\n htmlFor={switchId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Switch\n id={switchId}\n name=\"notifications\"\n checked={checked}\n onCheckedChange={setChecked}\n />\n <Text render={<span />}>Email notifications</Text>\n </label>\n );\n};\n```\n\n`onCheckedChange` receives the next boolean and event details. The `size` prop accepts `sm` or `md` and defaults to `md`.\n\nFor a consistent full-width row with an icon, description, and switch, use [SettingsRow](/ui/components/settings/settings-row).\n\n## Keyboard and forms\n\nTab moves focus to the switch; Space toggles it. Clicking its associated label also toggles it. Use `disabled` to prevent interaction or `readOnly` to retain a focusable control whose value cannot be changed.\n\nA named switch submits its value when checked. Use `value` to customize that value, and `uncheckedValue` if the form should also submit a value when it is off.\n\n## Parts and custom content\n\n`Switch` assembles the styled root and its default thumb. Use `Switch.Root` with `Switch.Thumb` to own the thumb content. Root owns state and track appearance; Thumb renders the content you supply.\n\n```tsx\nimport { Switch } from 'twenty-ui/primitives/input';\n\nexport const CustomPreference = () => (\n <Switch.Root aria-label=\"Updates\" defaultChecked>\n <Switch.Thumb></Switch.Thumb>\n </Switch.Root>\n);\n```\n\n`SwitchRootProps` and `SwitchThumbProps` are public types exported from `twenty-ui/primitives/input`. Both parts accept native attributes, handlers, refs, `render`, and state-based `className` and `style` callbacks. Root's `ref` targets the visible control; `inputRef` targets the native input. The part ref targets its rendered element. Pass `nativeButton` with `render={<button />}` when replacing Root with a button. Appearance props belong on Root; explicit classes and styles are merged with the defaults.\n\nThumb receives the current checked, disabled, readOnly, required, and Field state. Its position follows the reading direction.\n\n<StoryEmbed\n storyId=\"ui-input-switch-parts--composition\"\n title=\"Switch part composition\"\n height={90}\n/>\n\nThe callable assembly and its `SwitchProps` type remain supported. Replace the assembly with Root and its part when supplying custom thumb content instead of appending another part to the assembly's children.\n\nFor controlled form reset, handle the form's `onReset` and restore `checked` to your initial value. Base UI 1.8 does not restore uncontrolled component state on native form reset. `required`, `form`, `value`, and `uncheckedValue` keep the upstream native input behavior.\n\n## Props\n\nThe reference includes component-specific and inherited Base UI props. Native attributes such as `aria-label` and `data-*` are also accepted.\n\n<SwitchReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"Switch","entryPoint":"twenty-ui/primitives/input","slug":"input/switch","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the switch is currently active.\n\nTo render an uncontrolled switch, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: SwitchRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the switch is initially active.\n\nTo render a controlled switch, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the switch is rendered outside the form."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the hidden input element.\n\nWhen `nativeButton` is `true`, the id is applied to the root element."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the switch is activated or deactivated."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to activate or deactivate the switch."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must activate the switch before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the switch."},{"name":"style","type":"CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is off.\nBy default, unchecked switches do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is on.\nBy default, switch submits the \"on\" value, matching native checkbox behavior."}],"parts":[{"name":"Root","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the switch is currently active.\n\nTo render an uncontrolled switch, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: SwitchRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the switch is initially active.\n\nTo render a controlled switch, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the switch is rendered outside the form."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the hidden input element.\n\nWhen `nativeButton` is `true`, the id is applied to the root element."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the switch is activated or deactivated."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to activate or deactivate the switch."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must activate the switch before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the switch."},{"name":"style","type":"CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is off.\nBy default, unchecked switches do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is on.\nBy default, switch submits the \"on\" value, matching native checkbox behavior."}]},{"name":"Thumb","props":[{"name":"className","type":"string | ((state: SwitchThumbState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchThumbState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SwitchThumbState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Breadcrumb","entryPoint":"twenty-ui/primitives/navigation","content":"---\ntitle: Breadcrumb\ndescription: Show a page's location with a trail of ancestor links.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport BreadcrumbReference from '/snippets/ui/generated/navigation/breadcrumb.mdx';\n\n## Overview\n\n`Breadcrumb` renders an ordered navigation trail. It includes decorative separators, link focus styles, and truncation of the final item's label. Items preserve native anchor behavior and support custom routing through `render`. The trail uses medium font weight consistently, including inside headers with a different weight.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--display\"\n title=\"Breadcrumb example\"\n height={100}\n/>\n\n## Usage\n\nPass items in ancestor-to-current order. The navigation landmark defaults to the accessible name `Breadcrumb`; use `aria-label` to localize it or distinguish multiple trails. The final item defaults to `aria-current=\"page\"`, whether it has a destination or displays plain text.\n\n```tsx\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const CompanyBreadcrumb = () => (\n <Breadcrumb\n aria-label=\"Breadcrumb\"\n links={[\n { children: 'Home', href: '/' },\n { children: 'Companies', href: '/companies' },\n { children: 'Acme' },\n ]}\n />\n);\n```\n\nItems with `href` use native anchors. Items without a destination default to text. The `/` separators are decorative, hidden from assistive technology, and outside the links' accessible names. Links follow the browser's normal Tab and Enter behavior, including modifier clicks and opening in a new tab.\n\n## Native item props\n\nEach item accepts native anchor attributes, event handlers, `className`, `style`, and `ref`. For example, pass `target` and `rel` for a new tab, `download` for a file, or `referrerPolicy` to control the request. The item's ref reaches the rendered DOM element.\n\n```tsx\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const ReferenceBreadcrumb = () => (\n <Breadcrumb\n aria-label=\"Reference location\"\n links={[\n {\n children: 'Documentation',\n href: 'https://docs.twenty.com',\n target: '_blank',\n rel: 'noopener noreferrer',\n referrerPolicy: 'no-referrer',\n },\n { children: 'Companies' },\n ]}\n />\n);\n```\n\n## Current page\n\nAn explicit `aria-current` value on an item takes precedence over its position. Use `aria-current=\"page\"` on another item and `aria-current={false}` on the final item when the current page is earlier in the trail. Other native current-item values, such as `step`, are also preserved. Ensure only the intended item is current.\n\n```tsx\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const CompanyContextBreadcrumb = () => (\n <Breadcrumb\n links={[\n { children: 'Home', href: '/' },\n {\n children: 'Companies',\n href: '/companies',\n 'aria-current': 'page',\n },\n { children: 'Acme', 'aria-current': false },\n ]}\n />\n);\n```\n\n## Router links\n\nUse an item's `render` prop to supply your router's link component, alongside `href`. Pass router-specific destinations, state, and history options directly to that component. `render` accepts either an element or a function receiving the supplied props, including native anchor attributes and its ref.\n\nThe rendered link must forward the supplied props and ref to its anchor. Preserve native link behavior when handling navigation, including modifier clicks and new tabs. See [custom components](/ui/primitives/overview#custom-components) for composition requirements.\n\nThe application chooses destinations and decides when to show a mobile back action. `Breadcrumb` does not infer routes or collapse ancestors into a menu.\n\n## Long labels\n\nThe final item shrinks and truncates with an ellipsis when the container has limited space. Ancestor items retain their width. Plain string labels become the native browser tooltip automatically. Use `title` to override that text or provide a tooltip for rich content. Set `title=\"\"` to suppress the automatic tooltip.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--truncation\"\n title=\"Breadcrumb with a long current page label\"\n height={100}\n/>\n\n## Rich content\n\nAn item's `children` can include text and supporting visual content. Keep the label readable and avoid nesting interactive controls inside a link.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--rich-content\"\n title=\"Breadcrumb with supporting content\"\n height={100}\n/>\n\n## Text direction\n\nThe trail follows the surrounding text direction. Set `dir=\"rtl\"` on `Breadcrumb` or an ancestor for right-to-left content. When other controls need matching directional keyboard or pointer behavior, also set [DirectionProvider](/ui/primitives/layout/direction-provider) to the same direction.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--rtl\"\n title=\"Breadcrumb in right-to-left content\"\n height={100}\n/>\n\n## Root customization\n\nNative navigation attributes, including accessible names, `className`, `style`, and event handlers, reach the root landmark. The root ref reaches its `nav` element. Root `render` also accepts an element or function; keep the navigation landmark and forward its supplied props and ref.\n\n```tsx\nimport { useRef } from 'react';\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const HeaderBreadcrumb = () => {\n const navigationRef = useRef<HTMLElement>(null);\n const companiesRef = useRef<HTMLAnchorElement>(null);\n\n return (\n <Breadcrumb\n aria-label=\"Company location\"\n ref={navigationRef}\n render={<nav data-location=\"header\" />}\n links={[\n {\n children: 'Companies',\n href: '/companies',\n ref: companiesRef,\n render: (props) => (\n <a {...props} data-route={props.href}>\n {props.children}\n </a>\n ),\n },\n { children: 'Acme' },\n ]}\n />\n );\n};\n```\n\n## Props\n\n<BreadcrumbReference />\n\n<PageBanner illustration=\"card-page-navigation\" />\n","api":{"name":"Breadcrumb","entryPoint":"twenty-ui/primitives/navigation","slug":"navigation/breadcrumb","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible navigation name. Defaults to Breadcrumb; supply a localized name or use aria-labelledby."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged onto the root navigation element."},{"name":"links","type":"BreadcrumbItem[]","required":true,"defaultValue":null,"description":"Ordered trail items with native anchor attributes, event handlers, ref, children and element or callback render composition. Items with href default to anchors; other items default to text. The final item defaults to aria-current=\"page\". An explicit aria-current value is preserved, including false."},{"name":"ref","type":"Ref<HTMLElement>","required":false,"defaultValue":null,"description":"Ref to the root nav, or the DOM element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Preserve the navigation landmark and forward the supplied props and ref."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root navigation element."}]}},{"name":"ListItem","entryPoint":"twenty-ui/primitives/navigation","content":"---\ntitle: ListItem\ndescription: Compose consistent rows with icons, descriptions, indicators, and actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ListItemReference from '/snippets/ui/generated/navigation/list-item.mdx';\n\n## Overview\n\n`ListItem` supplies the visual layout shared by list and menu rows. It renders a `div` by default for passive content. Use [ListItemButton](/ui/components/navigation/list-item-button) for ordinary action rows. Compose `ListItem` with an anchor for navigation or with a custom semantic owner when needed. Use [Dropdown](/ui/components/navigation/dropdown) or [Select](/ui/primitives/input/select) when you need a complete popup or selection owner.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem--display\"\n title=\"ListItem example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { IconBell } from 'twenty-ui/icon';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const NotificationRow = () => (\n <ListItem startIcon={<IconBell />}>Notifications</ListItem>\n);\n```\n\n## Anatomy\n\n`ListItem` exposes content slots through props. These slots arrange content inside one row; they are not separately exported components.\n\n```text\nListItem\n├── startIcon\n├── children\n├── description\n├── actions\n└── endIcon\n```\n\n| Slot | Requirement | Purpose |\n| ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------ |\n| `children` | Required for a visible row label | Supplies the main text. |\n| `startIcon`, `endIcon` | Optional | Add icons, avatars, metadata, or independent controls at either end. |\n| `description` | Optional | Adds supporting content inline, below the label, or at the end. |\n| `actions` | Optional | Adds trailing content, such as a separately focusable action. |\n| `indicator`, `shortcut`, `hasSubmenu` | Optional | Configure built-in selection marks, shortcut hints, and the submenu indicator. |\n\nThe row supplies layout. `render` accepts an element or a callback that receives native props and visual state. Spread those props onto the actual root when using a callback. Native attributes, event handlers, `className`, `style`, and `ref` reach that root. For a row with independent action buttons, keep the row itself non-interactive so those buttons remain separate controls.\n\n## Multiline rows\n\nSet `descriptionPlacement=\"below\"` to place supporting content beneath the label. The title keeps its existing truncation behavior, and supporting content wraps with the available width. The default `inline` placement and the `end` placement retain their existing appearance.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem-multiline--display\"\n title=\"Multiline ListItem example\"\n height={150}\n/>\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const PlanningRow = () => (\n <ListItem\n descriptionPlacement=\"below\"\n startIcon={<Avatar name=\"Alex Morgan\" size=\"md\" imageProps={{ alt: '' }} />}\n description=\"Review the proposed timeline and confirm the next steps with the team.\"\n endIcon={\n <Text render={<span />} size=\"sm\" color=\"secondary\">\n 09:48\n </Text>\n }\n >\n Quarterly planning\n </ListItem>\n);\n```\n\nFor shorter previews, pass a [Text](/ui/primitives/typography/text) component with `truncate` or `lineClamp` as `description`. Custom content controls its own layout and accessible labels.\n\n### Independent visual states\n\nAll visual state belongs to the caller. `active` identifies the open or current row without selecting it. `selected` represents selection, and `focused` represents a keyboard navigation highlight without moving DOM focus. `active` applies the current-row background. Set `selectionAppearance=\"accent\"` for an accent fill on selected rows, independently of description placement. The default appearance preserves the existing indicator-based selection styling. `focused` applies the shared highlighted background, including when an owner uses it for pointer highlighting. The focus-visible outline follows actual keyboard focus on the root or its controls.\n\nThese props do not add accessible states. Supply `aria-current`, `aria-selected`, or a control's `checked` state on the appropriate semantic owner. Actual keyboard focus also retains the native focus-visible outline.\n\n### Independent controls\n\nKeep the default `div` root when a row contains a real checkbox or independent action buttons. Use `startIcon` for the checkbox and `actions` for buttons. The decorative `indicator` is unnecessary when a real checkbox already displays selection.\n\n```tsx\nimport { useState } from 'react';\nimport { Button, Checkbox } from 'twenty-ui/primitives/input';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\ntype SelectablePlanningRowProps = {\n active?: boolean;\n disabled?: boolean;\n onOpen: () => void;\n};\n\nexport const SelectablePlanningRow = ({\n active = false,\n disabled = false,\n onOpen,\n}: SelectablePlanningRowProps) => {\n const [selected, setSelected] = useState(false);\n\n return (\n <ListItem\n active={active}\n selected={selected}\n selectionAppearance=\"accent\"\n disabled={disabled}\n descriptionPlacement=\"below\"\n description=\"Review the proposed timeline and confirm the next steps with the team.\"\n startIcon={\n <Checkbox\n aria-label=\"Select quarterly planning\"\n checked={selected}\n onCheckedChange={setSelected}\n disabled={disabled}\n />\n }\n actions={\n <Button variant=\"ghost\" size=\"sm\" onClick={onOpen} disabled={disabled}>\n Open\n </Button>\n }\n >\n Quarterly planning\n </ListItem>\n );\n};\n```\n\nSelection and opening are separate interactions. The application owns event propagation and any row activation or keyboard policy. `ListItem.disabled` changes appearance only; pass `disabled` to each real control to prevent its activation.\n\nThe existing action visibility behavior applies to multiline rows: `actionsVisibility=\"hover\"` reveals actions on hover or focus within the row and keeps them visible on touch devices. Set it to `always` for persistent actions, including while a caller-owned popup is open. At row widths of 480px or less, multiline actions move to their own line and wrap as needed.\n\n## Action row\n\nUse [ListItemButton](/ui/components/navigation/list-item-button) to pair row styling with native button interaction. Pass `disabled` once to control both appearance and activation.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\n\ntype DuplicateActionProps = {\n onDuplicate: () => void;\n disabled?: boolean;\n};\n\nexport const DuplicateAction = ({\n onDuplicate,\n disabled = false,\n}: DuplicateActionProps) => (\n <ListItemButton\n disabled={disabled}\n startIcon={<IconCopy />}\n description=\"Create a copy\"\n onClick={onDuplicate}\n >\n Duplicate\n </ListItemButton>\n);\n```\n\nA custom button owner can still compose `ListItem` through `render`. That owner supplies native focus, Enter and Space activation, and disabled behavior. `ListItem.disabled` supplies only the matching visual style. `shortcut` displays hints; your application registers the shortcuts.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem--button-owner\"\n title=\"Custom button composition\"\n height={100}\n/>\n\n## Navigation and explicit links\n\nPass an anchor through `render` when the entire row navigates. Put anchor attributes, including `href`, `target`, and `rel`, on that element.\n\n```tsx\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const DocumentationLink = () => (\n <ListItem render={<a href=\"https://twenty.com/developers\" />}>\n Typography documentation\n </ListItem>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem--link-owner\"\n title=\"Link row\"\n height={100}\n/>\n\nString labels stay text, including URL-shaped strings. ListItem does not create links. To link part of a non-interactive row, supply an anchor as caller-owned content. Keep that row as a `div` to avoid nested links or buttons. String labels retain their truncation and overflow tooltip; custom content can use [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip) with an explicit rendered anchor.\n\nLinks do not have a native `disabled` attribute. If a destination is unavailable, the link owner must supply the appropriate semantics, tab order, and navigation policy. Styling it with `ListItem.disabled` alone does not prevent navigation.\n\n## Popup item owner\n\nUse `Dropdown.ActionItem` or `Dropdown.OptionItem` inside their popup owner. These parts already compose the ListItem layout and expose its visual slots. The popup owner supplies roles, focus, keyboard navigation, activation, and disabled behavior.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\ntype RecordActionsProps = { onDuplicate: () => void };\n\nexport const RecordActions = ({ onDuplicate }: RecordActionsProps) => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Record actions</Button>} />\n <Dropdown.Content>\n <Dropdown.ActionItem onClick={onDuplicate}>\n Duplicate record\n </Dropdown.ActionItem>\n <Dropdown.ActionItem disabled>Unavailable action</Dropdown.ActionItem>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--display\"\n title=\"Dropdown item owner\"\n height={420}\n/>\n\n## Native event policy\n\nListItem forwards native event objects and handlers. Clicks bubble normally, including clicks on trailing action controls. Put any intentional boundary on the interactive owner or caller's handler.\n\n```tsx\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\ntype OpenRecordProps = { onOpen: () => void };\n\nexport const OpenRecord = ({ onOpen }: OpenRecordProps) => (\n <ListItem\n render={<button type=\"button\" />}\n onClick={(event) => {\n event.stopPropagation();\n onOpen();\n }}\n >\n Open record\n </ListItem>\n);\n```\n\nThe caller also owns any `preventDefault()` policy, such as preventing a link's navigation. Passing `onClick` does not add a role, make a `div` keyboard-operable, or change propagation.\n\n## Application-owned drag and editor navigation\n\nCompose reorderable rows with `ListItem` inside your application's drag host. Put the host's drag attributes and listeners on its handle, and pass the handle or grip through `startIcon`. Keep independent visibility, edit and delete controls in `actions`. The drag host owns pointer and keyboard reordering, disabled dragging and accessible handle labels.\n\nFor editor suggestions, keep the editor's existing listbox and active option owner. Render each `ListItem` with `role=\"option\"` and `aria-selected`, and use `focused` for the active row's appearance. The editor owns arrow navigation and Enter activation while focus stays in the editing surface. Prevent pointer-down focus changes when the editor requires them, and handle pointer selection in the application's row handler.\n\nFor suggestions in a Dropdown page, use `Dropdown.OptionItem` or `Dropdown.ActionItem` so that page owns navigation and activation. Do not add a second Enter or Space handler to an owner that already activates from the keyboard.\n\n## Settings row\n\nUse [SettingsRow](/ui/components/settings/settings-row) for a labeled switch row. It composes `ListItem` and `Switch`, manages their accessible association, and uses the switch’s disabled state for the row’s appearance.\n\n## Selection indicator\n\n```tsx\nimport { useState } from 'react';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const ShowArchivedToggle = () => {\n const [selected, setSelected] = useState(false);\n\n return (\n <ListItem\n render={<button type=\"button\" aria-pressed={selected} />}\n selected={selected}\n indicator=\"check\"\n onClick={() => setSelected(!selected)}\n >\n Show archived records\n </ListItem>\n );\n};\n```\n\n`active`, `selected`, `focused`, and `disabled` independently control row styling. They do not register actions, move DOM focus, add accessible roles or states, or suppress events. The `check` and `checkbox` indicators are decorative; use a real [Checkbox](/ui/primitives/input/checkbox) for a form control. Set `aria-pressed`, `aria-selected`, or other state semantics on the owner that needs them.\n\n## Picker rows\n\nSelection belongs to the parent. `ListItem` has no uncontrolled selection state: pass `selected` and update it from `onClick`. Use `indicator=\"check\"` for a single choice and `indicator=\"checkbox\"` for multiple choices. Both indicators are decorative; the interactive owner handles activation.\n\nIn an existing listbox, pass `role=\"option\"` and `aria-selected`, and keep focus and arrow-key handling in the listbox. For a complete selection widget, use [Select](/ui/primitives/input/select). Standalone selection buttons can use `aria-pressed`, as in these examples.\n\n### Single selection\n\nPlace an [Avatar](/ui/primitives/data-display/avatar) in `startIcon` to identify a record. Use `description` for supporting text, and `descriptionPlacement=\"end\"` for a trailing value.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem-picker--single-selection\"\n title=\"Single selection rows\"\n height={170}\n/>\n\n```tsx\nimport { useState } from 'react';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const AssigneeButtons = () => {\n const [assignee, setAssignee] = useState<string | null>(null);\n\n return (\n <div role=\"group\" aria-label=\"Assignee\">\n {['Alex Morgan', 'Sam Taylor'].map((name) => (\n <ListItem\n key={name}\n render={<button type=\"button\" />}\n aria-pressed={assignee === name}\n selected={assignee === name}\n indicator=\"check\"\n startIcon={<Avatar name={name} size=\"md\" imageProps={{ alt: '' }} />}\n onClick={() => setAssignee(name)}\n >\n {name}\n </ListItem>\n ))}\n </div>\n );\n};\n```\n\n### Multiple selection\n\nCompose [Tag](/ui/primitives/data-display/tag) as the row content for tagged values, or put [ColorSample](/ui/primitives/data-display/color-sample) in `startIcon` for a color choice. A row can also contain plain text or an avatar.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem-picker--multiple-selection\"\n title=\"Multiple selection rows\"\n height={170}\n/>\n\n```tsx\nimport { useState } from 'react';\nimport { Tag } from 'twenty-ui/primitives/data-display';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const TeammateButtons = () => {\n const [teammates, setTeammates] = useState<string[]>([]);\n\n const toggleTeammate = (name: string) => {\n setTeammates((current) =>\n current.includes(name)\n ? current.filter((teammate) => teammate !== name)\n : [...current, name],\n );\n };\n\n return (\n <div role=\"group\" aria-label=\"Teammates\">\n {['Alex Morgan', 'Sam Taylor'].map((name) => (\n <ListItem\n key={name}\n render={<button type=\"button\" />}\n aria-pressed={teammates.includes(name)}\n selected={teammates.includes(name)}\n indicator=\"checkbox\"\n onClick={() => toggleTeammate(name)}\n >\n <Tag color=\"blue\">{name}</Tag>\n </ListItem>\n ))}\n </div>\n );\n};\n```\n\nThe checkbox indicator is not a form control and does not submit a value. Use [Checkbox](/ui/primitives/input/checkbox) when you need form participation. Set native `disabled` on the rendered button to prevent activation and remove it from the tab order. Also pass `ListItem.disabled` for its visual appearance.\n\n## Slots\n\nUse `startIcon` and `endIcon` for icons or caller-owned content, `description` for supporting text, `actions` for trailing content, and `hasSubmenu` for a submenu indicator. `descriptionPlacement` accepts `inline`, `end`, or `below`. `color=\"danger\"` styles a destructive action. Avoid nesting interactive controls inside a row rendered as a button.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\ntype ContactRowProps = { onOpen: () => void };\n\nexport const ContactRow = ({ onOpen }: ContactRowProps) => (\n <ListItem\n description=\"Account owner\"\n actions={\n <Button\n type=\"button\"\n aria-label=\"Open Alex Morgan's profile\"\n variant=\"ghost\"\n size=\"sm\"\n onClick={onOpen}\n >\n Open\n </Button>\n }\n >\n Alex Morgan\n </ListItem>\n);\n```\n\n## Labels\n\nUse `shortcutJoinLabel` to customize the text between sequential shortcut steps. It defaults to `then`; an empty string removes the join text. The same prop is available on `Dropdown` item parts.\n\n## Props\n\nThe reference is generated from the public component types. Native `div` attributes and handlers are accepted, including accessible names and native events. Put button- or anchor-specific attributes on the element supplied through `render`. Both `ref` and the rendered element's ref target the actual DOM root.\n\n<ListItemReference />\n\nPass `shortcut={['Mod', 'Enter']}` for simultaneous keys or `shortcut={[['G'], ['P']]}` for successive presses. See [Shortcut](/ui/primitives/typography/shortcut) for nested combinations and the shared string formatter.\n\n<PageBanner illustration=\"section-apps-data\" />\n","api":{"name":"ListItem","entryPoint":"twenty-ui/primitives/navigation","slug":"navigation/list-item","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Trailing content, such as buttons, rendered after the content."},{"name":"actionsPlacement","type":"\"auto\" | \"end\"","required":false,"defaultValue":"auto","description":"Keeps actions beside the content at every width when set to `end`. The default `auto` preserves responsive wrapping. Hidden end actions do not reserve width on devices without touch."},{"name":"actionsVisibility","type":"\"always\" | \"hover\"","required":false,"defaultValue":"hover","description":"When trailing actions are visible: on hover and focus, or always."},{"name":"active","type":"boolean","required":false,"defaultValue":"false","description":"Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":"neutral","description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":"inline","description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Applies disabled styling only. Set native disabled behavior and accessible semantics on the button, link, or popup item owner."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focused","type":"boolean","required":false,"defaultValue":"false","description":"Applies highlighted styling without moving DOM focus or handling keyboard navigation."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":"false","description":"Shows a chevron indicating that the item opens a submenu."},{"name":"indicator","type":"\"check\" | \"checkbox\" | \"none\"","required":false,"defaultValue":"none","description":"Selection indicator: a check icon after the content or a checkbox before\nit."},{"name":"ref","type":"Ref<HTMLElement>","required":false,"defaultValue":null,"description":"Ref to the actual DOM root, including a composed native button or link."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ListItemState>","required":false,"defaultValue":null,"description":"Composes the row with an element or render callback. The owner supplies interaction semantics, native attributes, and behavior."},{"name":"selected","type":"boolean","required":false,"defaultValue":"false","description":"Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner."},{"name":"selectionAppearance","type":"\"accent\" | \"default\"","required":false,"defaultValue":"default","description":"Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`; pass an empty string to omit it."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."}]}},{"name":"Tabs","entryPoint":"twenty-ui/primitives/navigation","content":"---\ntitle: Tabs\ndescription: Switch between related panels with accessible tab navigation.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TabsReference from '/snippets/ui/generated/navigation/tabs.mdx';\n\n## Overview\n\n`Tabs` connects each tab to a related content panel using a shared `value`. Keep values unique within a root. Use [TabButton](/ui/components/navigation/tab-button) for route links and adjacent actions.\n\n<StoryEmbed\n storyId=\"ui-navigation-tabs--display\"\n title=\"Tabs example\"\n height={160}\n/>\n\n## Usage\n\nUse `defaultValue` to set the initial selection. The root owns subsequent changes.\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const RecordTabs = () => (\n <Tabs.Root defaultValue=\"overview\">\n <Tabs.List aria-label=\"Record details\">\n <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n <Tabs.Tab value=\"activity\">Activity</Tabs.Tab>\n <Tabs.Tab value=\"settings\">Settings</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"overview\">Record overview</Tabs.Panel>\n <Tabs.Panel value=\"activity\">Recent activity</Tabs.Panel>\n <Tabs.Panel value=\"settings\">Record settings</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\n`Tabs.Tab` accepts `startIcon`, `endIcon`, `badge`, and a `size` of `compact`, `sm`, or `md` (default `sm`). The remaining props retain the installed Base UI contract. Values are not restricted to strings or numbers. Reference values must use the same identity on their tab, panel, and root. A root value of `null` selects no panel.\n\n### Compact tabs\n\nUse `size=\"compact\"` on each tab for short Input/Output controls inside a card. Compact tabs have a 24px minimum row height, small text, and 4px content padding on each side. The existing `sm` and `md` sizes keep their 40px minimum height. Compact tabs use the same indicator, focus ring, and keyboard activation as the other sizes.\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const ToolCallTabs = () => (\n <Tabs.Root defaultValue=\"output\">\n <Tabs.List aria-label=\"Tool call details\">\n <Tabs.Tab value=\"output\" size=\"compact\">Output</Tabs.Tab>\n <Tabs.Tab value=\"input\" size=\"compact\">Input</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"output\">Tool output</Tabs.Panel>\n <Tabs.Panel value=\"input\">Tool input</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-navigation-tabs--compact\"\n title=\"Compact Input and Output tabs\"\n height={110}\n/>\n\n## Anatomy\n\nPlace tabs and an optional indicator inside `Tabs.List`. Place their panels alongside the list, all within the same `Tabs.Root`.\n\n```text\nTabs.Root\n├── Tabs.List\n│ ├── Tabs.Tab\n│ ├── Tabs.Tab\n│ └── Tabs.Indicator\n├── Tabs.Panel\n└── Tabs.Panel\n```\n\n| Part | Requirement | Purpose |\n| ----------- | -------------------- | --------------------------------------------------------- |\n| `Root` | Required | Owns the selected value and orientation. |\n| `List` | Required | Groups tabs and supplies keyboard focus navigation. |\n| `Tab` | One per panel | Activates the panel with the same `value`. |\n| `Panel` | One per content view | Displays its content when its `value` is active. |\n| `Indicator` | Optional | Shows the position of the active tab with themed styling. |\n\nGive the list an accessible name and match each tab's `value` to its panel's `value`. Base UI supplies the tab and panel IDs, `aria-controls`, and `aria-labelledby` relationships.\n\nWhen you provide a custom `id` on `Tabs.Panel`, set `aria-controls` on the matching `Tabs.Tab` to that same ID. The installed Base UI 1.8.0 implementation requires this explicit relationship. Custom tab IDs are registered correctly for the panel's `aria-labelledby`.\n\nAdd one `Tabs.Indicator` when you want the active underline. `List` does not insert an indicator.\n\n## Controlled state and event details\n\nPass `value` and update it with `onValueChange` to own selection. The callback receives the next value and Base UI event details, including the originating `event`, `reason`, `activationDirection`, and `cancel()`.\n\n```tsx\nimport { useState } from 'react';\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const RecordTabs = () => {\n const [tab, setTab] = useState('overview');\n\n return (\n <Tabs.Root value={tab} onValueChange={setTab}>\n <Tabs.List aria-label=\"Record details\">\n <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n <Tabs.Tab value=\"activity\" badge={3}>\n Activity\n </Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"overview\">Company and contact details.</Tabs.Panel>\n <Tabs.Panel value=\"activity\">Recent calls and emails.</Tabs.Panel>\n </Tabs.Root>\n );\n};\n```\n\nUser activation has reason `none`. In uncontrolled roots, automatic fallback can have reason `initial`, `disabled`, or `missing`. Automatic fallback may select `null` when no enabled tab remains. These automatic changes cannot be canceled. Controlled roots keep selection under the application's ownership.\n\nCancel a user change before updating controlled state, or use the same callback with an uncontrolled root:\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const ProtectedTabs = () => (\n <Tabs.Root\n defaultValue=\"overview\"\n onValueChange={(value, details) => {\n if (value === 'restricted') {\n details.cancel();\n }\n }}\n >\n <Tabs.List aria-label=\"Account sections\">\n <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n <Tabs.Tab value=\"restricted\">Restricted</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"overview\">Account details.</Tabs.Panel>\n <Tabs.Panel value=\"restricted\">Restricted content.</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\n## Keyboard activation, orientation, and direction\n\n`Tabs.List` uses manual activation by default (`activateOnFocus={false}`). Arrow keys move focus; Enter or Space activates the focused tab. Set `activateOnFocus` to select a tab when keyboard focus reaches it. Both policies work with controlled and uncontrolled state.\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const SettingsTabs = () => (\n <Tabs.Root defaultValue=\"profile\" orientation=\"vertical\">\n <Tabs.List aria-label=\"Settings\" activateOnFocus loopFocus={false}>\n <Tabs.Tab value=\"profile\">Profile</Tabs.Tab>\n <Tabs.Tab value=\"billing\" disabled>\n Billing\n </Tabs.Tab>\n <Tabs.Tab value=\"notifications\">Notifications</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"profile\">Profile settings.</Tabs.Panel>\n <Tabs.Panel value=\"billing\">Billing settings.</Tabs.Panel>\n <Tabs.Panel value=\"notifications\">Notification settings.</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\nHorizontal lists use Left and Right; vertical lists use Up and Down. Home and End focus the first and last enabled tabs. Disabled tabs are skipped. `loopFocus` defaults to `true`; set it to `false` to stop at either boundary.\n\nUse [DirectionProvider](/ui/primitives/layout/direction-provider) for RTL keyboard direction and `dir=\"rtl\"` on the root for layout. Set `orientation=\"vertical\"` on `Root` for a vertical list and indicator.\n\n## Panel lifetime\n\nUse `keepMounted` when panel contents must retain their state while inactive. Inactive mounted panels remain hidden and do not occupy layout space.\n\n## Panel layout\n\n`Panel` fills the space left by the list and can shrink below its content on both axes, so it stays within a root of fixed height. To scroll its content, set `overflow: auto` on the panel, or on a child that fills it, such as a `flex: 1` child of a column flex panel.\n\n## Native props, render composition, and refs\n\nAll five parts preserve native props, event handlers, refs, and Base UI `render` composition. Their `className` and `style` can also be functions of the part's state. The default elements are a `div` for Root, List, and Panel, a `button` for Tab, and a `span` for Indicator. Refs point to the actual rendered elements.\n\n```tsx\nimport { useRef } from 'react';\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const ComposedTabs = () => {\n const panelRef = useRef<HTMLElement>(null);\n\n return (\n <Tabs.Root defaultValue=\"overview\" render={<section />}>\n <Tabs.List aria-label=\"Account details\">\n <Tabs.Tab value=\"overview\" nativeButton render={<button />}>\n Overview\n </Tabs.Tab>\n <Tabs.Indicator render={<span data-testid=\"active-indicator\" />} />\n </Tabs.List>\n <Tabs.Panel\n value=\"overview\"\n render={<article />}\n ref={(element) => {\n panelRef.current = element;\n }}\n >\n Account details.\n </Tabs.Panel>\n </Tabs.Root>\n );\n};\n```\n\nKeep `nativeButton` consistent with the element composed for a tab. Use `nativeButton={false}` for a custom interactive element that is not a native button and forwards the supplied props and ref. A route anchor belongs in `TabButton`, where the route owns navigation and `aria-current`.\n\n## Visual emphasis\n\nUse `highlighted` on `Tabs.Tab` to outline its content independently of selection, such as when its settings are open. Selection remains owned by `Tabs.Root`.\n\n## Props\n\nThe generated reference includes the public props for every part. Public part state types and Root change detail/reason types are available from `twenty-ui/primitives/navigation`.\n\n<TabsReference />\n\n## Migration\n\nAdd an explicit `Tabs.Indicator` to lists that should retain the active underline. Remove duplicate indicators from compositions that previously relied on `List` inserting one. Keep route links, create controls, and overflow controls outside `Tabs.List`, whose children select related panels.\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Tabs","entryPoint":"twenty-ui/primitives/navigation","slug":"navigation/tabs","props":[],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: TabsRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"any","required":false,"defaultValue":"0","description":"The default value. Use when the component is not controlled.\nWhen the value is `null`, no Tab will be active."},{"name":"onValueChange","type":"((value: any, eventDetails: TabsRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Callback invoked when new value is being set.\n\nThe event `reason` is `'none'` for user-initiated changes, such as a click\nor keyboard navigation; `'initial'` for the first automatic selection or\nfallback in uncontrolled roots when `defaultValue` is omitted or\n`undefined`, including when the implicit initial value is disabled or\nmissing; `'disabled'` for automatic fallback when the selected tab becomes\ndisabled in uncontrolled roots; or `'missing'` for automatic fallback when\nthe selected tab is removed, or when an explicit `defaultValue` never\nmatches a mounted tab in uncontrolled roots.\n\nFor automatic changes, the selected value can be `null` when no enabled Tab\nis available as a fallback.\n\nAutomatic changes cannot be canceled; calling `eventDetails.cancel()` for\n`'initial'`, `'disabled'`, or `'missing'` has no effect."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The component orientation (layout flow direction)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TabsRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":false,"defaultValue":null,"description":"The value of the currently active `Tab`. Use when the component is controlled.\nWhen the value is `null`, no Tab will be active."}]},{"name":"List","props":[{"name":"activateOnFocus","type":"boolean","required":false,"defaultValue":"false","description":"Whether to automatically change the active tab on arrow key focus.\nOtherwise, tabs will be activated using <kbd>Enter</kbd> or <kbd>Space</kbd> key press."},{"name":"className","type":"string | ((state: TabsListState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"loopFocus","type":"boolean","required":false,"defaultValue":"true","description":"Whether to loop keyboard focus back to the first item\nwhen the end of the list is reached while using the arrow keys."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsListState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TabsListState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Tab","props":[{"name":"badge","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered after the label, such as a count."},{"name":"className","type":"string | ((state: TabsTabState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the Tab is disabled.\n\nIf a first Tab on a `<Tabs.List>` is disabled, it won't initially be selected.\nInstead, the next enabled Tab will be selected.\nHowever, it does not work like this during server-side rendering, as it is not known\nduring pre-rendering which Tabs are disabled.\nTo work around it, ensure that `defaultValue` or `value` on `<Tabs.Root>` is set to an enabled Tab's value."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content after the label and before the badge."},{"name":"highlighted","type":"boolean","required":false,"defaultValue":"false","description":"Emphasizes the tab content without changing selection."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsTabState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"compact\" | \"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual tab size. Compact uses a 24px minimum height, small text, and 4px content padding; sm and md keep a 40px minimum height."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the label."},{"name":"style","type":"CSSProperties | ((state: TabsTabState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":true,"defaultValue":null,"description":"The value of the Tab."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: TabsIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"renderBeforeHydration","type":"boolean","required":false,"defaultValue":"false","description":"Whether to render itself before React hydrates.\nThis minimizes the time that the indicator isn't visible after server-side rendering."},{"name":"style","type":"CSSProperties | ((state: TabsIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Panel","props":[{"name":"className","type":"string | ((state: TabsPanelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM while the panel is hidden."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsPanelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TabsPanelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":true,"defaultValue":null,"description":"The value of the TabPanel. It will be shown when the Tab with the corresponding value is active."}]}]}},{"name":"Card","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Card\ndescription: Group related information inside a bordered surface.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CardReference from '/snippets/ui/generated/surfaces/card.mdx';\n\n## Overview\n\n`Card` groups related information and actions under one named export. Compose `Card.Root`, `Card.Header`, `Card.Content`, and `Card.Footer` to separate a title, body, and supporting actions. The parts do not manage selection, focus, or application state. The application owns the behavior of any controls placed inside them.\n\n<StoryEmbed\n storyId=\"ui-surfaces-card--display\"\n title=\"Card example\"\n height={200}\n/>\n\n## Usage\n\n```tsx\nimport { useId } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Heading, Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportSummary = () => {\n const titleId = useId();\n\n return (\n <Card.Root fullWidth role=\"region\" aria-labelledby={titleId}>\n <Card.Header>\n <Heading id={titleId} level={2}>\n Import summary\n </Heading>\n </Card.Header>\n <Card.Content>\n <Text>24 records are ready to import.</Text>\n </Card.Content>\n <Card.Footer>\n <Button>Review records</Button>\n </Card.Footer>\n </Card.Root>\n );\n};\n```\n\nUse [Heading](/ui/primitives/typography/heading) at the level required by the surrounding page. Put actions in [Button](/ui/primitives/input/button) or a native link so keyboard and assistive-technology users can activate them.\n\n## Anatomy\n\n```text\nCard.Root (outer surface)\n├── Card.Header (optional)\n├── Card.Content (optional, repeatable)\n├── Card.Footer (optional)\n├── Card.Action (optional, inside an action area)\n└── Card.Control (optional, independent control or tooltip target)\n```\n\nImport `Card` from `twenty-ui/primitives/surfaces`. `Card.Root` supplies the outer border and clipping, but creates no sections internally. No part requires another part or a particular section order. The sections also work independently, without `Card.Root` or context.\n\nRoot, Header, Content and Footer render a `div` by default and accept native div attributes, event handlers, `className`, `style`, and a DOM `ref`. Action renders a native button with `type=\"button\"`, and Control renders a span. Use `render` with an element or callback to choose a semantic target. No part infers an element or role from `onClick`.\n\n`CardRootProps`, `CardHeaderProps`, `CardContentProps`, `CardFooterProps`, `CardActionProps`, and `CardControlProps` are exported from `twenty-ui/primitives/surfaces`, `twenty-ui/primitives`, and the root package.\n\n## Appearance and dividers\n\n`Card.Root` has a transparent background by default. `fullWidth` fills its container, and `backgroundColor` changes the outer background. Child sections have their own backgrounds.\n\n`Card.Header` has a primary background, padding, and a bottom border. `Card.Content` has a secondary background and padding; its optional `divider` adds a bottom border. `Card.Footer` has a primary background, padding, and a top border unless `divider={false}`. Avoid adding two borders at the same section boundary.\n\n```tsx\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportSections = () => (\n <Card.Root>\n <Card.Content divider>\n <Text>24 records are ready to import.</Text>\n </Card.Content>\n <Card.Content divider>\n <Text>3 records need review.</Text>\n </Card.Content>\n <Card.Footer divider={false}>\n <Text>Last checked just now.</Text>\n </Card.Footer>\n </Card.Root>\n);\n```\n\n## Interactive composition\n\nChoose a native button for an action or an anchor for navigation through `render`. Supply target-specific attributes such as `type`, `disabled`, `href`, and `target` on that element. The actual owner supplies its keyboard, focus, disabled, and link behavior. Card does not add those behaviors to a display `div`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype ReviewCardProps = {\n disabled?: boolean;\n onReview: () => void;\n onDismiss: () => void;\n};\n\nexport const ReviewCard = ({\n disabled,\n onReview,\n onDismiss,\n}: ReviewCardProps) => (\n <Card.Root>\n <Card.Content\n render={<button type=\"button\" disabled={disabled} />}\n onClick={onReview}\n >\n <Text render={<span />}>Review 24 ready records</Text>\n </Card.Content>\n <Card.Footer>\n <Button onClick={onDismiss}>Dismiss</Button>\n </Card.Footer>\n </Card.Root>\n);\n```\n\nThe action and dismiss button are siblings inside a display card. Do not place another button, link, input, or other interactive control inside a button or link owner. When a button contains Card parts, render those parts as phrasing elements such as `span`.\n\n```tsx\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportLinkCard = () => (\n <Card.Root render={<a href=\"/imports\" />} fullWidth>\n <Card.Content>\n <Text>View imports</Text>\n </Card.Content>\n </Card.Root>\n);\n```\n\nNative button and link owners retain the card layout and get a visible focus outline. Explicit button and link owners highlight on hover. Disabled owners keep their disabled appearance. Custom owners must supply their interaction behavior, including keyboard activation and disabled handling when applicable.\n\n## Stretched actions and independent controls\n\nUse `Card.Action` when one primary action covers a card section that also contains independent controls. Place the action directly inside Card.Root, Card.Header, Card.Content or Card.Footer. That immediate part defines the stretched area. Keep one primary action per area, and keep expanded forms or other independent sections outside it.\n\n`Card.Action` is a native button by default. Give an empty action an accessible name with `aria-label` or `aria-labelledby`, and use `aria-describedby` for supporting text. A native anchor or router link supplied through `render` keeps its own navigation, target, modifier-click and context-menu behavior. Custom owners receive no synthetic button role, keyboard handler or tab stop. Put target-specific native attributes on the rendered element.\n\n`Card.Control` lifts an independent control or tooltip target above the stretched action. Compose its existing element through `render` to keep its layout and attributes. Controls stay siblings of the primary action, rather than children of a button or link. Card does not infer which descendants are interactive and does not forward their clicks to the primary action. Applications own any additional handling needed for raised plain text.\n\n```tsx\nimport { useId } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const CustomerImportActions = () => {\n const titleId = useId();\n\n return (\n <Card.Root>\n <Card.Content>\n <Card.Action\n aria-labelledby={titleId}\n render={<a href=\"/imports/review\" />}\n />\n <Text id={titleId}>Review customer import</Text>\n <Card.Control render={<Button variant=\"ghost\" />}>\n Import options\n </Card.Control>\n </Card.Content>\n </Card.Root>\n );\n};\n```\n\nEnabled action areas use the shared Card hover color, including when an independent control is hovered. A nested action area owns its highlight and does not highlight its ancestors. Native button and link actions show a 2px inset focus outline around the stretched area. A disabled native button is removed from keyboard navigation and its area does not highlight, including a button supplied through `render`. Links and controls associated through labels remain responsible for their own disabled behavior; the Action `disabled` prop also suppresses the shared action-area treatment.\n\nFor a Switch or Radio row, render Action as `<label htmlFor={controlId} />` and give the actual control that ID. Keep its visible label and accessible description associated with the control. The label creates no additional keyboard target or focus ring. Switch and Radio retain their own focus and keyboard behavior. Put a radio option's expanded form in a separate Card.Content so the label covers only its selection header.\n\n<StoryEmbed\n storyId=\"ui-surfaces-card-interactions--stretched-actions\"\n title=\"Stretched actions with independent controls\"\n height={360}\n/>\n\n## Independent parts and custom wrappers\n\nA section can be used without the outer surface. Wrappers can use its exported props type and spread it to preserve native attributes, event handlers, refs, render composition, classes, and styles. With a custom target, put its target-specific ref on the supplied element. Base UI merges that ref with the part ref and composed props.\n\n```tsx\nimport { Card, type CardContentProps } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype SummaryContentProps = CardContentProps;\n\nconst SummaryContent = ({ children, ...props }: SummaryContentProps) => (\n <Card.Content {...props}>{children}</Card.Content>\n);\n\nexport const StandaloneSummary = () => (\n <SummaryContent aria-label=\"Import summary\" style={{ maxWidth: 360 }}>\n <Text>24 records are ready to import.</Text>\n </SummaryContent>\n);\n```\n\n## Migration\n\nReplace the four separate imports with `import { Card } from 'twenty-ui/primitives/surfaces'`. The root package and `twenty-ui/primitives` also export the same `Card` object.\n\n| Previous API | Compound API |\n| ----------------------------- | ---------------------------------- |\n| `Card` as a component | `Card.Root` |\n| `CardHeader` | `Card.Header` |\n| `CardContent` | `Card.Content` |\n| `CardFooter` | `Card.Footer` |\n| `ComponentProps<typeof Card>` | `ComponentProps<typeof Card.Root>` |\n| `styled(Card)` | `styled(Card.Root)` |\n\nApply the same member names to JSX tags, styled wrappers, and prop types. Standalone part exports are removed without compatibility aliases. Layout props, styling defaults, and independent section use remain. Replace `isClickable` and `hasHoverHighlight` with an explicit native owner through `render`. Move action handlers off display-only wrappers, preserve accessible names, and keep nested controls outside the primary action. Use `render={<button type=\"button\" disabled={disabled} />}` for an action and `render={<a href=\"/imports\" />}` for navigation. DOM refs now point to the actual rendered part.\n\n## Props\n\n<CardReference />\n\n<PageBanner illustration=\"section-ui-primitives\" />\n","api":{"name":"Card","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/card","props":[],"parts":[{"name":"Root","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"CSS background color of the outer card. Child sections have their own backgrounds."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Card sections or other content."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Sets the card width to 100% of its container."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."},{"name":"variant","type":"\"compact\" | \"default\"","required":false,"defaultValue":"default","description":"default keeps the standard section appearance. compact uses secondary section backgrounds, 8px header and footer padding, 8px horizontal content padding without vertical padding, and no header divider."}]},{"name":"Action","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional content inside the stretched action. Supply an accessible name for empty actions."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the action class."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables native button owners and suppresses the action hover treatment. Links and associated controls remain responsible for their own disabled behavior."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the default button, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Native element or render callback composed through Base UI useRender. Links retain native navigation and labels activate their associated controls without an additional keyboard target."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered action."}]},{"name":"Control","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Independent controls or tooltip targets lifted above a sibling Card.Action."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the control class."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the default span, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. The supplied control retains its native attributes, events and semantics."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered control wrapper."}]},{"name":"Header","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Header content. Supply a Heading when the title should be a semantic heading."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."}]},{"name":"Content","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content displayed in the padded body."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"divider","type":"boolean","required":false,"defaultValue":null,"description":"Adds a bottom border."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."}]},{"name":"Footer","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Footer content, such as actions or supporting text."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"divider","type":"boolean","required":false,"defaultValue":"true","description":"Shows the top border unless explicitly set to false."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."}]}]}},{"name":"Dialog","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Dialog\ndescription: Present a focused task above the current page.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DialogReference from '/snippets/ui/generated/surfaces/dialog.mdx';\n\n## Overview\n\nUse `Dialog` for forms, details, and other tasks that open above the page. It manages focus, keyboard dismissal, outside clicks, and scrolling. Use [AlertDialog](/ui/primitives/surfaces/alert-dialog) when the user must explicitly respond to a decision.\n\nThis API is for standalone Twenty UI and the Twenty host application. Front components must use the SDK's [`openCommandConfirmationModal`](/developers/extend/apps/layout/front-components#host-communication-api) instead of rendering `Dialog` or `AlertDialog` directly. Native browser dialogs and popovers are also prohibited in the front component renderer.\n\n<StoryEmbed\n storyId=\"ui-surfaces-dialog--display\"\n title=\"Dialog example\"\n height={440}\n/>\n\n## Usage\n\n### Uncontrolled state\n\n`Root` owns visibility by default. Set `defaultOpen` for its initial state. Triggers, close controls, Escape, and outside clicks update that state.\n\n```tsx\nimport { Button, Field, Input } from 'twenty-ui/primitives/input';\nimport { Dialog } from 'twenty-ui/primitives/surfaces';\n\nexport const AccountDialog = () => (\n <Dialog.Root defaultOpen={false}>\n <Dialog.Trigger render={<Button>Edit account</Button>} />\n <Dialog.Portal>\n <Dialog.Backdrop />\n <Dialog.Viewport>\n <Dialog.Popup>\n <Dialog.Header>\n <Dialog.Title>Edit account</Dialog.Title>\n <Dialog.Description>Update the account details.</Dialog.Description>\n </Dialog.Header>\n <Dialog.Body>\n <Field.Root name=\"company\">\n <Field.Label>Company name</Field.Label>\n <Input defaultValue=\"Acme\" />\n </Field.Root>\n </Dialog.Body>\n <Dialog.Footer>\n <Dialog.Close render={<Button variant=\"outline\">Close</Button>} />\n <Dialog.Close render={<Button>Save</Button>} />\n </Dialog.Footer>\n </Dialog.Popup>\n </Dialog.Viewport>\n </Dialog.Portal>\n </Dialog.Root>\n);\n```\n\n## Anatomy\n\n```text\nDialog.Root\n├── Dialog.Trigger\n└── Dialog.Portal\n ├── Dialog.Backdrop\n └── Dialog.Viewport\n └── Dialog.Popup\n ├── Dialog.Header\n │ ├── Dialog.Title\n │ └── Dialog.Description\n ├── Dialog.Body\n └── Dialog.Footer\n └── Dialog.Close\n```\n\n| Part | Native and ref target |\n| -------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| `Root` | Coordinates visibility and modal behavior. Renders no DOM node and accepts no native attributes or DOM ref. |\n| `Trigger` | A button by default. Opens the dialog and supplies a focus restoration target. |\n| `Portal` | The portal div. Owns the destination container and whether closed content stays mounted. |\n| `Backdrop` | The backdrop div beneath the popup. Optional; omit it when no visible backdrop is needed. |\n| `Viewport` | The positioning div around the popup. |\n| `Popup` | The dialog div. Owns content, size, focus targets and dialog semantics. |\n| `Title` | An `h2` by default. Supplies the accessible name. Supply `aria-label` on `Popup` when omitting it. |\n| `Description` | A paragraph by default. Associates supporting text with the dialog. |\n| `Header`, `Body`, `Footer` | Optional divs arranging headings, content and actions. |\n| `Close` | A button by default. Provides a visible close action, including for touch screen readers. |\n\nAssemble `Portal`, `Backdrop`, `Viewport` and `Popup` explicitly. Each DOM part accepts its own native attributes, handlers, `className`, `style`, ref and `render` composition. A ref targets that part's rendered element. `Popup` does not create a portal, backdrop or viewport.\n\n## Controlled state\n\nPass `open` and `onOpenChange` when the application owns visibility. The callback receives the requested state and Base UI event details, including `reason`, `event`, `trigger` and `cancel()`. Update state to accept a change, or call `eventDetails.cancel()` to reject it. `onOpenChangeComplete` runs when the opening or closing animation finishes.\n\n```tsx\nimport { useState } from 'react';\nimport { Button, Field, Input } from 'twenty-ui/primitives/input';\nimport { Dialog } from 'twenty-ui/primitives/surfaces';\n\nexport const AccountDialog = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Dialog.Root open={open} onOpenChange={setOpen}>\n <Dialog.Trigger render={<Button>Edit account</Button>} />\n <Dialog.Portal>\n <Dialog.Backdrop />\n <Dialog.Viewport>\n <Dialog.Popup>\n <Dialog.Header>\n <Dialog.Title>Edit account</Dialog.Title>\n <Dialog.Description>\n Update the account details.\n </Dialog.Description>\n </Dialog.Header>\n <Dialog.Body>\n <Field.Root name=\"company\">\n <Field.Label>Company name</Field.Label>\n <Input defaultValue=\"Acme\" />\n </Field.Root>\n </Dialog.Body>\n <Dialog.Footer>\n <Dialog.Close render={<Button variant=\"outline\">Close</Button>} />\n <Dialog.Close render={<Button>Save</Button>} />\n </Dialog.Footer>\n </Dialog.Popup>\n </Dialog.Viewport>\n </Dialog.Portal>\n </Dialog.Root>\n );\n};\n```\n\nFor an asynchronous form, keep the dialog open while submitting. Close it after success and display failures inside the dialog.\n\n## Composition\n\n`Trigger` and `Close` accept `render` to compose with `Button`, as shown above. Custom wrappers must [forward supplied props and refs](/ui/primitives/overview#custom-components). DOM parts preserve Base UI's state-aware class names, styles and callback `render` contracts. `Header`, `Body` and `Footer` retain their styled layout and native div composition.\n\nNest another `Dialog.Root` inside a popup to open a second dialog. Closing the nested dialog returns focus to its trigger in the parent.\n\nTo open one dialog from triggers outside `Root`, create a handle once with `Dialog.createHandle<TPayload>()` and pass it to `handle` on both `Root` and each `Trigger`. Trigger `payload` values are available in `Root`'s render function. `Dialog.Handle` and the public `DialogHandle` type expose the installed handle contract:\n\n| Member | Purpose |\n| -------------------------- | ----------------------------------------------------- |\n| `open(triggerId)` | Opens with a matching trigger as the active trigger. |\n| `open(null)` | Opens without associating a trigger. |\n| `openWithPayload(payload)` | Opens with a typed payload and no associated trigger. |\n| `close()` | Requests closure. |\n| `isOpen` | Reads whether the associated dialog is open. |\n\nImperative actions take effect only while the associated Root is mounted. Root's `actionsRef` also exposes `close()` and `unmount()` for explicit transition control. To control an external closing animation, call `eventDetails.preventUnmountOnClose()` in `onOpenChange`, then call the `unmount()` action when the animation finishes.\n\n`Title` uses `Heading` and defaults to an `h2` with large type, primary text color, centered alignment, and spacing-4 below it. Use `level` to change the heading level independently of `size`, or `color` to change its text color. Native `className`, `style`, refs, and `render` are forwarded to the heading. Keep a heading element when using `render`. `Description` is centered like `Title`; AlertDialog keeps both left-aligned.\n\n`Popup` has no padding. `Header`, `Body` and `Footer` provide the inset, so content placed directly in `Popup` sits against its edges.\n\n## Focus, scrolling, and dismissal\n\n`Root.modal` controls the interaction boundary:\n\n| Value | Focus | Page scrolling and outside interaction |\n| ---------------- | ------------------------- | -------------------------------------------------------- |\n| `true` (default) | Trapped inside the dialog | Page scrolling and outside interaction are blocked. |\n| `\"trap-focus\"` | Trapped inside the dialog | Page scrolling and outside interaction remain available. |\n| `false` | Can leave the dialog | Page scrolling and outside interaction remain available. |\n\nOmit `Backdrop` when no visible backdrop is needed. For a nonmodal dialog whose viewport should pass pointer events through to the page, use `<Dialog.Viewport data-backdrop-hidden=\"true\">`; Popup remains interactive. Omitting the visual backdrop alone does not change `Root.modal`.\n\nSet `Popup.initialFocus` or `Popup.finalFocus` to a ref or callback to choose focus targets; `false` disables that automatic focus move. Focus callbacks receive the interaction type and retain Base UI's boolean, element, null and undefined return behavior. Closing normally restores focus to the trigger or previously focused element.\n\n`Root.disablePointerDismissal` prevents outside clicks from requesting closure. To prevent Escape dismissal, cancel the `escape-key` change in `onOpenChange`. Always provide a visible way to close a modal dialog.\n\n## Sizes and portals\n\n`Popup.size` accepts `sm`, `compact`, `md`, `lg`, `xl`, and `fullscreen`, and defaults to `md`. Long content scrolls within the popup. Width is constrained to the viewport.\n\nSet `Portal.container` to choose a destination:\n\n| Value | Resolution |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| Omitted or `undefined` | Uses the nearest scoped theme container. Without one, Base UI uses the parent portal or document body. |\n| Element or `ShadowRoot` | Uses that explicit destination instead of the theme scope. |\n| Ref | Base UI resolves its current element. A ref whose current value is null falls back to the parent portal or document body. |\n| `null` | Waits without mounting. Supply a destination in a later render to mount. |\n\n`Portal.keepMounted` retains content and form state while closed. `Viewport` and `Popup` carry the provided text direction into an external container; their explicit `dir` props take precedence. Without a direction provider or explicit `dir`, they inherit from the destination. See [theming](/ui/theming) and [DirectionProvider](/ui/primitives/layout/direction-provider).\n\nCustomize `Backdrop` and `Viewport` through their own props. Their native attributes, handlers, refs and `render` apply to those elements independently of Popup. Backdrop's `forceRender` keeps a nested dialog's backdrop visible when needed. Base UI open and transition state remains available to state-aware styles and render callbacks.\n\n## Migration\n\nWrap existing `Dialog.Popup` content in `Dialog.Portal` and `Dialog.Viewport`, and add a sibling `Dialog.Backdrop` inside Portal. Move `container` and `keepMounted` from Popup to Portal. Move former `backdrop` props onto Backdrop; replace `backdrop={false}` by omitting Backdrop. Move `viewportProps` onto Viewport, retaining `data-backdrop-hidden=\"true\"` when the viewport must pass outside pointer events through. Keep `size`, `initialFocus`, `finalFocus`, native popup attributes and popup refs on Popup. The fused Popup assembly props are removed.\n\nRoot, Trigger, Close, Title, Description, Header, Body, Footer and existing handles retain their roles. Public part props, state, actions and event-detail types are exported from `twenty-ui/primitives/surfaces`.\n\n## Props\n\n<DialogReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Dialog","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/dialog","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<DialogRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the dialog after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the dialog completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the dialog imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"Parts or a render function receiving the active trigger payload. Root renders no DOM node."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the dialog is initially open.\n\nTo render a controlled dialog, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open dialog."},{"name":"disablePointerDismissal","type":"boolean","required":false,"defaultValue":"false","description":"Whether to prevent the dialog from closing on outside presses.\nFor non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it."},{"name":"handle","type":"DialogHandle<Payload>","required":false,"defaultValue":null,"description":"Connects detached triggers and imperative dialog actions."},{"name":"modal","type":"boolean | \"trap-focus\"","required":false,"defaultValue":"true","description":"Determines if the dialog enters a modal state when open.\n- `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n- `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled.\n\nWhen `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so\ntouch screen readers can escape the popup."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested state and Base UI event details, including reason, event, trigger and cancel()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the dialog is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the dialog is currently open."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled dialog.\nThere's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: DialogTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"handle","type":"DialogHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with a dialog.\nCan be created with the Dialog.createHandle() method."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the dialog when it is opened."},{"name":"ref","type":"((((instance: HTMLButtonElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<HTMLButtonElement | null>) & (((instance: HTMLElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<...>)) | null","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: DialogPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Omit to use the nearest theme scope, then the parent portal or document body. Explicit null defers mounting; an element, ShadowRoot or ref keeps Base UI resolution."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the portal and its content mounted while closed."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPortalState>","required":false,"defaultValue":null,"description":"Composes the portal element. Native props and handlers target it."},{"name":"style","type":"CSSProperties | ((state: DialogPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: DialogBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"forceRender","type":"boolean","required":false,"defaultValue":"false","description":"Renders the backdrop even when this dialog is nested."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the backdrop div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Popup and any other content within the positioning viewport."},{"name":"className","type":"string | ((state: DialogViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the viewport div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Dialog content. Compose inside Viewport and Portal; Popup does not create those parts or a Backdrop."},{"name":"className","type":"string | ((state: DialogPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Controls focus restoration on closing. Accepts a boolean, element ref or callback receiving the interaction type."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Controls focus on opening. Accepts a boolean, element ref or callback receiving the interaction type."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>","required":false,"defaultValue":null,"description":"Composes the popup element while retaining native props, handlers, dialog semantics and focus behavior."},{"name":"size","type":"\"compact\" | \"fullscreen\" | \"lg\" | \"md\" | \"sm\" | \"xl\"","required":false,"defaultValue":"md","description":"Width of the dialog, or `fullscreen` to fill the viewport."},{"name":"style","type":"CSSProperties | ((state: DialogPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: DialogTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Theme font color. Defaults to `primary`."},{"name":"level","type":"1 | 2 | 3 | 4 | 5 | 6","required":false,"defaultValue":"2","description":"Semantic heading level, from `h1` through `h6`. Does not change the visual size. Defaults to `2`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"lg","description":"Visual font size, independent of the heading level. Defaults to `lg`."},{"name":"style","type":"CSSProperties | ((state: DialogTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: DialogDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLParagraphElement>","required":false,"defaultValue":null,"description":"Ref to the description paragraph, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"className","type":"string | ((state: DialogCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the close button, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Header","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Body","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Footer","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]}]}},{"name":"AlertDialog","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: AlertDialog\ndescription: Ask for confirmation before an action that needs an explicit decision.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AlertDialogReference from '/snippets/ui/generated/surfaces/alert-dialog.mdx';\n\n## Overview\n\nUse `AlertDialog` for a decision that interrupts the current workflow, such as confirming deletion. It provides `alertdialog` semantics, focus management, and explicit confirmation or cancellation.\n\nThis primitive is for standalone Twenty UI and host-owned interfaces. Front components must request a confirmation through the [SDK host dialog API](/developers/extend/apps/layout/front-components#host-communication-api). Direct `Dialog`, `AlertDialog`, and native browser dialogs are prohibited inside the front component renderer.\n\n<StoryEmbed\n storyId=\"ui-surfaces-alertdialog--display\"\n title=\"AlertDialog example\"\n height={440}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultOpen` to set the initial visibility. The dialog owns subsequent changes from its trigger, close controls, and dismissal interactions.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AlertDialog } from 'twenty-ui/primitives/surfaces';\n\ntype DeleteConfirmationProps = { onDelete: () => void };\n\nexport const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (\n <AlertDialog.Root defaultOpen={false}>\n <AlertDialog.Trigger\n render={<Button variant=\"solid\">Delete record</Button>}\n />\n <AlertDialog.Portal>\n <AlertDialog.Backdrop />\n <AlertDialog.Viewport>\n <AlertDialog.Popup>\n <AlertDialog.Header>\n <AlertDialog.Title>Delete this record?</AlertDialog.Title>\n <AlertDialog.Description>\n This record will be permanently deleted. This action cannot be\n undone.\n </AlertDialog.Description>\n </AlertDialog.Header>\n <AlertDialog.Footer>\n <AlertDialog.Close render={<Button>Cancel</Button>} />\n <AlertDialog.Close\n onClick={onDelete}\n render={<Button color=\"danger\">Delete</Button>}\n />\n </AlertDialog.Footer>\n </AlertDialog.Popup>\n </AlertDialog.Viewport>\n </AlertDialog.Portal>\n </AlertDialog.Root>\n);\n```\n\n`defaultOpen` defaults to `false`, so it can be omitted. This example uses a synchronous confirmation callback and closes after the action runs.\n\n## Anatomy\n\nKeep related parts inside `AlertDialog.Root`, or connect detached triggers through a handle. Compose the portal, backdrop, viewport, and popup separately.\n\n```text\nAlertDialog.Root\n├── AlertDialog.Trigger\n└── AlertDialog.Portal\n ├── AlertDialog.Backdrop\n └── AlertDialog.Viewport\n └── AlertDialog.Popup\n ├── AlertDialog.Header\n │ ├── AlertDialog.Title\n │ └── AlertDialog.Description\n ├── AlertDialog.Body\n └── AlertDialog.Footer\n ├── AlertDialog.Close\n └── Confirmation action\n```\n\n| Part | Requirement | Purpose |\n| -------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |\n| `Root` | Required | Coordinates open state and modal behavior. |\n| `Trigger` | Optional for a programmatically opened dialog | Opens the dialog and provides a return focus target. |\n| `Portal` | Recommended | Moves the overlay to its container and controls mounting. |\n| `Backdrop` | Optional | Visually separates the alert from the surrounding page. |\n| `Viewport` | Recommended | Positions the popup and provides its scrollable surrounding area. |\n| `Popup` | Required | Renders the alert content with focus management. |\n| `Title` | Recommended | Supplies the visible alert name. An accessible name is always required. |\n| `Description` | Recommended for a confirmation | Explains the decision and its consequences. |\n| `Header`, `Body`, `Footer` | Optional layout parts | Arrange headings, additional content, and actions. |\n| `Close` | Recommended for cancellation | Supplies an explicit close action. |\n\nSet `container` and `keepMounted` on `Portal`, backdrop attributes on `Backdrop`, layout attributes on `Viewport`, and `size` and focus props on `Popup`. Each element part accepts its own native attributes, handlers, ref, and `render` composition. `Popup.ref` points to the alert content element. `Title` and `Description` establish the accessible relationships; provide `aria-label` on `Popup` when omitting a title.\n\nThe confirmation action is application content, not an exported part. Use `Close` with a synchronous handler or a `Button` with controlled open state for asynchronous confirmation.\n\n## Controlled state\n\nPass `open` and update it with `onOpenChange` to own the same dialog's visibility in React state. The callback receives the requested boolean and upstream event details, including `reason`, `event`, and `cancel()`. Call `eventDetails.cancel()` to reject a requested change. `onOpenChangeComplete` runs after opening or closing transitions finish.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AlertDialog } from 'twenty-ui/primitives/surfaces';\n\ntype DeleteConfirmationProps = { onDelete: () => void };\n\nexport const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => {\n const [open, setOpen] = useState(false);\n\n return (\n <AlertDialog.Root open={open} onOpenChange={setOpen}>\n <AlertDialog.Trigger\n render={<Button variant=\"solid\">Delete record</Button>}\n />\n <AlertDialog.Portal>\n <AlertDialog.Backdrop />\n <AlertDialog.Viewport>\n <AlertDialog.Popup>\n <AlertDialog.Header>\n <AlertDialog.Title>Delete this record?</AlertDialog.Title>\n <AlertDialog.Description>\n This record will be permanently deleted. This action cannot be\n undone.\n </AlertDialog.Description>\n </AlertDialog.Header>\n <AlertDialog.Footer>\n <AlertDialog.Close render={<Button>Cancel</Button>} />\n <AlertDialog.Close\n onClick={onDelete}\n render={<Button color=\"danger\">Delete</Button>}\n />\n </AlertDialog.Footer>\n </AlertDialog.Popup>\n </AlertDialog.Viewport>\n </AlertDialog.Portal>\n </AlertDialog.Root>\n );\n};\n```\n\nFor asynchronous confirmation, use a `Button` with your action handler instead of `AlertDialog.Close`. Keep `open` true while the action is pending, call `setOpen(false)` after it succeeds, and show an error inside the dialog if it fails.\n\n## Compose with buttons\n\nUse `render` to give the trigger and close controls Twenty UI button styling. The dialog parts supply their interaction handlers and refs to the buttons.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AlertDialog } from 'twenty-ui/primitives/surfaces';\n\ntype DeleteConfirmationProps = { onDelete: () => void };\n\nexport const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (\n <AlertDialog.Root>\n <AlertDialog.Trigger\n render={<Button variant=\"solid\">Delete record</Button>}\n />\n <AlertDialog.Portal>\n <AlertDialog.Backdrop />\n <AlertDialog.Viewport>\n <AlertDialog.Popup>\n <AlertDialog.Header>\n <AlertDialog.Title>Delete this record?</AlertDialog.Title>\n <AlertDialog.Description>\n This record will be permanently deleted. This action cannot be\n undone.\n </AlertDialog.Description>\n </AlertDialog.Header>\n <AlertDialog.Footer>\n <AlertDialog.Close render={<Button>Cancel</Button>} />\n <AlertDialog.Close\n onClick={onDelete}\n render={<Button color=\"danger\">Delete</Button>}\n />\n </AlertDialog.Footer>\n </AlertDialog.Popup>\n </AlertDialog.Viewport>\n </AlertDialog.Portal>\n </AlertDialog.Root>\n);\n```\n\nKeep each action as a single interactive control. If you wrap `Button` in your own component, [forward the supplied props and ref](/ui/primitives/overview#custom-components).\n\n## Detached triggers and imperative actions\n\nCreate a handle once with `AlertDialog.createHandle<Payload>()` and pass it to `handle` on `Root` and each detached `Trigger`. A trigger's typed `payload` is available to the root's child render function. A handle also supports `open(triggerId)`, `openWithPayload(payload)`, `close()`, and the `isOpen` getter while its root is mounted. Pass a matching trigger ID to `open`, or `null` to open without a trigger. Call imperative methods from event handlers or effects.\n\n`Root.actionsRef` exposes `close()` and `unmount()`. For an externally controlled closing animation, call `eventDetails.preventUnmountOnClose()` in `onOpenChange`, then call `actionsRef.current?.unmount()` after the animation finishes. The regular styled parts manage their own transitions without these imperative actions.\n\n## Sizing and portals\n\n`Popup.size` accepts `sm`, `md`, `lg`, `xl`, and `fullscreen`, and defaults to `md`. Size and appearance belong to the AlertDialog surface and do not have to match Dialog presets.\n\n`Portal.container` defaults to the nearest theme's portal container. Without one, Base UI uses its default portal destination, normally `document.body`. An explicit element, shadow root, or ref overrides that destination. An explicit `null` defers mounting until a container is available. Base UI resolves a ref whose `current` is `null` using its default destination; use `container={null}` when mounting must wait.\n\nPortaled content retains the theme context. `Portal` and `Viewport` inherit the provided text direction unless you set `dir` explicitly. Set `Portal.keepMounted` to retain mounted content and form state while closed.\n\n## Focus and dismissal\n\nThe alert traps focus, blocks outside interaction, and locks page scrolling while open. Escape requests closure; clicking outside does not. To prevent Escape dismissal, cancel the `escape-key` change in `onOpenChange`. Always provide a visible Cancel or Close action.\n\nBy default, focus moves to the first tabbable control, or to the popup for a touch opening. Put the least destructive action first, or use `Popup.initialFocus` to select it. Focus returns to the trigger or previously focused element when the alert closes. Use `Popup.finalFocus` when a successful action removes that target. Both focus props accept a boolean, element ref, or interaction-type callback according to the upstream contract.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<AlertDialogReference />\n\n<PageBanner illustration=\"card-page-billing-faq\" />\n","api":{"name":"AlertDialog","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/alert-dialog","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<DialogRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the alert dialog after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the alert dialog completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the alert dialog imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"The content of the dialog.\nThis can be a regular React node or a render function that receives the `payload` of the active trigger."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the dialog is initially open.\n\nTo render a controlled dialog, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open dialog."},{"name":"handle","type":"AlertDialogHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the alert dialog with a trigger.\nIf specified, allows external triggers to control the alert dialog's open state.\nCan be created with the AlertDialog.createHandle() method."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Event handler called when the alert dialog is opened or closed."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the dialog is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the dialog is currently open."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled dialog.\nThere's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: DialogTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"handle","type":"AlertDialogHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with an alert dialog.\nCan be created with the AlertDialog.createHandle() method."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the dialog when it is opened."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: DialogPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Omission uses the theme container or Base UI default; explicit `null` defers mounting. A ref with a null current value uses the Base UI default destination."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps content mounted while the alert is closed."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: DialogBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"forceRender","type":"boolean","required":false,"defaultValue":"false","description":"Whether the backdrop is forced to render even when nested."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"className","type":"string | ((state: DialogViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"className","type":"string | ((state: DialogPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the dialog is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the dialog is opened.\nBy default, focus moves to the first tabbable element inside the popup, except when the dialog\nis opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"fullscreen\" | \"lg\" | \"md\" | \"sm\" | \"xl\"","required":false,"defaultValue":"md","description":"Width of the alert, or `fullscreen` to fill the viewport."},{"name":"style","type":"CSSProperties | ((state: DialogPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: DialogTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: DialogDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"className","type":"string | ((state: DialogCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Header","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Body","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Footer","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]}]}},{"name":"Popover","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Popover\ndescription: Display contextual content anchored to a trigger.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport PopoverReference from '/snippets/ui/generated/surfaces/popover.mdx';\n\n## Overview\n\nUse `Popover` for contextual information or lightweight controls. Compose its portal, positioning wrapper and popup separately. Use [Dropdown](/ui/components/navigation/dropdown) for menus, pickers and panels with higher-level navigation.\n\n<StoryEmbed\n storyId=\"ui-surfaces-popover--display\"\n title=\"Popover example\"\n height={280}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultOpen` to set the initial visibility. The popover owns subsequent changes from its trigger, close controls, and dismissal interactions.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const ContactDetailsPopover = () => (\n <Popover.Root defaultOpen={false}>\n <Popover.Trigger render={<Button>Show details</Button>} />\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup\n style={{ boxSizing: 'border-box', width: 260, padding: 16, gap: 12 }}\n >\n <Popover.Title>Contact details</Popover.Title>\n <Popover.Description>\n Reach Alex at [email protected].\n </Popover.Description>\n <Popover.Close\n style={{ alignSelf: 'flex-end' }}\n render={<Button size=\"sm\">Close</Button>}\n />\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n);\n```\n\n`defaultOpen` defaults to `false`, so it can be omitted. Use `Title` and `Description` to identify the popup. The trigger renders a button by default; `render` lets you supply a compatible element.\n\n## Placement comparison\n\nCompare the supported sides with and without an arrow. These open examples keep each popup beside its trigger for inspection; use the Display example to try opening and dismissing a popover.\n\n<StoryEmbed\n storyId=\"ui-surfaces-popover--catalog\"\n title=\"Placement comparison for popover\"\n height={640}\n/>\n\n## Anatomy\n\nKeep the trigger and popup inside `Popover.Root`. The popup can contain text, form controls, and actions.\n\n```text\nPopover.Root\n├── Popover.Trigger\n└── Popover.Portal\n ├── Popover.Backdrop (optional)\n └── Popover.Positioner\n └── Popover.Popup\n ├── Popover.Arrow (optional)\n └── Popover.Viewport (optional)\n ├── Popover.Title\n ├── Popover.Description\n └── Popover.Close\n```\n\n| Part | Purpose and native target |\n| ------------- | --------------------------------------------------------------------------------- |\n| `Root` | Owns state, triggers and interactions. Renders no DOM element. |\n| `Trigger` | Opens the popup and supplies its default anchor. Targets a button. |\n| `Portal` | Chooses the destination. Native props, handlers, `render` and ref target its div. |\n| `Positioner` | Owns anchors, alignment, offsets and collision handling. Targets its div. |\n| `Popup` | Renders content and manages focus. Targets its div. |\n| `Arrow` | Optional styled arrow inside Popup. Targets its div. |\n| `Backdrop` | Optional upstream backdrop inside Portal. Targets its div. |\n| `Viewport` | Optional transition container for changing content. Targets its div. |\n| `Title` | Supplies a visible accessible name. Targets an h2. |\n| `Description` | Associates explanatory text. Targets a paragraph. |\n| `Close` | Requests closing. Targets a button. |\n\nAll rendered parts support the installed Base UI native attributes, handlers, refs and element/function `render` composition. Custom components must forward the supplied props and ref. Every part has a public `Popover<Part>Props` and `Popover<Part>State` type. `PopoverRootProps` and `PopoverTriggerProps` preserve payload generics. `PopoverHandle`, `PopoverRootActions`, `PopoverRootChangeEventDetails` and `PopoverRootChangeEventReason` are also exported from `twenty-ui/primitives/surfaces`.\n\n## Controlled state\n\nPass `open` and update it with `onOpenChange` to own the same popover's visibility in React state.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const ContactDetailsPopover = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Popover.Root open={open} onOpenChange={setOpen}>\n <Popover.Trigger render={<Button>Show details</Button>} />\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup\n style={{\n boxSizing: 'border-box',\n width: 260,\n padding: 16,\n gap: 12,\n }}\n >\n <Popover.Title>Contact details</Popover.Title>\n <Popover.Description>\n Reach Alex at [email protected].\n </Popover.Description>\n <Popover.Close\n style={{ alignSelf: 'flex-end' }}\n render={<Button size=\"sm\">Close</Button>}\n />\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n );\n};\n```\n\n`onOpenChange` receives the next boolean and event details, including changes requested by the trigger, close controls, Escape, and outside interaction.\n\n## Compose with buttons\n\nPass a Twenty UI `Button` through `render` to use it as the trigger or close control. The popover keeps its open state, keyboard behavior, and focus handling.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const ImportHelp = () => (\n <Popover.Root>\n <Popover.Trigger render={<Button variant=\"outline\">Import help</Button>} />\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup\n style={{ boxSizing: 'border-box', width: 260, padding: 16, gap: 12 }}\n >\n <Popover.Arrow />\n <Popover.Title>Import a CSV file</Popover.Title>\n <Popover.Description>\n Use a header row to identify your columns.\n </Popover.Description>\n <Popover.Close\n style={{ alignSelf: 'flex-end' }}\n render={<Button size=\"sm\">Got it</Button>}\n />\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n);\n```\n\n`render` composes behavior onto the supplied button. Custom wrapper components must [forward the supplied props and ref](/ui/primitives/overview#custom-components) to preserve that behavior.\n\n## Placement and focus\n\n`Positioner` defaults to `side=\"bottom\"`, `align=\"center\"` and `sideOffset={8}`. It accepts the full installed Base UI contract, including element/ref/function/virtual anchors, functional offsets, `positionMethod`, `collisionBoundary`, `collisionPadding`, `collisionAvoidance`, `arrowPadding`, `sticky` and `disableAnchorTracking`. DirectionProvider controls logical positioning and supplies the DOM direction. An explicit `dir` can override the native attribute; use the provider to change logical side placement.\n\n```tsx\nimport { useRef } from 'react';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const AnchoredHelp = () => {\n const anchor = useRef<HTMLDivElement>(null);\n\n return (\n <div ref={anchor}>\n <Popover.Root>\n <Popover.Trigger>Help</Popover.Trigger>\n <Popover.Portal>\n <Popover.Positioner\n anchor={anchor}\n side=\"inline-end\"\n align=\"start\"\n sideOffset={({ anchor }) => anchor.width / 2}\n collisionBoundary=\"clipping-ancestors\"\n collisionAvoidance={{ side: 'flip', align: 'shift' }}\n collisionPadding={8}\n positionMethod=\"fixed\"\n >\n <Popover.Popup aria-label=\"Help\">\n <Popover.Arrow />\n Contextual help\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n </div>\n );\n};\n```\n\nEscape closes the popup and restores focus to its trigger. Outside interaction dismisses it by default. `Popup.initialFocus` and `Popup.finalFocus` accept the upstream focus targets and callbacks. `Root.modal` retains Base UI's nonmodal default, modal and trap-focus modes for standalone usage.\n\n## Portal destinations and theme\n\nSet `container` and `keepMounted` on `Portal`:\n\n| Container | Resolution |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Omitted or `undefined` | Uses the nearest scoped ThemeProvider container. Without one, Base UI uses its parent portal or document body. |\n| `null` | Waits without rendering portal content until the container changes. It does not fall back to the theme or body. |\n| Element, ShadowRoot or ref | Passes the supplied target unchanged to Base UI. An unresolved ref retains Base UI's parent-portal/body fallback; use explicit null when waiting is required. |\n\nThe default scoped destination preserves its CSS tokens and color scheme. An explicit destination inherits CSS from its actual DOM scope. Put it inside the intended theme scope, or supply the theme styles there. ShadowRoot targets need the library's CSS and theme styles in that shadow tree. React theme context and provided text direction remain available across portals. This API does not expand the renderer's permitted portal destinations.\n\n## Detached triggers and payloads\n\n`Popover.createHandle<TPayload>()` connects detached triggers to a root and exposes `open(triggerId)`, `close()` and `isOpen`. `Popover.Handle` is the installed upstream handle constructor. Root's render function receives the active payload. Call imperative actions from event handlers or effects.\n\n```tsx\nimport { useState } from 'react';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const OwnerHelp = () => {\n const [handle] = useState(() => Popover.createHandle<{ name: string }>());\n\n return (\n <>\n <Popover.Trigger handle={handle} id=\"owner\" payload={{ name: 'Alice' }}>\n Owner\n </Popover.Trigger>\n <Popover.Root handle={handle}>\n {({ payload }) => (\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup aria-label=\"Account owner\">\n {payload?.name}\n <Popover.Close>Close</Popover.Close>\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n )}\n </Popover.Root>\n </>\n );\n};\n```\n\n`onOpenChange` preserves `reason`, `event`, `trigger`, `cancel()` and `preventUnmountOnClose()`. Controlled roots retain `triggerId`; uncontrolled roots retain `defaultTriggerId`. `actionsRef` exposes the upstream close/unmount actions.\n\n## Migration\n\nMove `container` and `keepMounted` from Popup to Portal. Move placement, anchor and collision props to Positioner. Replace `Popup.arrow` with an explicit `Popover.Arrow` child. Popup's native props, handlers, focus props and ref continue to target the content element. Dropdown.Content keeps its existing convenient assembly.\n\nInside front components, use nonmodal composition within the existing scoped portal policy. Native browser popovers/dialogs and direct app-owned modality are prohibited; use the SDK host dialog API for dialogs. Renderer portal, geometry, scrolling and dismissal capability work remains separate from this primitive API.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<PopoverReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Popover","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/popover","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<PopoverRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the popover after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the popover completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the popover imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"Parts or a render function receiving the active trigger payload. Root renders no DOM element."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover is initially open.\n\nTo render a controlled popover, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the popover is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open popover."},{"name":"handle","type":"PopoverHandle<Payload>","required":false,"defaultValue":null,"description":"Connects detached triggers and imperative open/close actions."},{"name":"modal","type":"boolean | \"trap-focus\"","required":false,"defaultValue":"false","description":"Determines if the popover enters a modal state when open.\n- `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n- `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.\n\nOn touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.\n\nWhen `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered\ninside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as\nTailwind's `sr-only` utility.\n\nWhen `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch\nscreen readers can escape the popup."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the popover is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popover is currently open."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the popover is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled popover.\nThere's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"handle","type":"PopoverHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with a popover."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the popover when it is opened."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: PopoverPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"When omitted, uses the scoped theme container, then the Base UI parent portal or document body. Explicit null delays rendering until a target is supplied. Explicit elements, ShadowRoots and refs are forwarded unchanged; their DOM scope supplies CSS tokens."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the portal mounted in the DOM while the popup is hidden."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div. Native props, handlers and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"How to align the popup relative to the specified side."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: PopoverPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div. Accepts the complete Base UI anchor, collision and positioning contract."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"8","description":"Distance from the anchor. Defaults to 8. Accepts a number or positioning function."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: PopoverPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Popup content. Compose Portal, Positioner and Arrow separately."},{"name":"className","type":"string | ((state: PopoverPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is opened.\nBy default, focus moves to the first tabbable element inside the popup, except when the popover\nis opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div. Focus props, native attributes, handlers and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: PopoverArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the arrow div. Compose inside Popup."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: PopoverBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the optional backdrop div. Compose inside Portal."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: PopoverTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: PopoverDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"className","type":"string | ((state: PopoverCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The content to render inside the transition container."},{"name":"className","type":"string | ((state: PopoverViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the content-transition div for changing trigger payloads."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Tooltip","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Tooltip\ndescription: Show supplementary information when a trigger is hovered or focused.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TooltipReference from '/snippets/ui/generated/surfaces/tooltip.mdx';\n\n## Overview\n\nUse `Tooltip` for a short explanation of a control or truncated text. Keep essential information visible, give controls an accessible name, and use [Popover](/ui/primitives/surfaces/popover) when the content contains links, buttons, or other controls.\n\n<StoryEmbed\n storyId=\"ui-surfaces-tooltip--display\"\n title=\"Tooltip example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ExportHelp = () => (\n <Tooltip content=\"Download the visible records as a CSV file\" side=\"top\">\n <Text render={<span />}>\n <Button>Export records</Button>\n </Text>\n </Tooltip>\n);\n```\n\nThe convenience component accepts one trigger element as `children`. Native elements receive the trigger attributes, event handlers, and ref directly. Custom trigger components must forward all of them. A wrapper element also works with a component that does not forward every trigger prop.\n\nHover opens the tooltip after `delay` milliseconds, which defaults to `600`. Keyboard focus opens it immediately. `closeDelay` defaults to `0`; hovering over the popup keeps it open unless `disableHoverablePopup` is set. Escape dismisses it.\n\n## Controlled state\n\nUse `open` and `onOpenChange` together when the application owns visibility. Use `defaultOpen` only to set the initial visibility of an uncontrolled tooltip.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const ControlledExportHelp = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Tooltip\n content=\"Download the visible records as a CSV file\"\n open={open}\n onOpenChange={setOpen}\n delay={300}\n >\n <span>\n <Button>Export records</Button>\n </span>\n </Tooltip>\n );\n};\n```\n\n## Rich content and composition\n\nShorthand accepts `description` and `startIcon` beside `content`. Custom node content renders as supplied unless a description or icon requests the title layout.\n\n```tsx\nimport { IconInfoCircle } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const ExportDetails = () => (\n <Tooltip\n content=\"Export visible records\"\n description=\"Only records matching your current filters are included.\"\n startIcon={<IconInfoCircle />}\n arrow\n >\n <Button>Export records</Button>\n </Tooltip>\n);\n```\n\nCompound usage exposes every installed Base UI part and the optional `Tooltip.Body` layout. Assemble the portal, positioning, popup and optional arrow explicitly. Popup renders its children as supplied; Body provides the same title, description and decorative icon layout as shorthand.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const ComposedExportDetails = () => (\n <Tooltip.Provider delay={300} closeDelay={100} timeout={400}>\n <Tooltip.Root>\n <Tooltip.Trigger render={<Button>Export records</Button>} />\n <Tooltip.Portal>\n <Tooltip.Positioner side=\"inline-end\" sideOffset={10} arrowPadding={8}>\n <Tooltip.Popup>\n <Tooltip.Arrow />\n <Tooltip.Viewport>\n <Tooltip.Body description=\"Only records matching your current filters are included.\">\n Export visible records\n </Tooltip.Body>\n </Tooltip.Viewport>\n </Tooltip.Popup>\n </Tooltip.Positioner>\n </Tooltip.Portal>\n </Tooltip.Root>\n </Tooltip.Provider>\n);\n```\n\n| Part | Native, prop and ref target |\n| ------------ | --------------------------------------------------------------------------------------------------------------------------- |\n| `Root` | State and payload coordination. No DOM node, native props or DOM ref. `actionsRef` exposes `close` and `unmount`. |\n| `Provider` | Shared `delay`, `closeDelay` and `timeout`. No DOM node or DOM ref. |\n| `Trigger` | A button by default. Native props, handlers, `render` and ref target the trigger element. |\n| `Portal` | The portal div. Defaults to the theme container, then document body. |\n| `Positioner` | The positioning div. Owns anchor, physical/logical side, offsets, collision handling, sticky positioning and arrow padding. |\n| `Popup` | The popup div. Owns content, native props, styles, `render` and ref. |\n| `Body` | The optional body div inside Popup or Viewport. Native props, styles, `render` and ref target its root. |\n| `Arrow` | The arrow div inside Popup. |\n| `Viewport` | The optional div for transitions between trigger payloads. |\n\n`Tooltip.Body` accepts optional title children, `description` and `startIcon` nodes. Titles use medium weight; descriptions use the secondary tooltip color, preserve line breaks and wrap long text. Omit title children for a description-only tooltip. The icon is decorative and appears only with a title. Body adds no tooltip role, popup styling, sizing or positioning. Arbitrary Popup content remains supported. Import `TooltipBodyProps` from `twenty-ui/primitives/surfaces` when typing a wrapper.\n\nEvery DOM part accepts native props, refs, and element or callback `render` composition. Shorthand's top-level native props, `render` and ref target Popup. Use `triggerProps`, `positionerProps` and `portalProps` to customize the other targets; these override shorthand defaults. Children supply the default trigger render element. Both forms preserve controlled/uncontrolled Root state and Base UI callback event details, including cancellation, reason, original event and active trigger.\n\n`Tooltip.createHandle<TPayload>()` connects detached triggers to either form through `handle`. Compound Root's children or shorthand's `content` can be a function receiving the typed active payload. `Tooltip.Handle` and the public `TooltipHandle` type expose the installed handle contract. Handles support imperative `open(triggerId)` and `close()` while their Root is mounted.\n\n## Migration\n\nReplace `content={<Tooltip.Content description={description} startIcon={icon}>title</Tooltip.Content>}` with `content={title} description={description} startIcon={icon}`. In compound usage, use `Tooltip.Body` for the shared title and description layout or compose your own content. `Tooltip.Content` and `TooltipContentProps` are removed.\n\nExisting compound Popup positioning props move to Positioner. Wrap it in Portal, move `container` and `keepMounted` to Portal, keep `maxWidth` on Popup, and replace `arrow` with an Arrow child. Preserve the former spacing explicitly with `sideOffset={10}` when needed. Compound Positioner keeps Base UI's `sideOffset={0}`. Both forms cap Popup at 300 pixels by default.\n\n## Disabled controls\n\nNative disabled buttons cannot receive keyboard focus. Wrap one in a focusable trigger so users can discover why the action is unavailable.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const UnavailableExport = () => (\n <Tooltip content=\"Select at least one record to export\">\n <span tabIndex={0} aria-label=\"Export records unavailable\">\n <Button disabled>Export records</Button>\n </span>\n </Tooltip>\n);\n```\n\nSetting `disabled` on shorthand or Root suppresses the tooltip itself. Trigger `disabled` suppresses that trigger’s tooltip interaction. Disable the native control through its own props or Trigger’s render element.\n\n## Placement and overflowing text\n\nShorthand defaults to `side=\"top\"`, `align=\"center\"`, and `sideOffset={10}`. Both shorthand and compound tooltips have a maximum width of 300 pixels, capped by the available space beside the anchor. Pass `maxWidth` to shorthand or `Tooltip.Popup` to choose a different maximum, including wider previews. Native popup styles remain available for custom sizing. Placement adjusts to available space. An open tooltip hides while its anchor is scrolled out of view, including out of a scroll container. Use `arrow` for an arrow and `container` to override the theme's portal destination; see [theming](/ui/theming).\n\nUse [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip) when a text label should show its full value only when truncated. Its existing `text`, `tooltipContent`, and `tooltipPlace` props remain available.\n\n## Props\n\nThe reference is generated from the public component types. Native popup attributes and event handlers are also accepted.\n\n<TooltipReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Tooltip","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/tooltip","props":[{"name":"actionsRef","type":"RefObject<TooltipRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the tooltip after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the tooltip completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the tooltip imperatively when called."},{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"Alignment relative to the trigger. Defaults to center."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Offset along the alignment axis in pixels."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An explicit positioning anchor for the popup."},{"name":"arrow","type":"boolean","required":false,"defaultValue":null,"description":"Displays an arrow pointing to the trigger. Defaults to false."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance from the arrow to the popup edges."},{"name":"children","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":true,"defaultValue":null,"description":"A single trigger element. Custom components must forward their ref, native attributes, and event handlers."},{"name":"className","type":"string | ((state: TooltipPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"Additional CSS class for the popup."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"Delay in milliseconds before closing after hover ends. Defaults to 0."},{"name":"closeOnClick","type":"boolean","required":false,"defaultValue":"true","description":"Whether the tooltip should close when this trigger is clicked."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Defaults to the current theme container."},{"name":"content","type":"ReactNode | PayloadChildRenderFunction<TPayload>","required":true,"defaultValue":null,"description":"Supplementary content, or a function receiving the active trigger payload. Strings and numbers use the shorthand title layout."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Initial visibility when the tooltip manages its own state."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip."},{"name":"delay","type":"number","required":false,"defaultValue":"600","description":"Delay in milliseconds before opening on hover. Defaults to 600."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional secondary text below the shorthand title."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Prevents the tooltip from opening."},{"name":"disableHoverablePopup","type":"boolean","required":false,"defaultValue":"false","description":"Prevents hovering over the popup from keeping it open."},{"name":"handle","type":"TooltipHandle<TPayload>","required":false,"defaultValue":null,"description":"Connects detached triggers and preserves their typed payloads."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":null,"description":"Keeps the popup mounted while closed."},{"name":"maxWidth","type":"MaxWidth<string | number>","required":false,"defaultValue":null,"description":"Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the tooltip is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controlled visibility of the tooltip."},{"name":"portalProps","type":"TooltipPortalProps","required":false,"defaultValue":null,"description":"Full Portal props, including native props, ref and render. Overrides shorthand portal defaults."},{"name":"positionerProps","type":"TooltipPositionerProps","required":false,"defaultValue":null,"description":"Full Positioner props, including native props, ref and render. Overrides shorthand placement defaults."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"CSS positioning method for the popup."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the popup element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"top","description":"Preferred side of the trigger. Defaults to top and may change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"10","description":"Distance from the trigger in pixels. Defaults to 10."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional node before the shorthand title."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles for the popup."},{"name":"trackCursorAxis","type":"\"both\" | \"none\" | \"x\" | \"y\"","required":false,"defaultValue":"none","description":"Determines which axis the tooltip should track the cursor on."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled tooltip.\nThere's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set)."},{"name":"triggerProps","type":"TooltipTriggerProps<TPayload>","required":false,"defaultValue":null,"description":"Full Trigger props, including native props, ref, render and payload. Overrides the shorthand trigger defaults."},{"name":"withExitAnimation","type":"boolean","required":false,"defaultValue":null,"description":"Fades and slides the popup out when it closes instead of hiding it at once."}],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<TooltipRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the tooltip after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the tooltip completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the tooltip imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"Parts or a render function receiving the active trigger payload. Root renders no DOM node."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the tooltip is initially open.\n\nTo render a controlled tooltip, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the tooltip is disabled."},{"name":"disableHoverablePopup","type":"boolean","required":false,"defaultValue":"false","description":"Whether the tooltip contents can be hovered without closing the tooltip."},{"name":"handle","type":"TooltipHandle<Payload>","required":false,"defaultValue":null,"description":"Connects detached triggers and imperative open/close actions."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the tooltip is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the tooltip is currently open."},{"name":"trackCursorAxis","type":"\"both\" | \"none\" | \"x\" | \"y\"","required":false,"defaultValue":"none","description":"Determines which axis the tooltip should track the cursor on."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled tooltip.\nThere's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: TooltipTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the tooltip. Specified in milliseconds."},{"name":"closeOnClick","type":"boolean","required":false,"defaultValue":"true","description":"Whether the tooltip should close when this trigger is clicked."},{"name":"delay","type":"number","required":false,"defaultValue":"600","description":"How long to wait before opening the tooltip on hover. Specified in milliseconds."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables tooltip interaction for this trigger without disabling its native element."},{"name":"handle","type":"TooltipHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with a tooltip."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the tooltip when it is opened."},{"name":"ref","type":"((((instance: HTMLButtonElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<HTMLButtonElement | null>) & (((instance: HTMLElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<...>)) | null","required":false,"defaultValue":null,"description":"Ref to the rendered trigger element, a button by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipTriggerState>","required":false,"defaultValue":null,"description":"Composes a native element or a component that forwards attributes, handlers and ref."},{"name":"style","type":"CSSProperties | ((state: TooltipTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: TooltipPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Defaults to the current theme container, then the document body."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the portal mounted in the DOM while the popup is hidden."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"How to align the popup relative to the specified side."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: TooltipPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div. Native props, styles and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"top","description":"Preferred physical or logical side of the anchor. Defaults to top."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Distance from the anchor. Defaults to 0 in compound usage. Accepts a number or positioning function."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: TooltipPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered as supplied. Does not create a portal, positioner, title layout or arrow."},{"name":"className","type":"string | ((state: TooltipPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"maxWidth","type":"MaxWidth<string | number>","required":false,"defaultValue":null,"description":"Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div. Native props, styles and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"withExitAnimation","type":"boolean","required":false,"defaultValue":"false","description":"Enables the optional Twenty exit transition."}]},{"name":"Body","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional title content, displayed with medium weight. Omit it for a description-only tooltip."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional secondary content. Preserves line breaks and wraps long text."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the body div. Native props, styles and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Composes the body root through an element or render callback while preserving its layout and content."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional decorative node before the title. Omitted when the title is empty."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: TooltipArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the arrow div. Compose inside Popup."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The content to render inside the transition container."},{"name":"className","type":"string | ((state: TooltipViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the content-transition div. Useful when several triggers share changing content."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Provider","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Tooltips sharing delay, closeDelay and timeout configuration. Provider renders no DOM node."},{"name":"closeDelay","type":"number","required":false,"defaultValue":null,"description":"How long to wait before closing a tooltip. Specified in milliseconds."},{"name":"delay","type":"number","required":false,"defaultValue":null,"description":"How long to wait before opening the tooltip on hover. Specified in milliseconds."},{"name":"timeout","type":"number","required":false,"defaultValue":"400","description":"Another tooltip will open instantly if the previous tooltip\nis closed within this timeout. Specified in milliseconds."}]}]}},{"name":"Toast","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Toast\ndescription: Display status messages with optional details, actions, and progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ToastReference from '/snippets/ui/generated/components/feedback/toast.mdx';\nimport ToastProviderReference from '/snippets/ui/generated/components/feedback/toast-provider.mdx';\nimport ToasterReference from '/snippets/ui/generated/components/feedback/toaster.mdx';\n\n## Overview\n\n`Toast` renders one notification. Your application controls when it appears, its position, and when it is removed.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--display\"\n title=\"Toast example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SavedNotification = () => {\n const [isOpen, setIsOpen] = useState(true);\n\n return (\n <>\n <Button onClick={() => setIsOpen(true)}>Show notification</Button>\n {isOpen && (\n <Toast status=\"success\" progress={100} onClose={() => setIsOpen(false)}>\n Changes saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n## Visual options\n\nCompare neutral, success, error, information, and warning feedback with the same message and progress.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--catalog\"\n title=\"Toast feedback statuses\"\n height={530}\n/>\n\nFor application notifications, wrap the application in `ToastProvider`, mount a `Toaster` inside it, and use `useToast()` from descendants. Each provider owns an independent notification store, countdowns, and dismissal lifecycle. Multiple Toasters can mirror the same provider.\n\n## Application notifications\n\n```tsx\nimport { useState } from 'react';\n\nimport {\n ToastProvider,\n Toaster,\n useToast,\n} from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst SaveNotificationButton = () => {\n const { enqueueToast } = useToast();\n\n return (\n <Button\n onClick={() =>\n enqueueToast({\n children: 'Record saved',\n status: 'success',\n })\n }\n >\n Add saved notification\n </Button>\n );\n};\n\nexport const Notifications = () => {\n const [limit, setLimit] = useState(3);\n\n return (\n <ToastProvider limit={limit}>\n <SaveNotificationButton />\n <Button onClick={() => setLimit(1)}>Keep one notification</Button>\n <Button onClick={() => setLimit(3)}>Keep three notifications</Button>\n <Toaster />\n </ToastProvider>\n );\n};\n```\n\n`enqueueToast` accepts Toast props and an optional `dedupeKey`, and returns the notification ID. A matching visible key returns the existing ID without adding another notification. `updateToast({ id, ...changes })` patches that live notification. `closeToast(id)` dismisses one notification; `closeToast()` dismisses all visible notifications in the provider.\n\nThe provider defaults to three visible notifications. `limit` must be a positive integer and can change while the provider is mounted. Lowering it or adding above it dismisses the oldest visible notifications first. Increasing it leaves existing notifications unchanged and does not restore dismissed notifications. Configuration changes preserve the store, surviving IDs, order, and remaining countdown time.\n\n## Provider lifecycle\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--documentation\"\n title=\"Shared notification lifecycle\"\n height={430}\n/>\n\nMultiple Toasters inside a provider render the same notifications. Updates and dismissal apply to every mirror, and each notification has one shared countdown. Hover or focus inside any mirror pauses it; it resumes after all mirrors release both. Mounting another Toaster does not restart the countdown or create another callback lifecycle. Use separate providers for independent queues.\n\nFor provider notifications, expiry, the close button, `closeToast`, and limit eviction call the latest `onClose` once. The notification is already dismissed when the callback runs, so updates and repeated close requests for that ID have no effect. `onCancel` remains a separate action callback and does not dismiss automatically.\n\nDismissed notifications are inert during exit animations. Their entries are removed after all rendered mirrors finish their exit work or unmount. Unmounting the last Toaster clears dismissed entries and freezes the remaining time for visible notifications. Remounting a Toaster resumes that time. Unmounting the provider discards its notifications and cancels countdown and exit work without calling `onClose`. Captured `enqueueToast`, `updateToast`, and `closeToast` operations from that provider have no effect after it unmounts.\n\n`getToastProps` adapts each notification’s content and presentation. Set `duration` and `progress` in `enqueueToast` or `updateToast` so every mirror shares the same timing configuration. Existing timing overrides through `getToastProps` remain supported when all mirrors return the same duration and progress for a notification. The provider retains the ID, dismissal handler, and shared countdown.\n\n`container` selects a Toaster’s portal destination. When omitted, it uses the surrounding theme container or `document.body`. An explicit element renders there; `null` defers rendering. Visible notifications remain queued, with their countdowns paused while no Toaster is rendered. Portals retain the surrounding theme and direction. Set `aria-label` on each Toaster to localize its default region name, \"Notifications\", and give mirrored regions appropriate names.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--portal-documentation\"\n title=\"Scoped notification portal\"\n height={430}\n/>\n\n## Update a live notification\n\nUse the ID returned by `enqueueToast` to update content, feedback status, actions, or callbacks in place. Updates preserve the notification's ID and position. Unknown or dismissed IDs have no effect, including while the dismissal animation runs. Each `useToast()` call targets its closest provider.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster--updates-documentation\"\n title=\"Update a live notification\"\n height={380}\n/>\n\n```tsx\nimport { useToast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveButtonProps = {\n saveRecord: () => Promise<void>;\n onViewRecord: () => void;\n};\n\nexport const SaveButton = ({ saveRecord, onViewRecord }: SaveButtonProps) => {\n const { enqueueToast, updateToast } = useToast();\n\n const save = async () => {\n const id = enqueueToast({\n children: 'Saving record',\n status: 'info',\n progress: 0,\n });\n\n try {\n await saveRecord();\n updateToast({\n id,\n children: 'Record saved',\n status: 'success',\n progress: undefined,\n action: <Button onClick={onViewRecord}>View record</Button>,\n });\n } catch {\n updateToast({\n id,\n children: 'Record could not be saved',\n status: 'error',\n progress: undefined,\n });\n }\n };\n\n return <Button onClick={save}>Save record</Button>;\n};\n```\n\n`ToastUpdate` requires `id` and accepts partial Toast options. Omitted fields keep their current values. Explicit `undefined` clears an optional field or restores its component default, such as `progress: undefined` or `status: undefined`. Pass `null` to remove a content slot, including `description`, `icon`, or `action`. Setting `cancelLabel: null` hides the cancel control while preserving its callback. Callback changes take effect on the existing notification. `dedupeKey` belongs to enqueueing and cannot be updated.\n\n## Dismissal timing\n\nThe countdown defaults to 6,000 milliseconds. It pauses while the pointer is over the toast or keyboard focus is inside it, and resumes only after both leave. With multiple Toasters, pause state is shared across their mirrors. The visual countdown follows the remaining dismissal time. Automatic dismissal also works when reduced motion disables the animation.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-timing--documentation\"\n title=\"Toast timing controls\"\n height={480}\n/>\n\n| Operation | Countdown behavior |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Update content, status, actions, or callbacks | Preserve the remaining time. Repeated updates do not extend it. |\n| Supply `duration` to `updateToast` | Start a fresh duration, including when the value is unchanged. `duration: undefined` restores the default and restarts it. |\n| Change a standalone `Toast`'s `duration` prop | Start a fresh duration. Rendering the same value again keeps the remaining time. |\n| Set `duration: 0` | Keep the toast open until it is dismissed. |\n| Supply `progress` | Stop the countdown while progress is present. |\n| Remove `progress` | Start a fresh duration, or keep it open when its duration is zero. |\n| Update while hovered or focused | Apply the same rules, keeping the resulting countdown paused until both pointer and focus leave. |\n\nFor example, `updateToast({ id, children: 'Still saving' })` preserves the remaining time, while `updateToast({ id, duration: 6000 })` gives the reader another six seconds. These rules apply to the existing notification without changing its ID or position.\n\n## Dismissible notification\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveNotification = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <>\n <Button onClick={() => setVisible(true)}>Show saved notification</Button>\n {visible && (\n <Toast\n status=\"success\"\n description=\"Your changes are available to your team.\"\n duration={6000}\n onClose={() => setVisible(false)}\n >\n Record saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n`onClose` is called once by the close button or when the countdown completes. Remove the toast in that callback. Use `duration={0}` for a notification that stays open until dismissal.\n\n## Progress and cancellation\n\n```tsx\nimport { Toast } from 'twenty-ui/components/feedback';\n\ntype ImportProgressProps = { progress: number; onCancel: () => void };\n\nexport const ImportProgress = ({ progress, onCancel }: ImportProgressProps) => (\n <Toast\n status=\"info\"\n progress={progress}\n description=\"You can continue working while the import runs.\"\n onCancel={onCancel}\n cancelLabel=\"Cancel import\"\n >\n Importing records: {progress}%\n </Toast>\n);\n```\n\nPassing `progress` supplies a percentage and disables the countdown. Remove it after the operation finishes to start a fresh duration. Cancellation invokes `onCancel`; the parent owns cancellation and removal. `cancelLabel` accepts a React node for the button content. Children, `description`, `icon`, and `action` also accept caller-owned React nodes. Use Twenty UI controls for interactive actions and provide their accessible names.\n\n## Appearance and announcements\n\n`status` accepts `neutral`, `info`, `success`, `warning`, or `error` and defaults to `neutral`. It expresses feedback meaning and selects the icon and theme palette. Toast has one supported appearance, so it exposes no appearance `variant` or palette `color` option. Use `icon` to replace the icon, `icon={null}` to omit it, and `iconLabel` when the default icon needs its own accessible name.\n\nThe default role is `status` with polite announcements. Use `role=\"alert\"` for urgent feedback. Set `cancelLabel` and `closeLabel` to localize the controls, and allow enough time to read the content or interact with its actions.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, styles, class names, event handlers, and refs target the root. Use `render` to compose another element or component while retaining those props and the ref. Toaster portals inherit the surrounding theme and text direction.\n\n<ToastReference />\n\n### ToastProvider\n\n<ToastProviderReference />\n\n### Toaster\n\nNative div attributes, styles, class names, and refs target the notification region.\n\n<ToasterReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Toast","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/toast","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional footer node, such as a Button with a caller-owned action."},{"name":"cancelLabel","type":"ReactNode","required":false,"defaultValue":"Cancel","description":"Cancel button content node. Defaults to Cancel. Pass null to hide the control."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Main message node. Callers own its content and accessible text."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional class names merged onto the root."},{"name":"closeLabel","type":"string","required":false,"defaultValue":"Close","description":"Accessible name of the close button. Defaults to Close."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional supporting content node rendered below the message."},{"name":"duration","type":"number","required":false,"defaultValue":"6000","description":"Milliseconds before onClose is called, defaulting to 6000. Zero keeps the toast open. Changes restart the countdown; live updateToast duration patches restart it even when unchanged. Hover and keyboard focus pause it until both leave."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":null,"description":"Leading icon node. Defaults to the status icon. Pass null to omit it."},{"name":"iconLabel","type":"string","required":false,"defaultValue":null,"description":"Accessible name of the default icon. Without it, the icon is decorative."},{"name":"onCancel","type":"(() => void)","required":false,"defaultValue":null,"description":"Called when the cancel button is clicked. Providing it and renderable cancelLabel content shows the button."},{"name":"onClose","type":"(() => void)","required":false,"defaultValue":null,"description":"For standalone Toast, called once per mount by the close button or expiry. For provider notifications, called once on close, expiry, closeToast, or limit eviction, after dismissal and before exit cleanup. Provider teardown does not call it."},{"name":"progress","type":"number","required":false,"defaultValue":null,"description":"Completion percentage. Providing it disables the countdown. Removing it starts a fresh duration."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element supplied through render."},{"name":"render","type":"RenderProp<Record<string, unknown>>","required":false,"defaultValue":null,"description":"Element or callback composition for the root. Native props and the ref target the rendered element."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"neutral","description":"Feedback meaning: neutral, info, success, warning, or error. Defaults to neutral and selects the icon and theme palette."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles forwarded to the root."}]}},{"name":"Text","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: Text\ndescription: Compose theme typography with single-line truncation or a limited number of lines.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport TextReference from '/snippets/ui/generated/typography/text.mdx';\n\n## Overview\n\n`Text` provides typography and overflow handling. It renders a `div` by default. Omit `size`, `weight` and `color` to keep inheriting typography from its surroundings.\n\n<StoryEmbed\n storyId=\"ui-typography-text--display\"\n title=\"Text example\"\n height={90}\n/>\n\n## Usage\n\nGive the text a constrained width, then set `truncate` to show an ellipsis when it overflows:\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ContactName = () => (\n <Text truncate style={{ maxWidth: 160 }}>\n Alexandra Montgomery\n </Text>\n);\n```\n\n## Choose typography\n\n`size` uses the existing theme scale. It changes font size, with no height, font-family or line-height default:\n\n| Size | Theme value |\n| ----- | ----------- |\n| `xxs` | `0.625rem` |\n| `xs` | `0.85rem` |\n| `sm` | `0.92rem` |\n| `md` | `1rem` |\n| `lg` | `1.23rem` |\n| `xl` | `1.54rem` |\n| `xxl` | `1.85rem` |\n\n`weight` accepts `regular` (400), `medium` (500) or `semibold` (600). `color` accepts `primary`, `secondary`, `tertiary` or `light`. Each omitted prop inherits independently. The visual size does not change the semantic element.\n\n<StoryEmbed\n storyId=\"ui-typography-text--typography-catalog\"\n title=\"Text typography scale\"\n height={410}\n/>\n\nFor captions, compose the small size, semibold weight and light color:\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const Caption = () => (\n <Text size=\"xs\" weight=\"semibold\" color=\"light\">\n Workspace\n </Text>\n);\n```\n\nUse native `style` for runtime colors and parent-layout constraints. Caller classes and render composition target the same text element. Text adds no typography defaults when these props are omitted.\n\n## Limit the number of lines\n\n<StoryEmbed\n storyId=\"ui-typography-text--catalog\"\n title=\"Text overflow options\"\n height={210}\n/>\n\nUse `lineClamp` with a positive integer. Choose either `truncate` or `lineClamp`; their props are mutually exclusive.\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const Summary = () => (\n <Text lineClamp={2} style={{ maxWidth: 240 }}>\n Follow up with the customer about their onboarding milestones and upcoming\n renewal.\n </Text>\n);\n```\n\n## Choose an element\n\nUse `render` when the text needs another semantic element:\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const Description = () => (\n <Text render={<p />}>Account description</Text>\n);\n```\n\nTruncation affects the visual presentation; it does not shorten the text in the DOM. Provide a way to read the full content when the visible portion is insufficient.\n\n## Props\n\nNative attributes, children, refs, class names, and styles target the rendered text element. `TextProps` is exported from `twenty-ui/primitives/typography`. Text content is rendered unchanged, including caller-provided links.\n\n<TextReference />\n\n## Migration\n\n`color` now selects a semantic theme color. Move arbitrary CSS color values from a native `color` attribute to `style={{ color: customColor }}`. Existing styles, classes and render composition continue to target the text element.\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"Text","entryPoint":"twenty-ui/primitives/typography","slug":"typography/text","props":[{"name":"color","type":"\"light\" | \"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":null,"description":"Semantic text color. Omitted values inherit; native style supports runtime colors."},{"name":"lineClamp","type":"number","required":false,"defaultValue":null,"description":"Positive integer limiting the number of visible lines. Cannot be combined with `truncate`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default div. Native props and the ref target the rendered text element."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\" | \"xxs\"","required":false,"defaultValue":null,"description":"Font size from the theme scale. Omitted values inherit; this does not set height."},{"name":"truncate","type":"boolean","required":false,"defaultValue":null,"description":"Truncates one line with an ellipsis. Cannot be combined with `lineClamp`."},{"name":"weight","type":"\"medium\" | \"regular\" | \"semibold\"","required":false,"defaultValue":null,"description":"Theme font weight. Omitted values inherit."}]}},{"name":"Avatar","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Avatar\ndescription: Represent a person or record with an image, initial, or icon.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport AvatarReference from '/snippets/ui/generated/data-display/avatar.mdx';\n\n## Overview\n\n`Avatar` shows an image with a first-letter fallback. Use it beside a record name or inside a [Chip](/ui/primitives/data-display/chip). Its default root is a presentational `span`.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--display\"\n title=\"Avatar example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const WorkspaceAvatar = () => (\n <Avatar\n name=\"Acme\"\n colorSeed=\"acme-app\"\n shape=\"square\"\n variant=\"outline\"\n size=\"md\"\n />\n);\n```\n\nWhen the image is absent or fails to load, the fallback shows the first letter of the trimmed name in uppercase. An empty name shows `-`. `colorSeed` chooses stable fallback colors and defaults to `name`; use a record identifier to keep the color stable when the name changes.\n\nThe image and default fallback are decorative. `name` supplies the visual initial and fallback colors without adding an accessible label. When the avatar is the only representation of a person or record, set `imageProps={{ alt: name }}` to label both the image and default fallback. Keep the avatar decorative when a visible name or labeled owner already provides that information.\n\n`imageProps` accepts the complete image contract, including `srcSet`, `sizes`, `crossOrigin`, `referrerPolicy`, native events, refs, and `render`. Its `src` overrides the shorthand `src`. `fallbackProps` accepts the complete fallback contract, including `delay`, children, labeling, refs, and `render`. A custom fallback `render` owns its accessibility semantics; set `aria-hidden` explicitly when it is decorative.\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype RecordAvatarProps = {\n name: string;\n imageUrl?: string;\n initials: string;\n};\n\nexport const RecordAvatar = ({\n name,\n imageUrl,\n initials,\n}: RecordAvatarProps) => (\n <Avatar\n name={name}\n src={imageUrl}\n size=\"lg\"\n imageProps={{ alt: name, decoding: 'async', referrerPolicy: 'no-referrer' }}\n fallbackProps={{ children: initials, delay: 150 }}\n />\n);\n```\n\n## Compose the parts\n\nUse `Avatar.Root`, `Avatar.Image`, and `Avatar.Fallback` when you own the anatomy. Root supplies the size, shape, and fallback appearance; it does not generate children or accessible labels.\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype ContactAvatarProps = {\n name: string;\n imageUrl?: string;\n initials: string;\n};\n\nexport const ContactAvatar = ({\n name,\n imageUrl,\n initials,\n}: ContactAvatarProps) => (\n <Avatar.Root name={name} shape=\"circle\" size=\"xxl\">\n <Avatar.Image src={imageUrl} alt={name} decoding=\"async\" />\n <Avatar.Fallback role=\"img\" aria-label={name} delay={150}>\n {initials}\n </Avatar.Fallback>\n </Avatar.Root>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--parts\"\n title=\"Avatar parts\"\n height={110}\n/>\n\nThe parts share Base UI's image loading state. Image renders an `img` after a successful load by default, and Fallback renders a `span` while the image is absent, loading, or has failed. `delay` postpones the initial fallback display in milliseconds and defaults to `0`. A changed source is loaded again and can replace either the current image or fallback.\n\n`Avatar.Image` exposes `onLoadingStatusChange` with `idle`, `loading`, `loaded`, and `error` status values. The callback runs when Base UI reports a non-idle status change; unmounting the Image part resets the shared root state to `idle`. Root, Image, and Fallback accept state-aware `className`, `style`, and `render` functions with `imageLoadingStatus`; Image also exposes `transitionStatus`.\n\nUse `keepMounted` on Image when the rendered image must load in place, including `loading=\"lazy\"` or an optimized image component. Forward native attributes, events, and the ref from custom image renderers. A mounted image can still be loading or failed; inspect loading state rather than treating its presence as success.\n\nThe front component renderer currently supports the default preload path with `src`. Its host image does not receive `srcSet`, `sizes`, `loading`, `decoding`, or `referrerPolicy`. A changing custom `render` function with `keepMounted` can leave a decoded image hidden because the worker cannot read its completion state or dimensions. Use default preloading there until those renderer capabilities are available.\n\nThe public `AvatarRootProps`, `AvatarImageProps`, `AvatarFallbackProps`, `AvatarRootState`, `AvatarImageState`, `AvatarFallbackState`, and `AvatarImageLoadingStatus` types are exported from `twenty-ui/primitives/data-display`. Refs target the rendered DOM element: `span`, `img`, and `span` by default, or the element supplied through `render`.\n\n## Shape and appearance\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--catalog\"\n title=\"Avatar sizes and shapes\"\n height={320}\n/>\n\n`shape` accepts `square`, `rounded-square`, or `circle`. Sizes are `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), and `xxl` (40px). Both `xl` and `xxl` use 16px fallback text.\n\nThe former 40px `xl` size is now `xxl`. Update existing `size=\"xl\"` usages to `size=\"xxl\"` when they should remain 40px.\n\n`variant=\"outline\"` adds a border to the fallback. The `color`, `backgroundColor`, and `borderColor` overrides customize the fallback, while a loaded image keeps its original appearance.\n\n```tsx\nimport { IconUser } from 'twenty-ui/icon';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const ContactIcon = () => (\n <Avatar\n icon={<IconUser />}\n shape=\"rounded-square\"\n size=\"xxl\"\n role=\"img\"\n aria-label=\"Contact\"\n />\n);\n```\n\nAn `icon` takes precedence over both the image and the first-letter fallback. The icon itself is decorative, so label the root when it conveys information. `pulsing` animates opacity and respects reduced-motion preferences.\n\n## Open a profile\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype ProfileAvatarProps = {\n onOpenProfile: () => void;\n disabled?: boolean;\n};\n\nexport const ProfileAvatar = ({\n onOpenProfile,\n disabled = false,\n}: ProfileAvatarProps) => (\n <Avatar\n name=\"Jane\"\n shape=\"circle\"\n size=\"lg\"\n render={\n <button\n type=\"button\"\n disabled={disabled}\n aria-label=\"Open Jane's profile\"\n onClick={onOpenProfile}\n />\n }\n />\n);\n```\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--button-composition\"\n title=\"Avatar composed as a button\"\n height={110}\n/>\n\nCompose a native button for actions. It owns focus, Enter and Space activation, and disabled behavior. Supply an action-specific accessible name. Put `onClick` and `disabled` on the rendered button; shorthand Avatar has no `onClick`, `disabled`, or `nativeButton` prop.\n\nFor navigation, compose an anchor with an `href` or a router link that preserves anchor semantics. Native links activate with Enter. Keep navigation and disabled behavior with the link or interactive component you compose.\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const ProfileLink = () => (\n <Avatar\n name=\"Jane\"\n shape=\"circle\"\n size=\"lg\"\n render={<a href=\"/people/jane\" aria-label=\"Open Jane's profile\" />}\n />\n);\n```\n\n## Migrate clickable avatars\n\nCompose a native button through `render` for actions, or an anchor or router link for navigation. Move `onClick` and `disabled` onto that owner and remove `nativeButton`. Give the owner a useful accessible name and avoid nesting interactive elements. `Avatar.Root` and the other explicit parts retain the complete Base UI event contract.\n\nShorthand avatars are decorative by default. `name` does not name the image, fallback, or interactive owner. Use a nonempty `imageProps.alt` only when the avatar conveys identity that is not already supplied by visible text or an owner label. With explicit parts, supply image alternative text and fallback labels or decorative attributes yourself, and keep translated content in your application.\n\n## Props\n\nTypes and defaults are generated from the public component types. The explicit parts accept native attributes and event handlers. Shorthand Avatar omits `onClick`; supply it on the owner passed through `render`.\n\n<AvatarReference />\n\n<PageBanner illustration=\"page-cover-profile\" />\n","api":{"name":"Avatar","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/avatar","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"Background color override for a first-letter fallback."},{"name":"borderColor","type":"string","required":false,"defaultValue":null,"description":"Border color override for the outline fallback."},{"name":"className","type":"string | ((state: AvatarRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"Text color override for a first-letter fallback."},{"name":"colorSeed","type":"string","required":false,"defaultValue":null,"description":"Stable value used to choose fallback colors. Defaults to `name`."},{"name":"fallbackProps","type":"AvatarFallbackProps","required":false,"defaultValue":null,"description":"Complete `Avatar.Fallback` props, including caller-owned children, labeling, refs, `render`, and fallback `delay` in milliseconds."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information."},{"name":"imageProps","type":"AvatarImageProps","required":false,"defaultValue":null,"description":"Complete `Avatar.Image` props, including native image attributes, refs, `render`, `keepMounted`, and `onLoadingStatusChange`. Alternative text defaults to an empty string. Supply a nonempty `alt` to label the image and default fallback."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name used for the first-letter fallback and fallback colors. Does not add an accessible label."},{"name":"pulsing","type":"boolean","required":false,"defaultValue":"false","description":"Animates the avatar opacity. Respects reduced-motion preferences."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner."},{"name":"ring","type":"boolean","required":false,"defaultValue":"false","description":"Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct."},{"name":"shape","type":"\"circle\" | \"rounded-square\" | \"square\"","required":false,"defaultValue":"square","description":"Shape of the avatar and its fallback."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px)."},{"name":"src","type":"string | null","required":false,"defaultValue":null,"description":"Image URL. A missing or failed image shows the fallback. `imageProps.src` overrides this value."},{"name":"style","type":"CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"outline\" | \"soft\"","required":false,"defaultValue":"soft","description":"Visual treatment of the fallback."}],"parts":[{"name":"Root","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"Background color override for a first-letter fallback."},{"name":"borderColor","type":"string","required":false,"defaultValue":null,"description":"Border color override for the outline fallback."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned Image, Fallback, and other content."},{"name":"className","type":"string | ((state: AvatarRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"Text color override for a first-letter fallback."},{"name":"colorSeed","type":"string","required":false,"defaultValue":null,"description":"Stable value used to choose fallback colors. Defaults to `name`."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name used to choose fallback colors. Does not add children or accessible labels."},{"name":"pulsing","type":"boolean","required":false,"defaultValue":"false","description":"Animates the avatar opacity. Respects reduced-motion preferences."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner."},{"name":"ring","type":"boolean","required":false,"defaultValue":"false","description":"Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct."},{"name":"shape","type":"\"circle\" | \"rounded-square\" | \"square\"","required":false,"defaultValue":"square","description":"Shape of the avatar and its fallback."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px)."},{"name":"style","type":"CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"outline\" | \"soft\"","required":false,"defaultValue":"soft","description":"Visual treatment of the fallback."}]},{"name":"Image","props":[{"name":"alt","type":"string","required":false,"defaultValue":null,"description":"Caller-owned alternative text. Use an empty string for decorative images."},{"name":"className","type":"string | ((state: AvatarImageState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"crossOrigin","type":"\"\" | \"anonymous\" | \"use-credentials\"","required":false,"defaultValue":null,"description":"Native image cross-origin policy, also used during preloading."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown."},{"name":"loading","type":"\"eager\" | \"lazy\"","required":false,"defaultValue":null,"description":"Native eager or lazy loading. Use keepMounted for lazy loading."},{"name":"onLoadingStatusChange","type":"((status: ImageLoadingStatus) => void)","required":false,"defaultValue":null,"description":"Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback."},{"name":"referrerPolicy","type":"\"\" | \"no-referrer-when-downgrade\" | \"no-referrer\" | \"origin-when-cross-origin\" | \"origin\" | \"same-origin\" | \"strict-origin-when-cross-origin\" | \"strict-origin\" | \"unsafe-url\"","required":false,"defaultValue":null,"description":"Native image referrer policy, also used during preloading."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState>","required":false,"defaultValue":null,"description":"Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref."},{"name":"sizes","type":"string","required":false,"defaultValue":null,"description":"Native responsive image sizes used with srcSet."},{"name":"src","type":"string","required":false,"defaultValue":null,"description":"Image URL. Image renders after a successful load unless keepMounted is enabled."},{"name":"srcSet","type":"string","required":false,"defaultValue":null,"description":"Native responsive image source candidates."},{"name":"style","type":"CSSProperties | ((state: AvatarImageState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Fallback","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned fallback content, such as initials or an icon."},{"name":"className","type":"string | ((state: AvatarFallbackState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"delay","type":"number","required":false,"defaultValue":"0","description":"Milliseconds before the initial fallback is shown. Defaults to 0."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarFallbackState>","required":false,"defaultValue":null,"description":"Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes."},{"name":"style","type":"CSSProperties | ((state: AvatarFallbackState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Chip","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Chip\ndescription: Show compact caller-owned content with optional leading and trailing slots.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ChipReference from '/snippets/ui/generated/data-display/chip.mdx';\n\n## Overview\n\nUse `Chip` for compact references to people, records, or files. Use [Tag](/ui/primitives/data-display/tag) for colored categories and [Status](/ui/primitives/data-display/status) for workflow states.\n\n<StoryEmbed\n storyId=\"ui-data-display-chip--display\"\n title=\"Chip example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Avatar, Chip } from 'twenty-ui/primitives/data-display';\n\nexport const AssigneeChip = () => (\n <Chip\n variant=\"soft\"\n startElement={\n <Avatar name=\"Jane\" size=\"sm\" shape=\"circle\" imageProps={{ alt: '' }} />\n }\n >\n Jane\n </Chip>\n);\n```\n\nChildren accept text or nodes. `startElement` and `endElement` accept avatars, icons, or other content. `endElementDivider` adds a separator before the trailing content. The default chip is a `div`; its slots can contain a separate action while the chip itself remains presentational.\n\nChip never inserts a label. Supply a translated fallback from your application when needed. Omit children for content made entirely from slots. An interactive chip with only an icon needs a caller-supplied accessible name.\n\n## Appearance\n\n<StoryEmbed\n storyId=\"ui-data-display-chip--catalog\"\n title=\"Chip variants and sizes\"\n height={200}\n/>\n\n`size` accepts `sm` or `md`, with total heights of 20px and 24px. `variant` accepts `ghost`, `soft`, `solid`, `plain`, or `outline`; `ghost` is the default. Plain chips have no resting fill or leading padding. Outline chips have a strong 1px border, a lighter resting fill, and 8px inline padding on each side, with the same total height as other variants. Clickable plain and outline chips use the ghost hover and pressed backgrounds, pointer cursor, and focus ring. Use `shape=\"round\"` for a pill, `weight=\"medium\"` for emphasis, and `color=\"secondary\"` for secondary text.\n\n## Buttons and links\n\n```tsx\nimport { Avatar, Chip } from 'twenty-ui/primitives/data-display';\n\ntype AssigneeActionProps = {\n onOpenAssignee: () => void;\n disabled?: boolean;\n};\n\nexport const AssigneeAction = ({\n onOpenAssignee,\n disabled,\n}: AssigneeActionProps) => (\n <Chip\n render={<button type=\"button\" disabled={disabled} />}\n onClick={onOpenAssignee}\n aria-label=\"Open Jane's record\"\n startElement={\n <Avatar name=\"Jane\" size=\"sm\" shape=\"circle\" imageProps={{ alt: '' }} />\n }\n >\n Jane\n </Chip>\n);\n```\n\nSupplying `onClick` keeps the default `div`. Use `render` to compose an explicit native button, anchor, router link, or another appropriate owner. Native attributes, handlers, styles and the root ref reach that owner. A native button supplies keyboard activation and disabled behavior. Chip recognizes native disabled state and `aria-disabled` for appearance; `aria-disabled` alone does not prevent activation.\n\n`clickable` controls hover and pointer appearance and defaults to whether `onClick` is supplied. Set it explicitly for a link without a click handler. Do not nest buttons or links inside a chip that is itself interactive.\n\n```tsx\nimport { Chip } from 'twenty-ui/primitives/data-display';\n\nexport const DocumentationChip = () => (\n <Chip\n variant=\"outline\"\n shape=\"round\"\n render={<a href=\"https://twenty.com/developers\" />}\n clickable\n >\n Documentation\n </Chip>\n);\n```\n\nURL text remains plain text. Intentional links belong in caller content or in the explicit root composition.\n\n## Truncation and tooltips\n\n```tsx\nimport { Chip } from 'twenty-ui/primitives/data-display';\n\nexport const FileChip = () => (\n <Chip variant=\"soft\" maxWidth={180} tooltipPlace=\"top\">\n Quarterly customer research.pdf\n </Chip>\n);\n```\n\n`maxWidth` constrains the rendered chip width in pixels, including padding and any outline border. The same limit applies to plain chips with asymmetric padding. Content truncates with an ellipsis by default; `truncate={false}` leaves it unconstrained by truncation. String children supply their own tooltip text. Set `tooltipContent` for custom text or node content, `tooltipDelay` for the opening delay, and `isTooltipMultiline` to preserve line breaks. `alwaysShowTooltip` also enables the tooltip when content fits. These options follow [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip). Keep essential information available without relying on hover.\n\n## Migration\n\nReplace `emptyLabel` with caller-provided fallback children, and replace `forceEmptyText` or `isLabelHidden` with omitted children. Keep translated product fallbacks in the application. Replace `tooltipLabel` with `tooltipContent`. Move `disabled` to the explicit interactive owner and remove `nativeButton`. Add a native button or link through `render` wherever the chip previously relied on `onClick` to choose its element.\n\nReplace leading-padding overrides with `variant=\"plain\"`. Keep `clickable` enabled for native links and buttons that need hover and pressed feedback.\n\n## Props\n\nTypes and defaults are generated from the public component types. Native attributes and event handlers are also accepted.\n\n<ChipReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Chip","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/chip","props":[{"name":"alwaysShowTooltip","type":"boolean","required":false,"defaultValue":"false","description":"Shows the content tooltip even when the content is not truncated."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned content. Missing or empty children add no fallback label."},{"name":"clickable","type":"boolean","required":false,"defaultValue":"isDefined(onClick)","description":"Enables hover and pointer styling. Defaults to whether `onClick` is supplied; does not change the default div or add keyboard behavior."},{"name":"color","type":"\"primary\" | \"secondary\"","required":false,"defaultValue":"primary","description":"Primary or secondary text color."},{"name":"endElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content after the label. Avoid interactive content when the chip itself is a button or link."},{"name":"endElementDivider","type":"boolean","required":false,"defaultValue":"false","description":"Adds a divider before `endElement` when that slot has content."},{"name":"isTooltipMultiline","type":"boolean","required":false,"defaultValue":null,"description":"Preserves line breaks in the tooltip text."},{"name":"maxWidth","type":"number","required":false,"defaultValue":null,"description":"Maximum rendered chip width in pixels, including its leading and trailing padding and any outline border."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default div. Compose a native button or link explicitly; that owner supplies disabled and native interaction behavior."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Square or round corners."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the chip."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content before the label, such as an avatar or icon."},{"name":"tooltipContent","type":"string","required":false,"defaultValue":null,"description":"Tooltip text. Defaults to string children. Supply text explicitly for node content."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":null,"description":"Delay in milliseconds before the tooltip opens."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Position of the content tooltip."},{"name":"truncate","type":"boolean","required":false,"defaultValue":"true","description":"Truncates overflowing content with an ellipsis. Defaults to true."},{"name":"variant","type":"\"ghost\" | \"outline\" | \"plain\" | \"soft\" | \"solid\"","required":false,"defaultValue":"ghost","description":"Background and border treatment. Outline has a strong border, lighter resting fill and 8px inline padding. Plain has no resting fill or leading padding. Both use ghost hover and pressed feedback when clickable."},{"name":"weight","type":"\"medium\" | \"regular\"","required":false,"defaultValue":"regular","description":"Font weight of the content."}]}},{"name":"Tag","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Tag\ndescription: Label a category or attribute with a theme color and optional icon.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport TagReference from '/snippets/ui/generated/data-display/tag.mdx';\n\n## Overview\n\nUse `Tag` for categories, priorities, or other short attributes. Keep a text label so the meaning does not depend on color. Use [Status](/ui/primitives/data-display/status) when you need a state indicator and loading feedback.\n\n<StoryEmbed\n storyId=\"ui-data-display-tag--display\"\n title=\"Tag example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nexport const PriorityTag = () => <Tag color=\"red\">Urgent</Tag>;\n```\n\n`color` is required and accepts a theme color or `transparent`. The default element is always a `span`, including when a native click handler is supplied. Add a decorative icon with `startIcon`; the label supplies its accessible meaning.\n\n## Variants\n\n<StoryEmbed\n storyId=\"ui-data-display-tag--catalog\"\n title=\"Tag variants\"\n height={140}\n/>\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nexport const CategoryTags = () => (\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>\n <Tag color=\"blue\" variant=\"soft\">\n Customer\n </Tag>\n <Tag color=\"green\" variant=\"solid\">\n Partner\n </Tag>\n <Tag color=\"orange\" variant=\"outline\">\n Prospect\n </Tag>\n <Tag color=\"transparent\" variant=\"outline\" borderStyle=\"dashed\">\n Unassigned\n </Tag>\n </div>\n);\n```\n\n`soft` is the default treatment. `solid` emphasizes the label, `outline` adds a border, and `ghost` removes the background. Use `borderStyle=\"dashed\"` with `outline` and `weight=\"medium\"` for a stronger label.\n\n## Colors\n\n<StoryEmbed\n storyId=\"ui-data-display-tag--colors\"\n title=\"Tag theme colors\"\n height={240}\n/>\n\nKeep the label meaningful without relying on its color. The catalog compares the default soft treatment; the same palette is available to the other variants.\n\n## Filter by a tag\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\ntype CategoryFilterProps = {\n selected: boolean;\n onToggle: () => void;\n};\n\nexport const CategoryFilter = ({ selected, onToggle }: CategoryFilterProps) => (\n <Tag\n color=\"blue\"\n variant={selected ? 'solid' : 'outline'}\n render={<button type=\"button\" aria-pressed={selected} onClick={onToggle} />}\n >\n Customer\n </Tag>\n);\n```\n\nCompose an interactive owner through `render`. Put its click handler, native attributes, ref, and disabled state on that owner. A real button supplies focus, Enter, and Space activation. Selection state belongs to your application; use `aria-pressed` for a toggle and a visible treatment for the selected state. For navigation, render a link with its destination, such as `<a href=\"/records\" />`. Native owners retain Tag's appearance.\n\n## Long labels\n\nBy default, `truncate={true}` truncates constrained string labels and exposes their full text in a tooltip on hover. Set `truncate={false}` to keep the full label at its natural width without a tooltip, even when its parent is narrower. The parent layout owns wrapping, scrolling, and clipping.\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nexport const FullCategoryLabel = () => (\n <Tag color=\"green\" truncate={false}>\n Enterprise customer\n </Tag>\n);\n```\n\nNode children remain caller-owned content, so compose their text, translations, and intentional links directly.\n\n## Props\n\nTypes and defaults are generated from the public component types. Native attributes and event handlers are also accepted.\n\n<TagReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Tag","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/tag","props":[{"name":"borderStyle","type":"\"dashed\" | \"solid\"","required":false,"defaultValue":"solid","description":"Border style used by the outline variant."},{"name":"color","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"transparent\" | \"turquoise\" | \"violet\" | \"yellow\"","required":true,"defaultValue":null,"description":"Theme color for the tag, or `transparent` for an unfilled label."},{"name":"onClick","type":"MouseEventHandler<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Native click handler. Does not change the default span or add keyboard activation."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TagState>","required":false,"defaultValue":null,"description":"Replaces the default span. Compose a button or link to provide explicit interaction semantics."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative icon before the label. Hidden from assistive technology."},{"name":"truncate","type":"boolean","required":false,"defaultValue":"true","description":"Truncates constrained string labels and exposes the full text in a tooltip. Set to `false` to keep the full label at its natural width without a tooltip, even inside a narrower parent."},{"name":"variant","type":"\"ghost\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"soft","description":"Visual treatment of the tag background and border."},{"name":"weight","type":"\"medium\" | \"regular\"","required":false,"defaultValue":"regular","description":"Font weight of the label."}]}},{"name":"Status","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Status\ndescription: Show a named state with a colored indicator and optional loading feedback.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport StatusReference from '/snippets/ui/generated/data-display/status.mdx';\n\n## Overview\n\n`Status` combines a colored dot, a text label, and an optional loader. Use it for workflow or record states. Use [Tag](/ui/primitives/data-display/tag) for a category without the status indicator.\n\n<StoryEmbed\n storyId=\"ui-data-display-status--display\"\n title=\"Status example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Status } from 'twenty-ui/primitives/data-display';\n\nexport const RecordStatus = () => (\n <Status color=\"red\" weight=\"medium\">\n Urgent\n </Status>\n);\n```\n\n`color` is required and uses the theme palette. The label communicates the meaning independently of the color. The default element is always a `span`, including when a native click handler is supplied; `weight=\"medium\"` emphasizes its text.\n\n## Loading and announcements\n\n<StoryEmbed\n storyId=\"ui-data-display-status--loading\"\n title=\"Status while saving\"\n height={90}\n/>\n\n```tsx\nimport { Status } from 'twenty-ui/primitives/data-display';\n\ntype SaveStatusProps = { isSaving: boolean };\n\nexport const SaveStatus = ({ isSaving }: SaveStatusProps) => (\n <div role=\"status\">\n <Status color={isSaving ? 'blue' : 'green'} loading={isSaving}>\n {isSaving ? 'Saving' : 'Saved'}\n </Status>\n </div>\n);\n```\n\n`loading` shows a decorative loader after the label and defaults `aria-busy` to `true`. Supply `aria-busy` explicitly when the surrounding workflow owns that state. The component does not add a live region or change its text automatically. Keep a `role=\"status\"` container mounted when updates should be announced to assistive technology, and provide a label that describes the current state.\n\n## Change a state\n\n```tsx\nimport { Status } from 'twenty-ui/primitives/data-display';\n\ntype ChangeStatusActionProps = {\n isUpdating: boolean;\n onChangeStatus: () => void;\n};\n\nexport const ChangeStatusAction = ({\n isUpdating,\n onChangeStatus,\n}: ChangeStatusActionProps) => (\n <Status\n color=\"blue\"\n loading={isUpdating}\n render={\n <button\n type=\"button\"\n disabled={isUpdating}\n onClick={onChangeStatus}\n aria-label=\"Change record status\"\n />\n }\n >\n {isUpdating ? 'Updating' : 'In progress'}\n </Status>\n);\n```\n\nCompose an interactive owner through `render`. Put its click handler, native attributes, ref, and disabled state on that owner. A real button supplies focus, pointer, Enter, and Space activation. `Status.loading` displays progress; pass `disabled` to the button when the action should wait. For navigation, render a link with its destination, such as `<a href=\"/records\" />`. Native owners retain Status's appearance. Node children preserve caller-owned text, translations, and intentional links.\n\n## Props\n\nTypes and defaults are generated from the public component types. Native attributes and event handlers are also accepted.\n\n<StatusReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Status","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/status","props":[{"name":"color","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"turquoise\" | \"violet\" | \"yellow\"","required":true,"defaultValue":null,"description":"Theme color used for the status background, text, and loader."},{"name":"loading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a decorative loader after the label and defaults aria-busy to true. The caller owns announcements and disabled interaction."},{"name":"onClick","type":"MouseEventHandler<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Native click handler. Does not change the default span or add keyboard activation."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, StatusState>","required":false,"defaultValue":null,"description":"Replaces the default span. Compose a button or link to provide explicit interaction semantics."},{"name":"weight","type":"\"medium\" | \"regular\"","required":false,"defaultValue":"regular","description":"Font weight of the label."}]}},{"name":"Heading","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: Heading\ndescription: Render semantic headings with independent visual sizes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport HeadingReference from '/snippets/ui/generated/typography/heading.mdx';\n\n## Overview\n\n`Heading` renders an `h2` by default. Use `children` for its content, `level` for document structure, and `size` for appearance.\n\n<StoryEmbed\n storyId=\"ui-typography-heading--display\"\n title=\"Heading example\"\n height={90}\n/>\n\n## Usage\n\nChoose levels in document order. A smaller visual size does not change the level announced by assistive technology.\n\n```tsx\nimport { Heading } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceTitle = () => <Heading>Workspace settings</Heading>;\n```\n\nSizes `xs`, `sm`, `md`, `lg`, `xl`, and `xxl` use the matching font tokens. The larger sizes use `1.54rem` and `1.85rem`, respectively. All sizes keep semibold weight and a `1.1` line height. `Section.Header` and `Dialog.Title` accept the same size values. Headings have no outer margin; their surrounding layout owns spacing.\n\n## Color and composition\n\n<StoryEmbed\n storyId=\"ui-typography-heading--catalog\"\n title=\"Heading sizes and colors\"\n height={480}\n/>\n\nUse `color=\"secondary\"` for less prominent headings. `tertiary` is also available, but its contrast depends on the font size, theme, and background. Check readability when using it.\n\nNative attributes, styles, class names, and refs pass to the heading. Use `render` to compose with a custom element or component; that element is responsible for preserving heading semantics.\n\nFor a heading with supporting text or actions, use [Section](/ui/components/layout/section).\n\n## Props\n\n<HeadingReference />\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"Heading","entryPoint":"twenty-ui/primitives/typography","slug":"typography/heading","props":[{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Theme font color. Defaults to `primary`."},{"name":"level","type":"1 | 2 | 3 | 4 | 5 | 6","required":false,"defaultValue":"2","description":"Semantic heading level, from `h1` through `h6`. Does not change the visual size. Defaults to `2`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Visual font size from `xs` through `xxl`, independent of the heading level. Uses the matching font token. Defaults to `md`."}]}},{"name":"SettingsRow","entryPoint":"twenty-ui/components/settings","content":"---\ntitle: SettingsRow\ndescription: A labeled switch row with flat control props and native label composition.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SettingsRowReference from '/snippets/ui/generated/components/settings/settings-row.mdx';\n\n## Overview\n\n`SettingsRow` combines the appearance of [ListItem](/ui/primitives/navigation/list-item) with [Switch](/ui/primitives/input/switch). It renders a native label associated with its switch. Your application supplies the row content and owns any preference updates.\n\n<StoryEmbed\n storyId=\"ui-components-settingsrow--display\"\n title=\"Settings row example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { IconBell } from 'twenty-ui/icon';\n\nexport const NotificationSetting = () => (\n <SettingsRow startElement={<IconBell aria-hidden />}>\n Notifications\n </SettingsRow>\n);\n```\n\n## Visual options\n\nCompare switch sizes and checked, disabled, and read-only states.\n\n<StoryEmbed\n storyId=\"ui-components-settingsrow--catalog\"\n title=\"Settings row sizes and states\"\n height={520}\n/>\n\n## Configure the switch\n\nPass [Switch props](/ui/primitives/input/switch) directly to `SettingsRow`. Checked state, event details, disabled and read-only behavior, size, native form configuration, handlers, refs, and render composition configure the switch. `children` supplies the visible row label.\n\nUse `checked` and `onCheckedChange` when your application owns the value. The handler receives the next checked state and Base UI event details. Clicking the label or switch invokes it once. Call `eventDetails.cancel()` to reject a change, and keep your controlled value unchanged when the change is canceled.\n\n```tsx\nimport { useState } from 'react';\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { IconBell } from 'twenty-ui/icon';\n\nexport const NotificationSetting = () => {\n const [enabled, setEnabled] = useState(false);\n\n return (\n <SettingsRow\n startElement={<IconBell aria-hidden />}\n checked={enabled}\n onCheckedChange={setEnabled}\n >\n Notifications\n </SettingsRow>\n );\n};\n```\n\nUse `defaultChecked` for an uncontrolled setting. Keyboard users focus the switch and press Space. `disabled` disables the control and applies the row's disabled appearance. `readOnly` prevents changes while keeping the switch focusable.\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const WorkspaceSettings = () => (\n <>\n <SettingsRow disabled>Notifications</SettingsRow>\n <SettingsRow readOnly defaultChecked>\n Activity history\n </SettingsRow>\n </>\n);\n```\n\n## Row content and accessible text\n\n`children`, `startElement`, and `description` accept caller-owned nodes. The children supply the switch's accessible name, and the description supplies its accessible description. Keep content inside the label non-interactive. Use [ListItemButton](/ui/components/navigation/list-item-button) for action rows, or compose [ListItem](/ui/primitives/navigation/list-item) with a link for navigation.\n\n<StoryEmbed\n storyId=\"ui-components-settingsrow--with-description\"\n title=\"Settings row with a description\"\n height={110}\n/>\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const WeeklyDigestSetting = () => (\n <SettingsRow defaultChecked description=\"Sent every Monday\" name=\"digest\">\n Weekly digest\n </SettingsRow>\n);\n```\n\nSet `aria-label`, `aria-labelledby`, or `aria-describedby` to supply your own accessible text for the switch. An explicit `aria-label` replaces the generated name association; explicit `aria-labelledby` and `aria-describedby` values replace the corresponding generated associations.\n\n## Native targets and composition\n\nThe ordinary native props configure the control. Label customization has two explicit names:\n\n| Props | Target |\n| --------------------------------------------------------------------------------------- | --------------------------------------- |\n| Native attributes, handlers, `className`, `style`, `ref`, and `render` | The visible Switch root |\n| `inputRef`, `name`, `value`, `uncheckedValue`, `required`, and `form` | The Switch's underlying native checkbox |\n| `labelRef` and attributes, handlers, classes, and styles supplied through `labelRender` | The outer native label |\n\nThe label's `htmlFor` is managed internally and follows `id`, or a generated control ID when no ID is supplied. With the default Switch composition, this ID identifies the underlying checkbox. With `nativeButton`, it identifies the visible button. `ref` targets the visible root in both cases.\n\nUse `labelRender` to customize the row's native label. Preserve a label element and forward the render callback props to your element. Its `props.children` contains the complete row, including the switch. Element composition merges its classes and styles with the row's defaults.\n\n```tsx\nimport { useRef } from 'react';\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const ComposedNotificationSetting = () => {\n const labelRef = useRef<HTMLLabelElement>(null);\n const controlRef = useRef<HTMLElement>(null);\n const inputRef = useRef<HTMLInputElement>(null);\n\n return (\n <SettingsRow\n id=\"notification-control\"\n ref={controlRef}\n inputRef={inputRef}\n nativeButton\n render={<button />}\n labelRef={labelRef}\n labelRender={<label id=\"notification-row\" data-setting=\"notifications\" />}\n >\n Notifications\n </SettingsRow>\n );\n};\n```\n\n`onClick` receives control clicks. Native handlers supplied through `labelRender` receive label events and bubbled control events. Calling `preventDefault()` on a label click prevents its native control activation. Use `onCheckedChange` for preference updates, rather than inferring state from a label click.\n\nThe switch defaults to `size=\"sm\"`; use `\"md\"` for a larger switch. The row height stays the same. `focused` applies the row's highlighted appearance without moving keyboard focus. `className`, `style`, and `render` accept Switch state callbacks and customize the control. Supply label classes and styles through `labelRender` to customize the row.\n\n## Front component renderer\n\nInside a front component, use the native button composition for a switch nested in the row's label:\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const FrontComponentNotificationSetting = () => (\n <SettingsRow nativeButton render={<button />}>\n Notifications\n </SettingsRow>\n);\n```\n\nThis composition activates once when clicking the label or control. The renderer's asynchronous event bridge cannot cancel the host label's default activation in time for a span-based control, which can produce duplicate change callbacks on a direct control click. Native form validation attributes such as `required` are also filtered by the current renderer. Standalone `SettingsRow` retains the full Switch form contract.\n\n## Forms and reset\n\n`name`, `value`, and `required` configure the underlying checkbox for form submission and validation. A checked switch submits its value. An unchecked switch omits the value unless `uncheckedValue` is supplied. Use `form` to associate the input with a form outside the row's parent tree.\n\nFor controlled form reset, restore the application-owned checked value in the form's `onReset` handler. Base UI 1.8 does not restore uncontrolled switch state on native form reset. `SettingsRow` preserves this upstream behavior.\n\n```tsx\nimport { useState } from 'react';\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const NotificationPreferences = () => {\n const [enabled, setEnabled] = useState(true);\n\n return (\n <form onReset={() => setEnabled(true)}>\n <SettingsRow\n checked={enabled}\n onCheckedChange={setEnabled}\n name=\"notifications\"\n value=\"enabled\"\n uncheckedValue=\"disabled\"\n >\n Notifications\n </SettingsRow>\n <Button type=\"reset\">Reset</Button>\n </form>\n );\n};\n```\n\n## Props\n\n<SettingsRowReference />\n\n<PageBanner illustration=\"settings\" />\n","api":{"name":"SettingsRow","entryPoint":"twenty-ui/components/settings","slug":"components/settings/settings-row","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the switch is currently active.\n\nTo render an uncontrolled switch, use the `defaultChecked` prop instead."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Visible label and default accessible name of the switch. Use non-interactive node content."},{"name":"className","type":"string | ((state: SwitchRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Customizes the visible Switch root and accepts a Switch state callback."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the switch is initially active.\n\nTo render a controlled switch, use the `checked` prop instead."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Non-interactive supporting node content, used as the default accessible description of the switch."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"focused","type":"boolean","required":false,"defaultValue":"false","description":"Applies the highlighted row style without moving keyboard focus."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the switch is rendered outside the form."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Identifies the associated checkbox, or the visible root with nativeButton. The label association follows this ID."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Targets the underlying native checkbox."},{"name":"labelRef","type":"Ref<HTMLLabelElement>","required":false,"defaultValue":null,"description":"Targets the outer native label."},{"name":"labelRender","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the outer native label with its complete composed row children. Preserve a label element and forward its props to retain control association."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Receives the next checked value and Base UI event details. Controlled callers own accepted state updates; cancellation prevents a change."},{"name":"onClick","type":"((event: BaseUIEvent<MouseEvent<HTMLSpanElement, MouseEvent>>) => void)","required":false,"defaultValue":null,"description":"Native click handler for the visible Switch root."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to activate or deactivate the switch."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Targets the visible Switch root, which defaults to a span."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>","required":false,"defaultValue":null,"description":"Customizes the visible Switch root with control props and Switch state. Use nativeButton when composing a button."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must activate the switch before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the switch. Defaults to sm."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Non-interactive node content before the label."},{"name":"style","type":"CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Customizes the visible Switch root and accepts a Switch state callback."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is off.\nBy default, unchecked switches do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is on.\nBy default, switch submits the \"on\" value, matching native checkbox behavior."}]}},{"name":"PhoneCountryPicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: PhoneCountryPicker\ndescription: A complete phone country picker and composable parts sharing country data and selection.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport PhoneCountryPickerReference from '/snippets/ui/generated/components/input/phone-country-picker.mdx';\n\n## Overview\n\n`PhoneCountryPicker` combines a country flag trigger, popup, search and calling-code choices. Use the complete component for ordinary selection, or compose `Root`, `Trigger` and `Options` with [Dropdown](/ui/components/navigation/dropdown) when you need a custom popup. Both forms share the same prepared countries and selection.\n\n<StoryEmbed\n storyId=\"ui-input-phonecountrypicker--display\"\n title=\"Phone country selection\"\n height={260}\n/>\n\n## Usage\n\nSupply your own country data and a trigger accessible name. Use `value` with `onValueChange` for controlled selection, or `defaultValue` for uncontrolled selection. `null` represents no selected country.\n\n```tsx\nimport { useState } from 'react';\nimport {\n PhoneCountryPicker,\n type PhoneCountryOption,\n} from 'twenty-ui/components/input';\n\nconst COUNTRIES: PhoneCountryOption[] = [\n { value: 'FR', label: 'France', callingCode: '33', flag: '🇫🇷' },\n { value: 'GB', label: 'United Kingdom', callingCode: '44', flag: '🇬🇧' },\n { value: 'US', label: 'United States', callingCode: '1', flag: '🇺🇸' },\n];\n\nexport const PhoneCountryExample = () => {\n const [value, setValue] = useState<string | null>('FR');\n\n return (\n <PhoneCountryPicker\n aria-label=\"Phone country\"\n countries={COUNTRIES}\n value={value}\n onValueChange={setValue}\n contentProps={{ width: 280 }}\n optionsProps={{\n searchLabel: 'Search countries',\n listLabel: 'Phone countries',\n emptyLabel: 'No countries found',\n }}\n />\n );\n};\n```\n\nEach `PhoneCountryOption` has a unique stable `value`, a localized country `label`, a digits-only `callingCode` without the leading plus sign, and a decorative `flag` node. It may also be `disabled`. Values are caller-owned identifiers, such as ISO country codes, and are returned unchanged. Labels, flags and calling codes are presentation data and do not become the selected identifier.\n\nThe picker adds the plus sign and isolates calling codes left to right in option rows and overflow tooltips, including in right-to-left interfaces. Supply countries in the order you want them displayed. The selected country appears first while it matches the query; the remaining matches retain their supplied order.\n\n## Compound composition\n\nThis is a breaking API change for existing compound callers. Add `PhoneCountryPicker.Root` around `Dropdown.Root`, move `countries`, `value` and `onValueChange` from `Options` to `Root`, and remove `Trigger.country`. Both parts now require `Root` and derive the selected country from it.\n\n`Root` owns countries and the controlled or uncontrolled selection. Put the shared `Dropdown.Root` inside it and compose the trigger, content and options. `Trigger` derives its selected flag and accessible description from `Root`; `Options` reads the same data and selection. Do not supply another country or selected value to those parts.\n\n```tsx\nimport {\n PhoneCountryPicker,\n type PhoneCountryOption,\n} from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst COUNTRIES: PhoneCountryOption[] = [\n { value: 'FR', label: 'France', callingCode: '33', flag: '🇫🇷' },\n { value: 'GB', label: 'United Kingdom', callingCode: '44', flag: '🇬🇧' },\n];\n\n<PhoneCountryPicker.Root countries={COUNTRIES} defaultValue=\"FR\">\n <Dropdown.Root type=\"picker\">\n <PhoneCountryPicker.Trigger\n aria-label=\"Phone country\"\n render={<Button variant=\"outline\" />}\n />\n <Dropdown.Content width={320}>\n <PhoneCountryPicker.Options\n searchLabel=\"Search countries\"\n listLabel=\"Phone countries\"\n emptyLabel=\"No countries found\"\n />\n </Dropdown.Content>\n </Dropdown.Root>\n</PhoneCountryPicker.Root>;\n```\n\nKeep one root per selector. The shared Dropdown owns opening, popup placement, pages, focus and search navigation. Use `dropdownProps` and `contentProps` on the complete picker, or configure the Dropdown parts directly in compound usage.\n\n## Search and selection\n\nSearch matches substrings of the supplied country labels, stable identifiers and calling codes. Labels and identifiers use the shared `normalizeSearchText` normalization: lowercase text, Unicode NFD decomposition and script-aware accent handling. For example, `reunion` matches `Réunion` and `gb` matches a `GB` identifier. Meaningful distinctions in scripts are preserved according to that helper. Surrounding query whitespace is trimmed; internal whitespace is preserved. For calling-code search, one leading plus sign is optional, so `44`, `+44` and `\" +44 \"` match the supplied calling code `44`. Search does not parse a full phone number or infer a country from it.\n\n`onValueChange(value, eventDetails)` receives the requested identifier and the shared `Dropdown.SelectionGroup` details: `reason`, the native `event`, the selected option `trigger`, `cancel()` and `isCanceled`. Call `cancel()` before updating controlled state to reject the request. A canceled request preserves uncontrolled selection and leaves the popup open. Set `closeOnSelect={false}` to keep it open after an accepted selection. Selection changes do not modify any phone input value.\n\nSet `disabled` on the complete picker or `Root` to disable its trigger, search and selection. A disabled country stays visible and cannot be selected. `Trigger.disabled` and `Options.disabled` can additionally disable those individual parts.\n\n## Native targets and labels\n\nThe complete picker's native attributes, event handlers, `className`, `style`, `ref`, `render` and optional `children` target its trigger. `children` replaces the default flag or world icon and chevron. `contentProps` targets `Dropdown.Content`; `optionsProps` targets the options root div and supplies `searchLabel`, `listLabel` and `emptyLabel`. In compound usage, native props, refs and render composition target the corresponding `Trigger` button or `Options` div. `Root` renders no DOM node.\n\nSupply localized country labels and the required trigger `aria-label`. The selected country label describes the trigger, while its flag and chevron are decorative. An empty selection shows a world icon. The popup takes the trigger name unless a `Dropdown.Title` or an explicit content label names it. `searchLabel` defaults to `Search` and names both the search field and its placeholder. `listLabel` defaults to `Countries` and names the listbox independently. `emptyLabel` defaults to `No results`.\n\n## Phone input integration\n\nThe picker ships without a country catalog, flag asset package or phone-input runtime. The frontend adapter owns phone parsing, validation, formatting, editing drafts and persistence. Map the phone library's selected country to `Root.value` or the complete picker's `value`, and map country changes back through one callback. Keep the phone text in its existing owner when changing or clearing a country, or applying an external selected-country update.\n\nNative form submission, reset, required, read-only and Field integration for this custom picker are deferred. The complete picker forwards native trigger attributes according to the Dropdown button contract.\n\n## Front component renderer\n\nThe React and Preact gallery fixtures include the complete picker and compound composition. Portal placement, geometry, scrolling, dismissal and focus belong to the shared Dropdown and renderer integration. The picker does not introduce a separate renderer runtime.\n\n## Props\n\n<PhoneCountryPickerReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"PhoneCountryPicker","entryPoint":"twenty-ui/components/input","slug":"components/input/phone-country-picker","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Required accessible name for the country selector trigger."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trigger content replacing the default country flag or world icon and chevron."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Closes the dropdown after an accepted selection. Defaults to true."},{"name":"contentProps","type":"Omit<DropdownContentProps, \"children\">","required":false,"defaultValue":null,"description":"Props for the internally assembled Dropdown.Content, including its accessible name, placement, width and popup ref."},{"name":"countries","type":"readonly PhoneCountryOption[]","required":true,"defaultValue":null,"description":"Prepared choices with a unique stable value, localized label, digits-only calling code without a plus sign, decorative flag node and optional disabled state. Matching choices retain their supplied order after the selected country."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":null,"description":"Initial uncontrolled country identifier. Omit it or use null to start empty."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables the trigger, search and country selection."},{"name":"dropdownProps","type":"Omit<DropdownRootProps, \"children\" | \"type\" | \"multiple\">","required":false,"defaultValue":null,"description":"Props for the internally assembled Dropdown.Root, including controlled open state and open-change events. The picker fixes its type to picker."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested country identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"optionsProps","type":"PhoneCountryPickerOptionsProps","required":false,"defaultValue":null,"description":"Props for the options root div, including native attributes, ref, render, searchLabel, listLabel and emptyLabel. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Composes the trigger with an element or render callback. Native attributes, handlers, className, style and ref target the trigger."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled country identifier. Use null to clear the selection. Labels and calling codes do not replace this value."}],"parts":[{"name":"Root","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"A Dropdown.Root with type=\"picker\", its Trigger, Content and Options. Root shares prepared data and selection and renders no DOM node."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":"true","description":"Closes the composed Dropdown after an accepted selection. Defaults to true."},{"name":"countries","type":"readonly PhoneCountryOption[]","required":true,"defaultValue":null,"description":"Prepared choices shared by Trigger and Options, with unique stable values, localized labels, digits-only calling codes without a plus sign, decorative flag nodes and optional disabled states."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled country identifier. Omit it or use null to start empty."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the composed trigger, search and country selection."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled country identifier shared by the parts. Use null to clear the selection."}]},{"name":"Trigger","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Required accessible name for the country selector button."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trigger content replacing the selected country flag or empty world icon and chevron. The selected label comes from Root."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables the native trigger button in addition to Root.disabled."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Composes the Dropdown trigger with an element or render callback. Native attributes, handlers, className, style and ref target this element."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Options","props":[{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables search and selection in addition to Root.disabled."},{"name":"emptyLabel","type":"string","required":false,"defaultValue":"No results","description":"Status message shown when no country label, identifier or calling code matches. Defaults to No results."},{"name":"listLabel","type":"string","required":false,"defaultValue":"Countries","description":"Accessible name of the country listbox, separate from the search field. Defaults to Countries."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the options root div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Composes the non-interactive options root with an element or render callback. Native attributes, handlers, className, style and ref target this element. searchLabel names the internal search input."},{"name":"searchLabel","type":"string","required":false,"defaultValue":"Search","description":"Accessible name and placeholder of the country search field. Defaults to Search. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed."}]}]}},{"name":"Dropdown","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: Dropdown\ndescription: Action menus, searchable pickers, and form panels with shared presentation and interaction.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DropdownReference from '/snippets/ui/generated/components/navigation/dropdown.mdx';\n\n## Overview\n\n`Dropdown` combines a positioned popup, visual rows, keyboard navigation, focus, and dismissal. Your application owns data, filtering, fetching and pagination. `SelectionGroup` owns independent selection values inside the popup. Import it from `twenty-ui/components`.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--display\"\n title=\"Dropdown actions\"\n height={420}\n/>\n\nDropdown.Content accepts numeric offsets or functions for `sideOffset` and `alignOffset`. Offset functions receive the anchor and popup dimensions, side, and alignment. Use them to preserve an anchored field picker’s overlap when the cell is scaled.\n\n## Usage\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { IconArchive, IconCopy, IconDownload } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const RecordActions = () => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Record actions</Button>} />\n <Dropdown.Content aria-label=\"Record actions\" width={240}>\n <Dropdown.Section>\n <Dropdown.ActionItem startIcon={<IconCopy />}>\n Duplicate\n </Dropdown.ActionItem>\n <Dropdown.Submenu>\n <Dropdown.SubmenuTrigger startIcon={<IconDownload />}>\n Export\n </Dropdown.SubmenuTrigger>\n <Dropdown.Content aria-label=\"Export formats\">\n <Dropdown.Section>\n <Dropdown.ActionItem>CSV</Dropdown.ActionItem>\n <Dropdown.ActionItem>Excel</Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Submenu>\n </Dropdown.Section>\n <Dropdown.Separator />\n <Dropdown.Section>\n <Dropdown.ActionItem startIcon={<IconArchive />}>\n Archive\n </Dropdown.ActionItem>\n <Dropdown.ActionItem\n render={\n <a href=\"#dropdown-documentation\" aria-label=\"Documentation\" />\n }\n >\n Documentation\n </Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n## Choose an interaction type\n\nSet `type` on `Dropdown.Root` to match the popup's contents.\n\n| Type | Content | Interaction |\n| -------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |\n| `menu` | Commands and navigation links | Menu semantics with arrow navigation and typeahead. |\n| `picker` | Search, selectable values, and optional commands | A dialog containing search, selectable listboxes and optional commands. Arrow keys navigate result rows. |\n| `panel` | Inputs, forms, and supporting actions | A dialog with native input behavior and Tab navigation. |\n\nPickers allow creation actions and independent selection groups in the same page, in any order. Each picker group is a listbox, and its options expose `aria-selected`. Menu groups use checked radio or checkbox menu items. Panel groups use buttons with `aria-pressed`. Commands retain their mode’s action semantics. Give each group and `Search` an accessible name. This custom picker is not a native Combobox.\n\n`Content` takes its accessible name from `Trigger`, or from `SubmenuTrigger` in a submenu. Pass `aria-label` on `Content` when the trigger shows a value, such as the selected option, or when the root has no trigger. An explicit `aria-label` or `aria-labelledby`, and a `Title` inside a `Header`, take precedence over the trigger name.\n\n[Select](/ui/primitives/input/select) and [Popover](/ui/primitives/surfaces/popover) remain available for direct composition.\n\n## Anatomy\n\n```text\nDropdown.Root\n├── Dropdown.Trigger\n└── Dropdown.Content\n ├── Dropdown.Header\n │ ├── Dropdown.Close\n │ └── Dropdown.Title\n ├── Dropdown.Search\n └── Dropdown.Section\n ├── Dropdown.ActionItem\n └── Dropdown.SelectionGroup\n └── Dropdown.OptionItem\n```\n\n`Content` includes the portal and positioner. Use `width`, `side`, `align`, `sideOffset`, and `alignOffset` to control placement, and `collisionPadding` to keep the popup further from the edges of the viewport before it shifts or flips (5 pixels by default). `Section` groups rows with shared spacing, and `Separator` divides sections. A `scrollable` Section caps its height and scrolls; nest labelled sections inside it to scroll them as one list. Rows use [ListItem](/ui/primitives/navigation/list-item) for their appearance.\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const RecordActions = ({ onDuplicate }: { onDuplicate: () => void }) => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Record actions</Button>} />\n <Dropdown.Content>\n <Dropdown.Section>\n <Dropdown.ActionItem startIcon={<IconCopy />} onClick={onDuplicate}>\n Duplicate\n </Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\nPass custom trigger elements through `render` so the trigger remains one interactive element. Custom components must forward the supplied props and ref. `ActionItem` also accepts `render` for links.\n\n## Item actions\n\n`ActionItem` and `OptionItem` accept `actions` for trailing controls, such as a tab's edit button. Use them in `picker` and `panel` pages only: a `menu` may only contain menu items, so it cannot hold other controls. Set `actionsVisibility=\"always\"` to keep them visible; the default is `\"hover\"`. Secondary controls render beside the primary row control and activate independently: they do not close the popup, so close it from the action's handler when needed. The `render` prop and ref still apply to the primary control, so it can also serve as a drag handle.\n\nUse `tabIndex={-1}` for a pointer-only secondary action that has a separate keyboard alternative. Keyboard navigation continues to focus and activate the primary control.\n\n## Headers\n\n`Header` lays out a row at the top of the popup. Put a `Title` in it to name the popup after the title instead of the trigger. `Close` closes the popup the same way an outside press does. It renders an icon button with an X by default, so give it an `aria-label`, or pass `render` and children for another control. Other controls, such as a button that returns to a previous step, can sit in the same row. Use `Dropdown.Back` when navigating the root's page history.\n\n## Search and selection\n\n`Search` provides the input and navigation into the result rows. Pass `value` and `onValueChange`; compute or fetch matching results in your application. Render `Loading` while a request is pending and `Empty` when no results match. Both accept caller-provided status text.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--picker-documentation\"\n title=\"Searchable picker with inline creation\"\n height={420}\n/>\n\nWrap selectable options in `SelectionGroup` and give each option a stable `value` unique within the group. An uncontrolled group also needs an `id` unique within its dropdown tree, including submenus. Independently nested `Root` components keep their own selection store. Single selection uses a string or `null` for no selection. Multiple selection uses an array, including `[]` for no selection.\n\n```tsx\nimport { useState } from 'react';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const PersonPicker = () => {\n const [search, setSearch] = useState('');\n const [selectedPerson, setSelectedPerson] = useState<string | null>(null);\n const people = ['Ada Lovelace', 'Grace Hopper'].filter((person) =>\n person.toLowerCase().includes(search.toLowerCase()),\n );\n\n return (\n <Dropdown.Root type=\"picker\">\n <Dropdown.Trigger render={<Button>Choose person</Button>} />\n <Dropdown.Content>\n <Dropdown.Search\n aria-label=\"Search people\"\n value={search}\n onValueChange={setSearch}\n />\n <Dropdown.SelectionGroup\n id=\"person\"\n aria-label=\"Person\"\n value={selectedPerson}\n onValueChange={setSelectedPerson}\n >\n {people.map((person) => (\n <Dropdown.OptionItem key={person} value={person}>\n {person}\n </Dropdown.OptionItem>\n ))}\n </Dropdown.SelectionGroup>\n </Dropdown.Content>\n </Dropdown.Root>\n );\n};\n```\n\nPass `value` and `onValueChange` for controlled selection. Omitting `value`, or passing `undefined`, leaves selection uncontrolled; `defaultValue` sets its initial value. An uncontrolled group defaults to `null`, or `[]` with `multiple`. Its stable `id` preserves selection across close and reopen and across page navigation. Removing or filtering an option does not clear its selected identifier or emit a change; the option is selected again when it returns. Use a controlled value when the application needs to clear unavailable choices.\n\nEach group changes independently. An option commits to its nearest group, while the active page supplies one ordered collection for arrow navigation across groups and action rows. Repeated activation of a selected single option preserves its value without another change callback. Multiple activation toggles the option in the array.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--selection-groups-documentation\"\n title=\"Independent owner and watcher selections\"\n height={440}\n/>\n\nSingle selection closes by default; multiple selection stays open. `SelectionGroup.closeOnSelect` changes the group default, and `OptionItem.closeOnSelect` overrides it for one option. Action rows use `closeOnClick` independently. A cancelled change preserves the previous selection and does not automatically close the popup.\n\n`onValueChange` receives the next value and event details with `event`, `reason`, `trigger`, `cancel()` and `isCanceled`. The reason is `item-press`, and `event` is the original activation event. `OptionItem.onSelect` receives the same details before its owner commits. Call `cancel()` in either callback to prevent selection and automatic closing.\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\n<Dropdown.SelectionGroup\n id=\"watchers\"\n aria-label=\"Watchers\"\n multiple\n defaultValue={[]}\n onValueChange={(value, eventDetails) => {\n if (value.length > 3) {\n eventDetails.cancel();\n }\n }}\n>\n <Dropdown.OptionItem value=\"ada\">Ada Lovelace</Dropdown.OptionItem>\n <Dropdown.OptionItem value=\"grace\">Grace Hopper</Dropdown.OptionItem>\n</Dropdown.SelectionGroup>;\n```\n\nSearch receives focus when the picker opens. Without search, the first enabled selected option receives focus, or the first enabled row when no selected option is present. While `Search` has focus and a nonempty query, the first eligible `OptionItem` across selection groups is highlighted and Enter activates it. Action rows are never picked this way. ArrowDown moves focus to the first enabled row, including actions. Leaving search clears the preview and `aria-activedescendant`, even when the popup stays open. Returning to search restores the preview for the current query.\n\nEnter does nothing for an empty or whitespace-only query, or when no eligible option remains. Composing text with an input method does not activate an option or move focus with arrow keys. When rows are pinned above matches, such as the current value or a \"none\" row, render them only when they match the search text. The popup stays open when no option matches. Filtering remains caller-owned.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--multiple-selection-documentation\"\n title=\"Multiple selection\"\n height={420}\n/>\n\nStandalone `OptionItem` still accepts `selected` and `onSelect` for callers that own selection themselves. Grouped options derive selection from the group value; do not duplicate that state on the option. Custom selection groups do not provide native form submission, reset, required validation, read-only behavior or Field integration. Use [Select](/ui/primitives/input/select) when those native form contracts are needed.\n\n## Icon grids\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--icon-grid-documentation\"\n title=\"Icon grid with selected cell styling\"\n height={360}\n/>\n\nSet `columns` on `Section` to lay out items in equal-width grid columns. The same count drives keyboard navigation: Left and Right move within a row, while Up and Down move between rows. Navigation skips disabled options and follows the reading direction. When no enabled option is left in the column, Up and Down move to the nearest enabled option of the next row. Up from the first row returns to the search field when no earlier section exists. A short final row uses its last item when the requested column is missing. Inside a submenu, the backward arrow closes the submenu when no enabled option remains to its left.\n\nRender each icon as an `OptionItem` with an accessible label and an icon button through `render`. Use `indicator=\"none\"` to show selection through the button background. The `render` callback receives `{ selected, multiple, disabled }` state; use it to style a selected cell and forward the supplied props and ref.\n\n```tsx\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { IconCalendar } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const IconGrid = () => (\n <Dropdown.Root type=\"picker\">\n <Dropdown.Trigger render={<Button>Choose icon</Button>} />\n <Dropdown.Content>\n <Dropdown.SelectionGroup\n id=\"icon\"\n aria-label=\"Icon\"\n defaultValue=\"calendar\"\n >\n <Dropdown.Section columns={5}>\n <Dropdown.OptionItem\n value=\"calendar\"\n aria-label=\"Calendar\"\n indicator=\"none\"\n nativeButton\n render={(props, state) => (\n <LightIconButton\n // oxlint-disable-next-line react/jsx-props-no-spreading\n {...props}\n size=\"md\"\n color={state.selected ? 'accent' : 'neutral'}\n aria-label=\"Calendar\"\n >\n <IconCalendar />\n </LightIconButton>\n )}\n />\n </Dropdown.Section>\n </Dropdown.SelectionGroup>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n## Keyboard focus\n\nIn `menu` and `picker` pages, the rows form a single Tab stop. Arrow keys move focus across sections, actions and options, and Home and End move to the first and last enabled rows unless the search field has focus. Moving focus never selects an option; Enter or Space activates the focused row. Tabbing back to the rows returns to the last focused row, or to the first enabled row once that row is gone. Search, `Back` beside a search, header buttons and other controls inside the popup keep their own Tab stops.\n\nTab and Shift+Tab close a `menu`, along with its parent menus when focus is in a submenu. In a `picker`, Tab moves through the popup's controls and closes the popup when focus leaves it. A `panel` keeps the native Tab order of its controls.\n\n## Pages and submenus\n\nUse `Page` for navigation that replaces the contents of the same popup. Wrap the first page in `Page id=\"root\"`, or choose another initial page with `defaultPage`. Set `page` on an action to navigate without closing. `Back` returns to the previous page and restores focus to its invoking row.\n\nPages mount when first visited and stay mounted for that open session. Returning to a page preserves its local search, form drafts and scrollable sections. Inactive pages are hidden and inert: they do not participate in keyboard navigation, focus or the accessibility tree, and their nested Dropdown popups are inactive.\n\nReopening starts a new session at `defaultPage` with fresh content, including when `Content.keepMounted` is set or the popup reopens during its exit transition. Page history, local search and drafts reset. The closing page remains mounted during its exit transition.\n\nUncontrolled `SelectionGroup` values stay stored in `Root` under each group's stable `id` and survive reopening. Caller-controlled values remain caller-owned. For example, a search value stored above `Content` stays unchanged until the caller updates it. Put temporary search or draft state in a component inside `Content` or `Page` when it should reset with the session; keep durable application state above `Content`.\n\nA page can override the root's `type`. For example, an action menu can open a searchable picker page or a form panel. Search receives focus when entering a searchable page; other pages focus their first row after `Back`.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--pages-documentation\"\n title=\"Menu to picker page navigation\"\n height={420}\n/>\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const FilterMenu = () => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Filters</Button>} />\n <Dropdown.Content>\n <Dropdown.Page id=\"root\">\n <Dropdown.Section>\n <Dropdown.ActionItem page=\"status\">Status</Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Page>\n <Dropdown.Page id=\"status\" type=\"picker\">\n <Dropdown.Back>Filters</Dropdown.Back>\n <Dropdown.Section>\n <Dropdown.SelectionGroup id=\"status\" aria-label=\"Status\">\n <Dropdown.OptionItem value=\"active\">Active</Dropdown.OptionItem>\n <Dropdown.OptionItem value=\"archived\">Archived</Dropdown.OptionItem>\n </Dropdown.SelectionGroup>\n </Dropdown.Section>\n </Dropdown.Page>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\nTo navigate from code, call `useDropdownPage` in a component rendered inside the root. It returns the current `page`, `goToPage(page)`, `goBack()`, `canGoBack` and `isActive`. Inside a page, `isActive` is true only while that page is active and its dropdown is open. Use `isActive` to show a page's custom portaled popups so they disappear when the page becomes inactive or the dropdown closes. For example, an option can return to the previous page after a selection while the popup stays open:\n\n```tsx\nimport { Dropdown, useDropdownPage } from 'twenty-ui/components/navigation';\n\nexport const StatusOptions = ({\n status,\n onStatusChange,\n}: {\n status: string | null;\n onStatusChange: (status: string | null) => void;\n}) => {\n const { goBack } = useDropdownPage();\n\n return (\n <Dropdown.SelectionGroup\n id=\"status\"\n aria-label=\"Status\"\n value={status}\n closeOnSelect={false}\n onValueChange={(value) => {\n onStatusChange(value);\n goBack();\n }}\n >\n {['Active', 'Archived'].map((option) => (\n <Dropdown.OptionItem key={option} value={option}>\n {option}\n </Dropdown.OptionItem>\n ))}\n </Dropdown.SelectionGroup>\n );\n};\n```\n\nUse `Submenu` with `SubmenuTrigger` and a nested `Content` for a side-by-side menu. Arrow Right enters the submenu; Arrow Left returns to its parent. Selecting a closing action closes the whole dropdown.\n\n```text\nDropdown.Content\n└── Dropdown.Submenu\n ├── Dropdown.SubmenuTrigger\n └── Dropdown.Content\n └── Dropdown.ActionItem\n```\n\n## Independent nested pickers\n\nPlace another `Dropdown.Root` inside `Content` when a control opens its own picker, such as a sort direction selector. Selecting an inner option closes only that picker and restores focus to its trigger. Escape and outside presses dismiss one layer at a time. Use `Submenu` for commands that should close the entire menu tree when selected.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--nested-documentation\"\n title=\"Sort picker with a nested direction picker\"\n height={420}\n/>\n\n## Panels and controlled state\n\nUse `type=\"panel\"` for form inputs. Input interaction keeps the panel open; a save action can close it. Own `open` and `onOpenChange` when another component or a shortcut needs to open the dropdown. Keep that state with the feature that coordinates the interaction.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--panel-documentation\"\n title=\"Controlled form panel\"\n height={420}\n/>\n\nEscape dismisses the popup and restores focus to its trigger. Outside interaction also dismisses it, and the click that dismisses it doesn't activate what it lands on. Keys pressed inside the popup stay inside it, except Ctrl or Cmd shortcuts the dropdown doesn't handle, so page-level shortcuts keep working. `Content` accepts focus and portal options from Popover, including an explicit return-focus target for editor workflows.\n\n## Dismissal\n\nEscape, a press outside the popup and Tab out of it close the dropdown. Pass `onEscapeKeyDown` or `onInteractOutside` to `Root` to react before it closes, and call `event.preventDefault()` to keep it open. `event.target` is the element pressed outside, or `null` when focus leaves with Tab, and `event.type` is the type of the DOM event that triggered it, such as `touchmove` for a swipe outside the popup. A prevented outside press still reaches the element it lands on.\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const ViewSettings = ({ isEditing }: { isEditing: boolean }) => (\n <Dropdown.Root\n type=\"panel\"\n onInteractOutside={(event) => {\n if (isEditing) {\n event.preventDefault();\n }\n }}\n >\n <Dropdown.Trigger render={<Button>View settings</Button>} />\n <Dropdown.Content>\n <Dropdown.ActionItem>Save view</Dropdown.ActionItem>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n## Anchoring without a trigger\n\nA root can open without a `Trigger`, for example as a context menu. Control it with `open` and `onOpenChange`, and pass `anchor` to `Content`: an element, a ref, or a virtual element that returns a rectangle in viewport coordinates. Give `Content` an `aria-label`, since there is no trigger to name it after. On close, focus returns to the element that was focused when the popup opened.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--context-menu-documentation\"\n title=\"Context menu anchored to the pointer\"\n height={420}\n/>\n\n```tsx\nimport { useState } from 'react';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\nexport const RecordContextMenu = ({ recordName }: { recordName: string }) => {\n const [open, setOpen] = useState(false);\n const [point, setPoint] = useState({ x: 0, y: 0 });\n\n return (\n <>\n <p\n onContextMenu={(event) => {\n event.preventDefault();\n setPoint({ x: event.clientX, y: event.clientY });\n setOpen(true);\n }}\n >\n {recordName}\n </p>\n <Dropdown.Root type=\"menu\" open={open} onOpenChange={setOpen}>\n <Dropdown.Content\n aria-label=\"Record actions\"\n anchor={{\n getBoundingClientRect: () => new DOMRect(point.x, point.y, 0, 0),\n }}\n >\n <Dropdown.ActionItem>Duplicate</Dropdown.ActionItem>\n </Dropdown.Content>\n </Dropdown.Root>\n </>\n );\n};\n```\n\nRight-clicking elsewhere while the menu is open moves it to the new point.\n\nCall `useDropdownPlacementOrThrow` inside `Dropdown.Content` to read its resolved `side` and `align`, including collision flips. Use the resolved side to place a picker's search and create controls beside its trigger. Keep the controls in their visual DOM order so keyboard navigation follows the layout. A search below the results receives focus from `ArrowDown` on the last result; `ArrowUp` from that search returns to the last result.\n\n## Labels\n\nEach part owns its text: supply `Search.placeholder` and native accessible names, `Close` accessible attributes, and children for `Back`, `Loading`, and `Empty`. `Back` defaults to `Back`; loading and empty states have no built-in message. Item parts accept `shortcutJoinLabel` to replace the default `then` between sequential shortcut steps. Native `aria-labelledby` takes precedence over `aria-label`.\n\n## Props\n\n<DropdownReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Dropdown","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/dropdown","props":[],"parts":[{"name":"Root","props":[{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is initially open when uncontrolled."},{"name":"defaultPage","type":"string","required":false,"defaultValue":null,"description":"ID of the `Page` shown when the popup opens. Closing the popup resets the page history to it. Defaults to `root`."},{"name":"multiple","type":"boolean","required":false,"defaultValue":null,"description":"Default for standalone options. Use `SelectionGroup.multiple` for independently owned selection values."},{"name":"onEscapeKeyDown","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called when Escape is about to close the popup. Call `event.preventDefault()` to keep it open."},{"name":"onInteractOutside","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called when a press outside the popup, or Tab out of it, is about to close it. `event.target` is the element pressed outside, or `null` after Tab, and `event.type` is the type of the DOM event that triggered it. Call `event.preventDefault()` to keep it open."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Called with the next open state when the popup opens or closes."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is open. Use with `onOpenChange` to control it."},{"name":"type","type":"\"menu\" | \"panel\" | \"picker\"","required":true,"defaultValue":null,"description":"Interaction model: `menu` for commands and links, `picker` for search and selectable options, or `panel` for forms. It sets the ARIA roles, initial focus, and keyboard navigation."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Content","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"start","description":"Alignment along the anchor. Defaults to start."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Offset along the alignment axis. Accepts a number or positioning function."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"className","type":"string | ((state: PopoverPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination, using the scoped theme when omitted. Explicit null waits for a target, matching Popover.Portal."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is opened.\nBy default, focus moves to the first tabbable element inside the popup, except when the popover\nis opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the popup mounted while closed."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Preferred side of the anchor. Defaults to bottom, or inline-end in a submenu."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Distance from the anchor. Defaults to 0. Accepts a number or positioning function."},{"name":"style","type":"CSSProperties | ((state: PopoverPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"width","type":"Width<string | number>","required":false,"defaultValue":"200","description":"CSS width of the popup. Numbers are in pixels."}]},{"name":"ActionItem","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Trailing controls rendered beside the primary row control. Only supported in picker and panel pages, since a menu may only contain menu items. Secondary actions activate independently of the row."},{"name":"actionsVisibility","type":"\"always\" | \"hover\"","required":false,"defaultValue":null,"description":"Whether trailing actions appear on hover or remain visible. Defaults to `hover`."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"closeOnClick","type":"boolean","required":false,"defaultValue":"true","description":"Closes the dropdown after activation, along with parent menus when inside a submenu. Ignored when `page` is set."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Shows a chevron indicating that the item opens a submenu."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"page","type":"string","required":false,"defaultValue":null,"description":"ID of the `Page` to show on activation. The popup stays open, and the row shows a chevron by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":false,"defaultValue":null,"description":"Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."}]},{"name":"OptionItem","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Trailing controls rendered beside the primary row control. Only supported in picker and panel pages, since a menu may only contain menu items. Secondary actions activate independently of the row."},{"name":"actionsVisibility","type":"\"always\" | \"hover\"","required":false,"defaultValue":null,"description":"Whether trailing actions appear on hover or remain visible. Defaults to `hover`."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Overrides the nearest group close policy for this option. A cancelled selection never closes automatically."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Shows a chevron indicating that the item opens a submenu."},{"name":"indicator","type":"\"check\" | \"checkbox\" | \"none\"","required":false,"defaultValue":null,"description":"Selection indicator: a check icon after the content, a checkbox before it, or none. Defaults to `checkbox` when `multiple` is set, otherwise `check`, and to `none` when `selected` is omitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"onSelect","type":"((eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called before the nearest group commits selection, with `event`, `reason`, `trigger`, `cancel` and `isCanceled`. Calling `cancel()` prevents the value change and automatic close."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DropdownOptionItemState>","required":false,"defaultValue":null,"description":"Element or function rendered as the row. Functions receive the supplied props and `{ selected, multiple, disabled }` state. Forward the props and ref to the rendered control."},{"name":"selected","type":"boolean","required":false,"defaultValue":null,"description":"Selected state for standalone options. Options inside a `SelectionGroup` derive it from their owner. Grouped picker options expose `aria-selected`, menu options expose `aria-checked`, and panel options expose `aria-pressed`."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"Stable option identifier within its nearest `SelectionGroup`. The group supplies selected state and commits this value on activation."}]},{"name":"SelectionGroup","props":[{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Default close policy for owned options: true for single selection, false for multiple selection. Individual options can override it."},{"name":"defaultValue","type":"string | string[] | null","required":false,"defaultValue":null,"description":"Initial uncontrolled selection. Defaults to null for single selection and an empty array for multiple selection."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Stable identifier unique within the dropdown root. Required for uncontrolled groups, whose values persist under it across popup close and page navigation. Optional for controlled groups."},{"name":"multiple","type":"boolean","required":false,"defaultValue":null,"description":"Uses an array of selected identifiers when true. Otherwise the value is one identifier or null."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void) | ((value: string[], eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next value and cancellable event details: `event`, `reason`, `trigger`, `cancel` and `isCanceled`. Calling `cancel()` preserves the value and keeps the popup open. Repeated single selection does not emit another change."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DropdownSelectionGroupState>","required":false,"defaultValue":null,"description":"Element or function rendered as the group. Functions receive supplied props and `{ value, multiple }` state. Forward the props and ref."},{"name":"value","type":"string | string[] | null","required":false,"defaultValue":null,"description":"Controlled selection: a string or null for single selection, or an array for multiple selection. Undefined leaves selection uncontrolled."}]},{"name":"Search","props":[{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"false","description":"Shows the search input focus outline. Defaults to false for all dropdown searches. Set true to opt in. Error styling remains visible."},{"name":"onValueChange","type":"((value: string) => void)","required":false,"defaultValue":null,"description":"Called with the search text on every change. The application filters the results."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, InputState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: InputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"textAlign","type":"\"end\" | \"start\"","required":false,"defaultValue":null,"description":"Aligns text to the logical start or end of the input. Follows the text direction."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The value of the input. Use when controlled."}]},{"name":"Header","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: PopoverTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the close control. Required because the default control only shows an icon."},{"name":"className","type":"string | ((state: PopoverCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Page","props":[{"name":"id","type":"string","required":true,"defaultValue":null,"description":"Identifier matched by `defaultPage`, the `page` prop of actions, and `goToPage`. The page renders only while it is current."},{"name":"type","type":"\"menu\" | \"panel\" | \"picker\"","required":false,"defaultValue":null,"description":"Interaction model while the page is shown. Defaults to the root `type`."}]},{"name":"Back","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Shows a chevron indicating that the item opens a submenu."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":false,"defaultValue":null,"description":"Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."}]},{"name":"Submenu","props":[{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is initially open when uncontrolled."},{"name":"defaultPage","type":"string","required":false,"defaultValue":null,"description":"ID of the `Page` shown when the popup opens. Closing the popup resets the page history to it. Defaults to `root`."},{"name":"multiple","type":"boolean","required":false,"defaultValue":null,"description":"Default for standalone options. Use `SelectionGroup.multiple` for independently owned selection values."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Called with the next open state when the popup opens or closes."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is open. Use with `onOpenChange` to control it."},{"name":"type","type":"\"menu\" | \"panel\" | \"picker\"","required":false,"defaultValue":"menu","description":"Interaction model: `menu` for commands and links, `picker` for search and selectable options, or `panel` for forms. It sets the ARIA roles, initial focus, and keyboard navigation."}]},{"name":"SubmenuTrigger","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"closeDelay","type":"number","required":false,"defaultValue":null,"description":"Delay in milliseconds before a submenu opened on hover closes. Requires `openOnHover`. Defaults to `0`."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"delay","type":"number","required":false,"defaultValue":null,"description":"Delay in milliseconds before the submenu opens on hover. Requires `openOnHover`. Defaults to `300`."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":"true","description":"Shows a chevron indicating that the item opens a submenu."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"true","description":"Also opens the submenu when the row is hovered."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":false,"defaultValue":null,"description":"Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."}]},{"name":"Section","props":[{"name":"columns","type":"number","required":false,"defaultValue":null,"description":"Number of grid columns. Sets the grid layout and enables horizontal arrow navigation and vertical movement by row."},{"name":"label","type":"ReactNode","required":false,"defaultValue":null,"description":"Heading displayed above the rows. It also names the group for assistive technologies."},{"name":"scrollable","type":"boolean","required":false,"defaultValue":null,"description":"Caps the section height and scrolls its rows. Nest labelled sections inside it to scroll them as one list."}]},{"name":"Separator","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the separator. Native div attributes and refs are also accepted."}]},{"name":"Loading","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Loading message announced as a polite, busy status."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the status. Native div attributes and refs are also accepted."}]},{"name":"Empty","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Empty-state message announced as a polite status."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the status. Native div attributes and refs are also accepted."}]}]}},{"name":"OverflowingList","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: OverflowingList\ndescription: Fit a row of items into the available space and show the complete list in a popup.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport OverflowingListReference from '/snippets/ui/generated/components/layout/overflowing-list.mdx';\n\n## Overview\n\n`OverflowingList` measures its available width, keeps fitting items in a compact row, and offers a `+N` button that opens the complete list in a popup. The count updates when the container, item content or ordered list changes. Empty lists and lists that fit have no overflow button or exposed popup.\n\n<StoryEmbed\n storyId=\"ui-components-overflowinglist--display\"\n title=\"Overflowing list example\"\n height={280}\n/>\n\nSupply the complete ordered list as keyed elements. Your application owns each item's content, actions and data. The compact row remains visible when the popup opens. The popup repeats the complete list, including the items that fit in the row.\n\n## Usage\n\n```tsx\nimport { OverflowingList, Section } from 'twenty-ui/components/layout';\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nconst TAGS = ['Customer', 'Partner', 'Priority', 'Renewal'];\n\nexport const CompanyTags = () => (\n <Section.Root>\n <Section.Header\n title=\"Company tags\"\n description=\"Open the count to see all tags.\"\n />\n <OverflowingList\n style={{ width: 180 }}\n showOverflowCount\n overflowLabel=\"Show all company tags\"\n >\n {TAGS.map((label) => (\n <Tag\n key={label}\n color=\"blue\"\n truncate={false}\n style={{ width: 80, minWidth: 'fit-content' }}\n >\n {label}\n </Tag>\n ))}\n </OverflowingList>\n </Section.Root>\n);\n```\n\n## Count visibility\n\n| `showOverflowCount` | Behavior when items overflow |\n| ------------------- | ---------------------------------------------------------------------------- |\n| Omitted | Shows the count on pointer hover, keyboard focus or while the popup is open. |\n| `true` | Keeps the count visible. |\n| `false` | Hides the count and clips the row. An open popup stays open until dismissed. |\n\nThe default mode keeps the current count visibility while an inline item is focused, so showing the count does not push that item out of the row. Focusing the count button makes the count visible.\n\nUse `false` when the surrounding interface provides another way to access the hidden items. Changing it to `false` hides the count without dismissing an already-open popup. `open` and `defaultOpen` can still expose the complete list when items overflow. Removing the overflow items or widening the list until everything fits closes the popup and removes the count button. The count always describes the items outside the compact row.\n\n`maxInlineCount` caps the number of visible row items. Available width can reduce that number further. The popup still contains the complete list. It does not fetch missing items or virtualize the popup.\n\n## Popup state\n\nThe list owns its popup state when `open` is omitted. Use `defaultOpen` for its initial state. The default is `false`; an initially open popup still requires overflowing items.\n\nPass `open` and update it in `onOpenChange` to own the popup state. The callback receives the requested boolean and the installed [Popover](/ui/primitives/surfaces/popover) event details, including `reason`, `event`, `trigger`, `cancel()` and `preventUnmountOnClose()`. Calling `cancel()` prevents the requested state change. In controlled use, update your state only for changes you accept.\n\nPass `actionsRef` to receive the Popover `close()` and `unmount()` methods. `close()` requests closure through `onOpenChange` and respects cancellation. If your callback calls `preventUnmountOnClose()` to run a caller-owned exit, call `actionsRef.current?.unmount()` when that exit finishes. This releases the retained popup without removing the list and allows it to open again.\n\n```tsx\nimport { useState } from 'react';\nimport { OverflowingList } from 'twenty-ui/components/layout';\nimport { Tag } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst TEAMS = ['Design', 'Engineering', 'Support', 'Operations'];\n\nexport const ControlledTeamList = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <OverflowingList\n open={open}\n onOpenChange={setOpen}\n showOverflowCount\n overflowLabel=\"Show all teams\"\n style={{ width: 220 }}\n triggerProps={{ render: <Button variant=\"outline\" size=\"sm\" /> }}\n >\n {TEAMS.map((team) => (\n <Tag key={team} color=\"blue\">\n {team}\n </Tag>\n ))}\n </OverflowingList>\n );\n};\n```\n\n<StoryEmbed\n storyId=\"ui-components-overflowinglist--controlled\"\n title=\"Controlled state with a custom trigger\"\n height={280}\n/>\n\n## Native targets and composition\n\nNative `div` attributes, handlers, styles, class names and refs on `OverflowingList` target the compact row root. Use `triggerProps` for the count button and `popupProps` for the popup content div. Both retain their Popover part's native props, handlers, ref and element/function `render` composition.\n\nCustomize the trigger with `triggerProps.render`, as in the controlled example, or supply `triggerProps.children` to replace `+N`. Custom components must [forward the supplied props and ref](/ui/primitives/overview#custom-components). Custom popup components must also render the supplied children; OverflowingList owns the item content. `overflowLabel` defaults to \"Show all items\". The default button's accessible name combines its count and that label, for example \"+3 Show all teams\". Override `triggerProps['aria-label']` or `popupProps['aria-label']` when their content needs a different name.\n\n`OverflowingList` stops `click`, `mousedown`, `pointerdown`, `keydown` and `keyup` propagation on the trigger and popup by default. This keeps opening the popup and interacting with its items from activating a surrounding field or picker. A handler supplied through `triggerProps` or `popupProps` replaces the default for that event. Call `event.stopPropagation()` in your handler to retain blocking, or omit it to allow that event to bubble. Other events keep their defaults. Handlers on a custom `render` element compose with the supplied props as usual.\n\nWhen a popup click override allows bubbling, the installed Base UI portal can dispatch that click to a surrounding React ancestor twice with the same native event. This also occurs with a plain `Popover`. OverflowingList preserves that upstream behavior; it does not guarantee one ancestor callback per native popup event when bubbling is enabled.\n\n## Keyboard and focus\n\nEnter, Space and pointer activation open a non-modal popup. Escape and outside interaction dismiss it. Ordinary dismissal restores focus to the count button. Focus already on a visible inline item or an outside control is preserved. The popup supports content, links and buttons with their native keyboard behavior; it does not turn them into menu items or add menu arrow navigation.\n\nUse `popupProps.initialFocus` and `popupProps.finalFocus` to customize opening and dismissal focus through the installed Popover contract.\n\nEach list owns its responsive measurements independently. Unmounting one list releases its observers and leaves other lists working.\n\n## Server rendering and hydration\n\nServer markup includes the first `maxInlineCount` items, or all items when the cap is omitted. Width measurement and popup content become available after client mounting.\n\nHydration reuses the provisional row and applies responsive measurement after client mounting. Row and popup children are separate rendered instances. Keep state shared between those locations in the caller.\n\n## Migration\n\nThe popup continues to show the complete list and uses \"Show all items\" by default. `showOverflowCount={false}` preserves the clipped row and hides the count. It does not dismiss an already-open popup. The trigger and popup retain their default blocking for click, mousedown, pointerdown, keydown and keyup. Override an individual handler through `triggerProps` or `popupProps` when the surrounding interface should receive that event.\n\n## Props\n\n<OverflowingListReference />\n\n<PageBanner illustration=\"section-apps-data\" />\n","api":{"name":"OverflowingList","entryPoint":"twenty-ui/components/layout","slug":"components/layout/overflowing-list","props":[{"name":"actionsRef","type":"RefObject<PopoverRootActions | null>","required":false,"defaultValue":null,"description":"Ref exposing the Popover close() and unmount() methods. After preventUnmountOnClose(), call unmount() when the caller-owned exit finishes."},{"name":"children","type":"ReactElement<unknown, string | JSXElementConstructor<any>>[]","required":true,"defaultValue":null,"description":"Complete ordered list of elements, each with a stable key. The popup contains the complete list, including items visible in the compact row."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Initial popup visibility when uncontrolled. Defaults to false."},{"name":"maxInlineCount","type":"number","required":false,"defaultValue":null,"description":"Maximum number of items visible in the compact row. Available width can reduce this count further. The popup still contains the complete list."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose()."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controlled popup visibility. A popup can appear only when items overflow."},{"name":"overflowLabel","type":"string","required":false,"defaultValue":"Show all items","description":"Accessible label for the popup. The default overflow button is named by its visible count followed by this label. Defaults to Show all items."},{"name":"popupProps","type":"Omit<PopoverPopupProps, \"children\">","required":false,"defaultValue":null,"description":"Popover.Popup native props, handlers, ref, render composition and focus options for the overflow content. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the compact row root div."},{"name":"showOverflowCount","type":"boolean","required":false,"defaultValue":null,"description":"Shows the count on hover, keyboard focus or while open by default. Use true to keep it visible whenever items overflow, or false to hide the count and clip the row. An already-open popup stays open until dismissed. Empty lists and lists that fit have no trigger."},{"name":"triggerProps","type":"Omit<\n ComponentPropsWithRef<typeof Popover.Trigger>,\n 'handle' | 'payload' | 'ref'\n > & { ref?: Ref<HTMLElement> }","required":false,"defaultValue":null,"description":"Popover.Trigger native props, handlers, ref, children and render composition for the count button. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default. Custom components must forward supplied props and ref."}]}},{"name":"LabeledSeparator","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: LabeledSeparator\ndescription: Separate content with a centered or end-aligned text label.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport LabeledSeparatorReference from '/snippets/ui/generated/components/layout/labeled-separator.mdx';\n\n## Overview\n\n`LabeledSeparator` composes [Separator](/ui/primitives/layout/separator) and [Text](/ui/primitives/typography/text) into a named horizontal divider. Your application supplies the label and surrounding spacing.\n\n<StoryEmbed\n storyId=\"ui-layout-labeledseparator--display\"\n title=\"Labeled separator between import options\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport { LabeledSeparator } from 'twenty-ui/components/layout';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportOptions = () => (\n <Text\n style={{\n display: 'grid',\n gap: 'var(--t-spacing-3)',\n width: 320,\n maxWidth: '100%',\n }}\n >\n <Button fullWidth>Import a CSV file</Button>\n <LabeledSeparator>Or</LabeledSeparator>\n <Button fullWidth variant=\"outline\">\n Connect a data source\n </Button>\n </Text>\n);\n```\n\n## Label placement and tone\n\n`labelPosition` defaults to `center`, with a line on each side of the label. Use `end` to place the label after the leading line. The label accepts a string supplied and localized by your application.\n\n`tone` defaults to `neutral`. Use `danger` for a red marker with a medium-weight label and a thicker rule. Set `hasStartMarker` to add a small decorative cap at the beginning of the rule.\n\nThe optional cap follows the [shared calendar and chat line design](https://www.figma.com/design/xt8O9mFeLl46C5InWwoMrN/Twenty?node-id=118289-146574).\n\n<StoryEmbed\n storyId=\"ui-layout-labeledseparator--unread-marker\"\n title=\"Unread marker with an end-aligned label\"\n height={100}\n/>\n\n```tsx\nimport { LabeledSeparator } from 'twenty-ui/components/layout';\n\nexport const UnreadMarker = () => (\n <LabeledSeparator\n labelPosition=\"end\"\n tone=\"danger\"\n hasStartMarker\n style={{ width: 488, maxWidth: '100%' }}\n >\n New\n </LabeledSeparator>\n);\n```\n\n## Spacing and application state\n\nThe component fills its container and adds no outer margin. Use parent layout spacing or native `style` and `className` for margins and alignment. Keep offsets for adjacent avatars or calendar positions in your application.\n\nThe component presents the supplied label. Your application decides where an unread boundary or calendar marker belongs and when it is visible.\n\n## Accessibility and composition\n\nThe root exposes one horizontal separator named from its label. The rule segments and optional start marker are decorative, so assistive technology does not announce extra separators. Native accessible attributes can provide a different name or description when needed.\n\nNative attributes, styles, class names, and `ref` target the outer `div`. Use `render` to compose another noninteractive element while forwarding the supplied props and ref. `LabeledSeparatorProps` is exported from `twenty-ui/components/layout`.\n\n## Migration\n\nReplace the frontend `LabeledDivider` with `LabeledSeparator`. Rename `textPosition` to `labelPosition`, and use `tone=\"danger\"` for the unread marker's red appearance. Remove `noMargin`, since outer margins default to zero. Preserve the former default spacing with `style={{ marginBlock: 'var(--t-spacing-3)' }}` where needed.\n\n## Props\n\n<LabeledSeparatorReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"LabeledSeparator","entryPoint":"twenty-ui/components/layout","slug":"components/layout/labeled-separator","props":[{"name":"children","type":"string","required":true,"defaultValue":null,"description":"Text naming the separator. Supplied and localized by the caller."},{"name":"hasStartMarker","type":"boolean","required":false,"defaultValue":"false","description":"Show a decorative cap at the beginning of the rule."},{"name":"labelPosition","type":"\"center\" | \"end\"","required":false,"defaultValue":"center","description":"Place the label between two lines or at the end of one line."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"tone","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":"neutral","description":"Neutral divider or red marker with a thicker rule."}]}},{"name":"Section","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: Section\ndescription: Group content with a heading, supporting description, and optional action.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SectionReference from '/snippets/ui/generated/components/layout/section.mdx';\n\n## Overview\n\n`Section.Root` groups related content. `Section.Header` combines [Heading](/ui/primitives/typography/heading) with a description and optional `actions` content. Descriptions are ordinary text associated with the heading, so they do not add levels to the document outline.\n\n<StoryEmbed\n storyId=\"ui-components-section--display\"\n title=\"Section example\"\n height={150}\n/>\n\n## Usage\n\n```tsx\nimport { Section } from 'twenty-ui/components/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceSection = () => (\n <Section.Root>\n <Section.Header\n title=\"Workspace settings\"\n description=\"Manage your workspace name and preferences.\"\n />\n <Text>Workspace preferences appear here.</Text>\n </Section.Root>\n);\n```\n\n## Add a description and action\n\n```tsx\nimport { Section } from 'twenty-ui/components/layout';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceSection = () => (\n <Section.Root>\n <Section.Header\n title=\"Workspace settings\"\n description=\"Manage your workspace name and preferences.\"\n actions={<Button>Edit workspace</Button>}\n />\n <Text>Workspace preferences appear here.</Text>\n </Section.Root>\n);\n```\n\n`Section.Root` defaults to a full-width `div` with left alignment and the primary text color. Use `align`, `color`, and `fullWidth` to adjust the content wrapper.\n\n`Section.Header` can also be used by itself. Its `level`, `size`, and `color` configure the heading and default to `2`, `md`, and `primary`. The header has one spacing-4 margin after it. Use native `style` or `className` to adjust that spacing.\n\n## Description overflow\n\nString descriptions show up to five lines. Set `descriptionLineClamp` to a positive integer to choose another limit, or `false` to display the full description without an overflow tooltip. Hover reveals overflowing text. Descriptions do not add a tab stop by default; set `isDescriptionFocusable` to enable focus access to the tooltip. Escape dismisses the tooltip.\n\nThe heading accepts node content. Choose `level` for the document outline independently of visual `size` and `color`. Compose links and other rich content explicitly in a node description.\n\nPass a React node for richer supporting content. Rich descriptions render as supplied, without automatic truncation or tooltips.\n\n## Composition\n\nBoth parts forward native attributes, refs, class names, styles, and `render` to their outer element. For example, `Section.Root render={<section aria-label=\"Workspace settings\" />}` provides a named section, and `Section.Header render={<header />}` uses a header container.\n\nWhen migrating, replace `adornment` with `actions`. Opt into description focus with `isDescriptionFocusable` when needed. `SectionRootProps` and `SectionHeaderProps` are exported from `twenty-ui/components/layout`.\n\n## Props\n\n<SectionReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Section","entryPoint":"twenty-ui/components/layout","slug":"components/layout/section","props":[],"parts":[{"name":"Root","props":[{"name":"align","type":"\"center\" | \"left\"","required":false,"defaultValue":"left","description":"Text alignment within the section. Defaults to `left`."},{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Text color within the section. Defaults to `primary`."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"true","description":"Whether the section fills the available width. Defaults to `true`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Header","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Content alongside the heading, such as an action button or status."},{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Theme font color. Defaults to `primary`."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text associated with the heading. Strings have optional truncation and overflow tooltips; React nodes render as supplied."},{"name":"descriptionLineClamp","type":"number | false","required":false,"defaultValue":"5","description":"Maximum visible lines for a string description. Defaults to `5`; use `false` to display the full description without a tooltip."},{"name":"isDescriptionFocusable","type":"boolean","required":false,"defaultValue":"false","description":"Adds a tab stop to a truncated string description so its overflow tooltip can open on focus. Defaults to `false`."},{"name":"level","type":"1 | 2 | 3 | 4 | 5 | 6","required":false,"defaultValue":"2","description":"Semantic heading level, from `h1` through `h6`. Does not change the visual size. Defaults to `2`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Visual font size from `xs` through `xxl`, independent of the heading level. Uses the matching font token. Defaults to `md`."},{"name":"title","type":"ReactNode","required":true,"defaultValue":null,"description":"Content of the section heading."}]}]}},{"name":"CodeEditor","entryPoint":"twenty-ui/components/code-editor","content":"---\ntitle: CodeEditor\ndescription: Edit and display code in a Monaco editor styled with the Twenty theme.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CodeEditorReference from '/snippets/ui/generated/components/code-editor/code-editor.mdx';\nimport CodeEditorHeaderReference from '/snippets/ui/generated/components/code-editor/code-editor-header.mdx';\n\n## Overview\n\n`CodeEditor` renders a [Monaco](https://microsoft.github.io/monaco-editor/) editor that follows the Twenty theme in light and dark mode. `CodeEditorHeader` adds a bar above it for a title, tabs, or actions. Both come from `twenty-ui/components/code-editor`, a separate entry point, so the rest of Twenty UI works without Monaco.\n\n<StoryEmbed\n storyId=\"ui-components-codeeditor--display\"\n title=\"Code editor example\"\n height={280}\n/>\n\n## Usage\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\n\nexport const WorkspaceEditor = () => (\n <>\n <CodeEditorHeader title=\"workspace.json\" />\n <CodeEditor\n variant=\"with-header\"\n language=\"json\"\n defaultValue={JSON.stringify(\n { name: 'Acme', plan: 'Pro', seats: 12 },\n null,\n 2,\n )}\n height={160}\n />\n </>\n);\n```\n\n## Setup\n\nInstall the editor's optional peer dependencies:\n\n```bash\nyarn add @monaco-editor/react monaco-editor\n```\n\nThe editor loads your installed `monaco-editor` package rather than a copy from a CDN. Monaco runs language features such as validation and autocompletion in web workers, and creating those workers depends on your bundler. Before an editor mounts, define `MonacoEnvironment.getWorker` as described in [Monaco's ESM integration guide](https://github.com/microsoft/monaco-editor/blob/main/docs/integrate-esm.md). Without it, the editor still renders, but language features are unavailable.\n\nThe code editor does not run inside [front components](/developers/extend/apps/layout/front-components) yet.\n\n## Controlled content\n\n```tsx\nimport { useState } from 'react';\nimport { isDefined } from 'twenty-ui/utilities';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const PayloadEditor = () => {\n const [payload, setPayload] = useState('{\\n \"name\": \"Acme\"\\n}');\n\n return (\n <CodeEditor\n language=\"json\"\n value={payload}\n onChange={(value) => {\n if (isDefined(value)) {\n setPayload(value);\n }\n }}\n height={200}\n />\n );\n};\n```\n\n`CodeEditorProps` includes the installed Monaco React editor contract. `onChange(value, event)` receives the content (`string | undefined`) and the original `IModelContentChangedEvent`, including changed ranges, version and undo/redo details. Guard an undefined value at the boundary where your application requires a string.\n\n`beforeMount(monaco)` runs after the Twenty theme is defined and before editor creation. `onMount(editor, monaco)` receives the editor instance after the selected theme is applied. `onValidate(markers)` receives Monaco diagnostics unchanged. `overrideServices` passes through to editor creation.\n\nA Twenty `Loader` shows until Monaco loads. Pass `loading` to customize that content, or set `isLoading` to keep it visible while your own data loads. `isLoading` unmounts an existing editor and follows Monaco React's model disposal rules.\n\n## Models and values\n\nUse `defaultValue`, `defaultLanguage` and `defaultPath` to initialize an uncontrolled model, or `value`, `language` and `path` for updates. These props retain Monaco React's behavior, including its rules for choosing initial values and reusing an existing model URI. Changing `defaultValue` does not overwrite a model that already exists.\n\nChanging `path` selects or creates a model. `saveViewState` defaults to true and restores the model's cursor and scroll state when switching back. `line` reveals a line when the editor mounts or the prop changes. `keepCurrentModel` defaults to false; when true, the caller owns disposal of the retained model.\n\n```tsx\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const FileEditor = () => (\n <CodeEditor\n defaultPath=\"file:///workspace/settings.json\"\n defaultLanguage=\"json\"\n defaultValue={'{\\n \"name\": \"Acme\"\\n}'}\n saveViewState\n />\n);\n```\n\n## Native integration\n\n`ref` points to the outer Twenty group div, which uses `display: contents` by default. This keeps the Monaco section in the parent's sizing and flex layout. The outer div has no measurable layout box.\n\nUse `containerProps` for the outer div's native attributes, event handlers, class and style. Background, border, padding and dimensions require overriding its `display`. Prefer Monaco React's `wrapperProps` section for layout styles and a measurable native ref. `className` targets the editor-container div inside that section; use `onMount` for the Monaco editor instance.\n\nThe Monaco React section contains its own loading content until the editor is ready. During initial bundled Monaco configuration or `isLoading`, Twenty renders a separate loader without `wrapperProps` or `className`. The outer `containerProps` and `ref` remain available in these states.\n\n```tsx\nimport { useRef } from 'react';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const NamedEditor = () => {\n const containerRef = useRef<HTMLDivElement>(null);\n\n return (\n <CodeEditor\n ref={containerRef}\n containerProps={{ id: 'payload-editor' }}\n wrapperProps={{ 'data-editor-surface': 'payload' }}\n options={{ ariaLabel: 'Payload code' }}\n />\n );\n};\n```\n\n## Add a header\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype ScriptEditorProps = {\n script: string;\n onRun: () => void;\n};\n\nexport const ScriptEditor = ({ script, onRun }: ScriptEditorProps) => (\n <div>\n <CodeEditorHeader\n title=\"index.ts\"\n endElement={\n <Button size=\"sm\" onClick={onRun}>\n Run\n </Button>\n }\n />\n <CodeEditor language=\"typescript\" value={script} variant=\"with-header\" />\n </div>\n);\n```\n\n`variant=\"with-header\"` removes the editor's top border so it joins the header. Use `borderless` when the editor sits inside a surface that already has a border.\n\nThe header accepts node content in `title`, `startElement`, and `endElement`. Use fragments for multiple tabs or actions. Native props, `className`, `style`, and `ref` target its root div. Use `render` to replace that root, for example `render={<header />}`. The `title` prop supplies visible content; to set a native title attribute, pass it on the element supplied to `render`.\n\n## Size and appearance\n\nThe editor is 450px tall and 100% wide by default. `width` and `height` accept pixels or a CSS length.\n\nSizing follows this order:\n\n1. `resizable` starts from the rendered height, including CSS lengths, within the resize handle's 50px to 500px bounds. It adds a handle after Monaco mounts. Dragging or keyboard input then sets a pixel height. Changing `height` resets it within the same bounds.\n2. Otherwise, `autoHeight` uses Monaco's content height. The explicit or default height is used until content is measured.\n3. Otherwise, the explicit or default `height` applies.\n\nMonaco React enables `automaticLayout` by default. If you disable it in `options`, your application must call `editor.layout()` when the container changes size. Native `wrapperProps.style` is passed unchanged and can override the section's width or height.\n\nPass a localized `resizeLabel` to name the resize handle for screen readers.\n\nTwenty supplies font, formatting, scrollbar, minimap and padding defaults. `contentPadding=\"comfortable\"` also widens the gap between line numbers and code. Caller `options` replace the corresponding defaults, including the whole `padding` object and `lineDecorationsWidth`.\n\nAn explicit `theme` takes precedence over `options.theme`; otherwise the editor follows Twenty's light or dark theme. Define custom Monaco themes in `beforeMount`. Monaco themes are global, so changing one affects other Monaco editors on the same page. `transparentBackground` controls the Twenty wrapper appearance independently.\n\n## Validation\n\nMonaco reports its own diagnostics, such as JSON syntax errors, through `onValidate`. To add your own, return marker data from `setMarkers`. It runs on mount, model selection and every model content change, including controlled value updates, and replaces the custom markers for the current model.\n\n## Keyboard\n\nWhile the editor has focus, it stops keyboard events from propagating. React key handlers on parent components and document-level shortcuts do not receive keystrokes typed in the editor.\n\n## Props\n\n### CodeEditor\n\n<CodeEditorReference />\n\n### CodeEditorHeader\n\n<CodeEditorHeaderReference />\n\n<PageBanner illustration=\"dev-api\" />\n","api":{"name":"CodeEditor","entryPoint":"twenty-ui/components/code-editor","slug":"components/code-editor/code-editor","props":[{"name":"autoHeight","type":"boolean","required":false,"defaultValue":"false","description":"Grows the editor to fit its content instead of using `height`. Ignored when `resizable` is set."},{"name":"beforeMount","type":"BeforeMount","required":false,"defaultValue":null,"description":"Called with Monaco before editor creation, after the Twenty theme has been defined. Use it to register custom themes or languages."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the Monaco editor-container div."},{"name":"containerProps","type":"Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"ref\">, \"children\">","required":false,"defaultValue":null,"description":"Native props, className and style for the outer Twenty group div. Its default `display: contents` preserves the Monaco section's parent sizing and flex layout without creating a layout box. Background, border, padding and dimensions require overriding `display`. Prefer `wrapperProps` for section layout styles. Its keyboard handler runs before focused editor keystrokes stop propagating."},{"name":"contentPadding","type":"\"comfortable\" | \"default\"","required":false,"defaultValue":"default","description":"`default` supplies top and bottom padding. `comfortable` also widens the gap between line numbers and code. Explicit Monaco options override these defaults."},{"name":"defaultLanguage","type":"string","required":false,"defaultValue":null,"description":"Initial Monaco language for a newly created model."},{"name":"defaultPath","type":"string","required":false,"defaultValue":null,"description":"Initial model URI, used when `path` is omitted."},{"name":"defaultValue","type":"string","required":false,"defaultValue":null,"description":"Initial content for a model created by Monaco React."},{"name":"height","type":"string | number","required":false,"defaultValue":"450","description":"Editor height in pixels or as a CSS length, defaulting to 450px. Resizing starts from this rendered height and resets when this prop changes. Auto-height uses it until content is measured."},{"name":"isLoading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a loader at the editor height instead of the editor. A loader also shows while Monaco loads."},{"name":"keepCurrentModel","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the current model when the editor unmounts. Defaults to false. The caller owns disposal of retained models."},{"name":"language","type":"string","required":false,"defaultValue":null,"description":"Monaco language identifier for highlighting and language services, such as `json` or `typescript`."},{"name":"line","type":"number","required":false,"defaultValue":null,"description":"Line revealed when the editor mounts or this prop changes."},{"name":"loading","type":"ReactNode","required":false,"defaultValue":"<Loader />","description":"Content shown while Monaco loads or `isLoading` is true. Defaults to the Twenty Loader."},{"name":"onChange","type":"OnChange","required":false,"defaultValue":null,"description":"Monaco React callback with the full content (string or undefined) and the original IModelContentChangedEvent."},{"name":"onMount","type":"OnMount","required":false,"defaultValue":null,"description":"Called when the editor is ready, with the editor instance and the Monaco namespace. The selected theme is already applied."},{"name":"onValidate","type":"OnValidate","required":false,"defaultValue":null,"description":"Called with the markers Monaco reports after validating the content, such as JSON syntax errors."},{"name":"options","type":"IStandaloneEditorConstructionOptions","required":false,"defaultValue":null,"description":"Monaco editor options merged over Twenty defaults. Explicit values, including padding, replace the corresponding defaults. The `theme` prop takes precedence over `options.theme`."},{"name":"overrideServices","type":"IEditorOverrideServices","required":false,"defaultValue":null,"description":"Monaco services passed through when the editor is created."},{"name":"path","type":"string","required":false,"defaultValue":null,"description":"URI of the current model. Changing it selects or creates a model using Monaco React behavior."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the outer Twenty group div, which has no measurable layout box with its default `display: contents`. Use `wrapperProps` for a measurable section ref or `onMount` for the Monaco editor instance."},{"name":"resizable","type":"boolean","required":false,"defaultValue":"false","description":"Adds a height resize handle after Monaco mounts, bounded from 50px to 500px. Takes precedence over autoHeight. A changed height prop resets the resized height within these bounds."},{"name":"resizeLabel","type":"string","required":false,"defaultValue":"Resize editor","description":"Accessible name of the resize handle. Pass a localized label when `resizable` is enabled."},{"name":"saveViewState","type":"boolean","required":false,"defaultValue":"true","description":"Preserves Monaco React view state between model changes. Defaults to true."},{"name":"setMarkers","type":"((value: string) => IMarkerData[])","required":false,"defaultValue":null,"description":"Returns custom validation markers for the current model content. Runs on mount, model selection and content changes, including controlled updates."},{"name":"theme","type":"string","required":false,"defaultValue":"Twenty theme","description":"Monaco theme name. Takes precedence over `options.theme`, which takes precedence over the Twenty theme. Define custom themes in `beforeMount`."},{"name":"transparentBackground","type":"boolean","required":false,"defaultValue":null,"description":"Removes the editor background so the surrounding surface shows through."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"Content of the editor. Pair it with `onChange` to control the editor."},{"name":"variant","type":"\"borderless\" | \"default\" | \"with-header\"","required":false,"defaultValue":"default","description":"Border treatment: `default` draws a rounded border, `with-header` attaches the editor below a `CodeEditorHeader`, and `borderless` removes the border."},{"name":"width","type":"string | number","required":false,"defaultValue":"100%","description":"Width of the Monaco React section, in pixels or as a CSS length."},{"name":"wrapperProps","type":"object","required":false,"defaultValue":null,"description":"Native props passed unchanged to the Monaco React section around the editor and Monaco React loading content. Use this section for layout styles and a measurable native ref. Not applied to the separate Twenty loader during initial Monaco configuration or `isLoading`. Native styles can override the section sizing."}]}},{"name":"CodeEditorHeader","entryPoint":"twenty-ui/components/code-editor","content":"---\ntitle: CodeEditor\ndescription: Edit and display code in a Monaco editor styled with the Twenty theme.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CodeEditorReference from '/snippets/ui/generated/components/code-editor/code-editor.mdx';\nimport CodeEditorHeaderReference from '/snippets/ui/generated/components/code-editor/code-editor-header.mdx';\n\n## Overview\n\n`CodeEditor` renders a [Monaco](https://microsoft.github.io/monaco-editor/) editor that follows the Twenty theme in light and dark mode. `CodeEditorHeader` adds a bar above it for a title, tabs, or actions. Both come from `twenty-ui/components/code-editor`, a separate entry point, so the rest of Twenty UI works without Monaco.\n\n<StoryEmbed\n storyId=\"ui-components-codeeditor--display\"\n title=\"Code editor example\"\n height={280}\n/>\n\n## Usage\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\n\nexport const WorkspaceEditor = () => (\n <>\n <CodeEditorHeader title=\"workspace.json\" />\n <CodeEditor\n variant=\"with-header\"\n language=\"json\"\n defaultValue={JSON.stringify(\n { name: 'Acme', plan: 'Pro', seats: 12 },\n null,\n 2,\n )}\n height={160}\n />\n </>\n);\n```\n\n## Setup\n\nInstall the editor's optional peer dependencies:\n\n```bash\nyarn add @monaco-editor/react monaco-editor\n```\n\nThe editor loads your installed `monaco-editor` package rather than a copy from a CDN. Monaco runs language features such as validation and autocompletion in web workers, and creating those workers depends on your bundler. Before an editor mounts, define `MonacoEnvironment.getWorker` as described in [Monaco's ESM integration guide](https://github.com/microsoft/monaco-editor/blob/main/docs/integrate-esm.md). Without it, the editor still renders, but language features are unavailable.\n\nThe code editor does not run inside [front components](/developers/extend/apps/layout/front-components) yet.\n\n## Controlled content\n\n```tsx\nimport { useState } from 'react';\nimport { isDefined } from 'twenty-ui/utilities';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const PayloadEditor = () => {\n const [payload, setPayload] = useState('{\\n \"name\": \"Acme\"\\n}');\n\n return (\n <CodeEditor\n language=\"json\"\n value={payload}\n onChange={(value) => {\n if (isDefined(value)) {\n setPayload(value);\n }\n }}\n height={200}\n />\n );\n};\n```\n\n`CodeEditorProps` includes the installed Monaco React editor contract. `onChange(value, event)` receives the content (`string | undefined`) and the original `IModelContentChangedEvent`, including changed ranges, version and undo/redo details. Guard an undefined value at the boundary where your application requires a string.\n\n`beforeMount(monaco)` runs after the Twenty theme is defined and before editor creation. `onMount(editor, monaco)` receives the editor instance after the selected theme is applied. `onValidate(markers)` receives Monaco diagnostics unchanged. `overrideServices` passes through to editor creation.\n\nA Twenty `Loader` shows until Monaco loads. Pass `loading` to customize that content, or set `isLoading` to keep it visible while your own data loads. `isLoading` unmounts an existing editor and follows Monaco React's model disposal rules.\n\n## Models and values\n\nUse `defaultValue`, `defaultLanguage` and `defaultPath` to initialize an uncontrolled model, or `value`, `language` and `path` for updates. These props retain Monaco React's behavior, including its rules for choosing initial values and reusing an existing model URI. Changing `defaultValue` does not overwrite a model that already exists.\n\nChanging `path` selects or creates a model. `saveViewState` defaults to true and restores the model's cursor and scroll state when switching back. `line` reveals a line when the editor mounts or the prop changes. `keepCurrentModel` defaults to false; when true, the caller owns disposal of the retained model.\n\n```tsx\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const FileEditor = () => (\n <CodeEditor\n defaultPath=\"file:///workspace/settings.json\"\n defaultLanguage=\"json\"\n defaultValue={'{\\n \"name\": \"Acme\"\\n}'}\n saveViewState\n />\n);\n```\n\n## Native integration\n\n`ref` points to the outer Twenty group div, which uses `display: contents` by default. This keeps the Monaco section in the parent's sizing and flex layout. The outer div has no measurable layout box.\n\nUse `containerProps` for the outer div's native attributes, event handlers, class and style. Background, border, padding and dimensions require overriding its `display`. Prefer Monaco React's `wrapperProps` section for layout styles and a measurable native ref. `className` targets the editor-container div inside that section; use `onMount` for the Monaco editor instance.\n\nThe Monaco React section contains its own loading content until the editor is ready. During initial bundled Monaco configuration or `isLoading`, Twenty renders a separate loader without `wrapperProps` or `className`. The outer `containerProps` and `ref` remain available in these states.\n\n```tsx\nimport { useRef } from 'react';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const NamedEditor = () => {\n const containerRef = useRef<HTMLDivElement>(null);\n\n return (\n <CodeEditor\n ref={containerRef}\n containerProps={{ id: 'payload-editor' }}\n wrapperProps={{ 'data-editor-surface': 'payload' }}\n options={{ ariaLabel: 'Payload code' }}\n />\n );\n};\n```\n\n## Add a header\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype ScriptEditorProps = {\n script: string;\n onRun: () => void;\n};\n\nexport const ScriptEditor = ({ script, onRun }: ScriptEditorProps) => (\n <div>\n <CodeEditorHeader\n title=\"index.ts\"\n endElement={\n <Button size=\"sm\" onClick={onRun}>\n Run\n </Button>\n }\n />\n <CodeEditor language=\"typescript\" value={script} variant=\"with-header\" />\n </div>\n);\n```\n\n`variant=\"with-header\"` removes the editor's top border so it joins the header. Use `borderless` when the editor sits inside a surface that already has a border.\n\nThe header accepts node content in `title`, `startElement`, and `endElement`. Use fragments for multiple tabs or actions. Native props, `className`, `style`, and `ref` target its root div. Use `render` to replace that root, for example `render={<header />}`. The `title` prop supplies visible content; to set a native title attribute, pass it on the element supplied to `render`.\n\n## Size and appearance\n\nThe editor is 450px tall and 100% wide by default. `width` and `height` accept pixels or a CSS length.\n\nSizing follows this order:\n\n1. `resizable` starts from the rendered height, including CSS lengths, within the resize handle's 50px to 500px bounds. It adds a handle after Monaco mounts. Dragging or keyboard input then sets a pixel height. Changing `height` resets it within the same bounds.\n2. Otherwise, `autoHeight` uses Monaco's content height. The explicit or default height is used until content is measured.\n3. Otherwise, the explicit or default `height` applies.\n\nMonaco React enables `automaticLayout` by default. If you disable it in `options`, your application must call `editor.layout()` when the container changes size. Native `wrapperProps.style` is passed unchanged and can override the section's width or height.\n\nPass a localized `resizeLabel` to name the resize handle for screen readers.\n\nTwenty supplies font, formatting, scrollbar, minimap and padding defaults. `contentPadding=\"comfortable\"` also widens the gap between line numbers and code. Caller `options` replace the corresponding defaults, including the whole `padding` object and `lineDecorationsWidth`.\n\nAn explicit `theme` takes precedence over `options.theme`; otherwise the editor follows Twenty's light or dark theme. Define custom Monaco themes in `beforeMount`. Monaco themes are global, so changing one affects other Monaco editors on the same page. `transparentBackground` controls the Twenty wrapper appearance independently.\n\n## Validation\n\nMonaco reports its own diagnostics, such as JSON syntax errors, through `onValidate`. To add your own, return marker data from `setMarkers`. It runs on mount, model selection and every model content change, including controlled value updates, and replaces the custom markers for the current model.\n\n## Keyboard\n\nWhile the editor has focus, it stops keyboard events from propagating. React key handlers on parent components and document-level shortcuts do not receive keystrokes typed in the editor.\n\n## Props\n\n### CodeEditor\n\n<CodeEditorReference />\n\n### CodeEditorHeader\n\n<CodeEditorHeaderReference />\n\n<PageBanner illustration=\"dev-api\" />\n","api":{"name":"CodeEditorHeader","entryPoint":"twenty-ui/components/code-editor","slug":"components/code-editor/code-editor-header","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional CSS class applied to the root element."},{"name":"endElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content shown at the end of the header, such as actions. Use a fragment for multiple elements."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the rendered root element, a div by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replace the root div or compose it with another component. Native props and refs target the rendered root."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content shown at the start of the header, before the title, such as tabs. Use a fragment for multiple elements."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root element."},{"name":"title","type":"ReactNode","required":false,"defaultValue":null,"description":"Content shown after `startElement`. This is visible header content, not the native HTML title attribute."}]}},{"name":"ListItemButton","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: ListItemButton\ndescription: Native action buttons with the shared list row appearance.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ListItemButtonReference from '/snippets/ui/generated/components/navigation/list-item-button.mdx';\n\n## Overview\n\nUse `ListItemButton` for action rows and standalone selection buttons. It combines [ListItem](/ui/primitives/navigation/list-item) layout with a native button, including Enter and Space activation, focus, and disabled behavior. It defaults to `type=\"button\"`.\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--display\"\n title=\"ListItemButton example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\n\nexport const DuplicateAction = ({\n onDuplicate,\n}: {\n onDuplicate: () => void;\n}) => (\n <ListItemButton\n startIcon={<IconCopy />}\n description=\"Create a copy\"\n onClick={onDuplicate}\n >\n Duplicate\n </ListItemButton>\n);\n```\n\n## Actions and disabled state\n\nPass `onClick` and `disabled` directly. Disabled buttons use the matching row appearance, prevent activation, and leave the tab order.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\n\ntype DuplicateActionProps = {\n onDuplicate: () => void;\n disabled?: boolean;\n};\n\nexport const DuplicateAction = ({\n onDuplicate,\n disabled = false,\n}: DuplicateActionProps) => (\n <ListItemButton\n disabled={disabled}\n onClick={onDuplicate}\n startIcon={<IconCopy />}\n description=\"Create a copy\"\n >\n Duplicate\n </ListItemButton>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--disabled\"\n title=\"Disabled action row\"\n height={110}\n/>\n\nSet `focusableWhenDisabled` to keep a disabled button focusable. It uses `aria-disabled` and continues to block activation. Native button attributes, events, styles, class names, and an `HTMLButtonElement` ref reach the button. Events bubble normally; callers supply any `stopPropagation()` or `preventDefault()` policy.\n\n## Selection and visual slots\n\nYour application owns the independent `active`, `selected`, and `focused` states. Use `active` for the open or current row. Pair `selected` with the appropriate accessible state, such as `aria-pressed` for a toggle button. `focused` highlights the row without moving DOM focus. Indicators and shortcut hints are decorative; your application registers shortcuts and handles navigation.\n\n```tsx\nimport { useState } from 'react';\nimport { ListItemButton } from 'twenty-ui/components/navigation';\n\nexport const ShowArchivedToggle = () => {\n const [selected, setSelected] = useState(false);\n\n return (\n <ListItemButton\n aria-pressed={selected}\n selected={selected}\n indicator=\"check\"\n onClick={() => setSelected(!selected)}\n >\n Show archived records\n </ListItemButton>\n );\n};\n```\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--selected\"\n title=\"Selected action row\"\n height={110}\n/>\n\nUse `startIcon`, `endIcon`, `description`, and `descriptionPlacement` for supporting content. `color=\"danger\"` marks a destructive action. `shortcutJoinLabel` controls the text between sequential shortcuts, and `hasSubmenu` displays a submenu indicator.\n\n## Multiline supporting content\n\nSet `descriptionPlacement=\"below\"` to wrap supporting text beneath the label. The label retains its truncation behavior. Pass [Text](/ui/primitives/typography/text) with `truncate` or `lineClamp` as `description` when you need a shorter preview. The `inline` and `end` placements keep their existing appearance.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype PlanningActionProps = {\n active?: boolean;\n disabled?: boolean;\n onOpen: () => void;\n};\n\nexport const PlanningAction = ({\n active = false,\n disabled = false,\n onOpen,\n}: PlanningActionProps) => (\n <ListItemButton\n active={active}\n disabled={disabled}\n descriptionPlacement=\"below\"\n description=\"Review the proposed timeline and confirm the next steps with the team.\"\n startIcon={<Avatar name=\"Alex Morgan\" size=\"md\" imageProps={{ alt: '' }} />}\n onClick={onOpen}\n >\n Quarterly planning\n </ListItemButton>\n);\n```\n\n`active` applies the current-row background. Set `selectionAppearance=\"accent\"` for an accent fill on selected rows with any description placement; the default preserves the existing indicator-based selection styling. `focused` applies the shared highlighted background; the focus-visible outline follows actual keyboard focus. These props do not add accessible state or move focus. Native button activation and disabled behavior remain unchanged.\n\n## Independent controls\n\nKeep independent buttons and checkboxes beside `ListItemButton` so each retains its own focus and activation. Do not nest them in its content or icon slots. The component has no `actions` slot. Use a `ListItem` with its default `div` root for [a row with independent controls](/ui/primitives/navigation/list-item#independent-controls), and supply disabled behavior and event propagation on each control.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype ContactActionsProps = {\n onOpen: () => void;\n onDetails: () => void;\n};\n\nexport const ContactActions = ({ onOpen, onDetails }: ContactActionsProps) => (\n <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <ListItemButton onClick={onOpen} description=\"Account owner\">\n Alex Morgan\n </ListItemButton>\n <Button onClick={onDetails} aria-label=\"Open Alex Morgan's details\">\n Details\n </Button>\n </div>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--independent-action\"\n title=\"Sibling action controls\"\n height={110}\n/>\n\nUse `ListItem` for passive content, links, or custom semantic owners. Use the existing [Dropdown](/ui/components/navigation/dropdown), and [Select](/ui/primitives/input/select) item parts within their popup owners, which supply roles and keyboard navigation.\n\n## Props\n\n<ListItemButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"ListItemButton","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/list-item-button","props":[{"name":"active","type":"boolean","required":false,"defaultValue":null,"description":"Marks the open or current item independently of selection and focus. The caller supplies accessible state."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables activation and applies the matching row appearance."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Keeps a disabled button focusable with aria-disabled while preventing activation."},{"name":"focused","type":"boolean","required":false,"defaultValue":null,"description":"Highlights the row without moving DOM focus."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Displays a decorative submenu indicator."},{"name":"indicator","type":"\"check\" | \"checkbox\" | \"none\"","required":false,"defaultValue":null,"description":"Selection indicator: a check icon after the content or a checkbox before\nit."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the native HTMLButtonElement."},{"name":"selected","type":"boolean","required":false,"defaultValue":null,"description":"Applies selected styling and a decorative indicator. The caller supplies selection state and accessible semantics."},{"name":"selectionAppearance","type":"\"accent\" | \"default\"","required":false,"defaultValue":null,"description":"Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Displays decorative shortcut hints. The caller registers the shortcuts."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`; pass an empty string to omit it."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."}]}},{"name":"CountPager","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: CountPager\ndescription: Navigate a finite collection with previous and next controls and formatted position text.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CountPagerReference from '/snippets/ui/generated/components/navigation/count-pager.mdx';\n\n## Overview\n\n`CountPager` combines previous and next buttons with caller-formatted position text. Use it to move through a small collection such as review items or requests.\n\n<StoryEmbed\n storyId=\"ui-components-countpager--display\"\n title=\"Count pager example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { CountPager } from 'twenty-ui/components/navigation';\n\nexport const ReviewPager = () => {\n const [index, setIndex] = useState(0);\n\n return (\n <CountPager\n aria-label=\"Review item\"\n index={index}\n count={3}\n onIndexChange={setIndex}\n positionText={`${index + 1} of 3`}\n previousLabel=\"Previous item\"\n nextLabel=\"Next item\"\n />\n );\n};\n```\n\n## Controlled navigation\n\nSupply a zero-based `index`, the collection's `count`, and `onIndexChange`. Activating an available button requests the neighboring index. Your application updates the index and renders the corresponding content.\n\nPrevious is disabled on the first item, and Next is disabled on the last item. Both buttons are disabled for an empty or single-item collection, when `disabled` is set, or when the supplied index or count is invalid. Counts must be nonnegative integers, and the index must be an integer within the collection bounds.\n\nChanging props never calls `onIndexChange`. When items disappear or the collection changes, your application chooses the next active item. Data loading, stable item identities, draft preservation, and executing the displayed item remain with the application.\n\n## Position text and placement\n\n`positionText` is required and stays under application control. Format numbers, units, and translations before passing it to the pager. For an empty collection, supply a meaningful value such as `No items`; the component does not invent an empty-state label.\n\nThe default `positionPlacement=\"between\"` shows Previous, position text, and Next. Set `positionPlacement=\"start\"` to place the text before both buttons. The text then fills the available width so the actions align at the end of the row.\n\n```tsx\nimport { useState } from 'react';\nimport { CountPager } from 'twenty-ui/components/navigation';\n\nexport const RequestPager = () => {\n const [index, setIndex] = useState(0);\n\n return (\n <CountPager\n aria-label=\"Pending requests\"\n index={index}\n count={3}\n onIndexChange={setIndex}\n positionText={`Request ${index + 1} of 3`}\n previousLabel=\"Previous request\"\n nextLabel=\"Next request\"\n positionPlacement=\"start\"\n style={{ width: 280, maxWidth: '100%' }}\n />\n );\n};\n```\n\n## Accessibility and composition\n\nThe root defaults to a group. Supply a contextual accessible name with `aria-label` or `aria-labelledby`, plus `previousLabel` and `nextLabel` for the two icon buttons. Position text uses a polite live region so changes can be announced without moving focus.\n\nThe controls use native buttons with the shared [LightIconButton](/ui/components/input/light-icon-button) presentation. Tab moves between enabled controls, and Enter or Space activates the focused button. Disabled controls cannot navigate. Pager clicks do not submit a surrounding form.\n\nNative attributes, `className`, `style`, and `ref` target the root. Use `render` to compose a different root element while preserving the supplied props and ref. Keep the buttons and their interaction semantics intact.\n\n## Props\n\n<CountPagerReference />\n\n<PageBanner illustration=\"dashboards\" />\n","api":{"name":"CountPager","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/count-pager","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the root element."},{"name":"count","type":"number","required":true,"defaultValue":null,"description":"Number of items in the collection. Empty collections and invalid or noninteger counts disable navigation."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables both navigation buttons without changing the position text."},{"name":"index","type":"number","required":true,"defaultValue":null,"description":"Controlled zero-based item index. Navigation is disabled when the index is not an integer within the collection bounds."},{"name":"nextLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the Next button."},{"name":"onIndexChange","type":"(index: number) => void","required":true,"defaultValue":null,"description":"Requests the neighboring index after activating Previous or Next. Prop changes do not call this callback or select a replacement item."},{"name":"positionPlacement","type":"\"between\" | \"start\"","required":false,"defaultValue":"between","description":"Places the position text between the buttons or at the start of the row. Start placement lets the text fill the available width."},{"name":"positionText","type":"string","required":true,"defaultValue":null,"description":"Caller-formatted position text, announced politely when it changes. The caller also supplies text for empty collections."},{"name":"previousLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the Previous button."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the root element while preserving its props and contents."},{"name":"role","type":"AriaRole","required":false,"defaultValue":"group","description":"Root semantics. Defaults to a group; the caller supplies its accessible name."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root element."}]}},{"name":"TabButton","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: TabButton\ndescription: Present route links and actions alongside tabs with consistent styling.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TabButtonReference from '/snippets/ui/generated/components/navigation/tab-button.mdx';\n\n## Overview\n\nUse `TabButton` for route links and actions such as adding a tab or opening an overflow menu. It shares the appearance of [Tabs](/ui/primitives/navigation/tabs) and uses [Button](/ui/primitives/input/button) for interaction.\n\n<StoryEmbed\n storyId=\"ui-components-tabbutton--display\"\n title=\"TabButton example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { TabButton } from 'twenty-ui/components/navigation';\nimport { IconSettings } from 'twenty-ui/icon';\n\nexport const GeneralAction = ({ onOpen }: { onOpen: () => void }) => (\n <TabButton startIcon={<IconSettings />} onClick={onOpen}>\n General\n </TabButton>\n);\n```\n\n## State and semantics\n\nYour application supplies `active` from its current route or menu state. This prop highlights the control. Set `aria-current=\"page\"` on the current route link. Route links and adjacent actions retain their link or button semantics, with no tab role, `aria-selected`, or panel relationship.\n\nUse `Tabs.Root`, `Tabs.List`, `Tabs.Tab`, `Tabs.Panel`, and optional `Tabs.Indicator` to switch between related content panels. Keep route and action controls outside `Tabs.List`.\n\n## Navigation\n\nSet `href` to render a native link. The current route owns its `active` appearance and `aria-current` value.\n\n```tsx\nimport { TabButton } from 'twenty-ui/components/navigation';\nimport { IconCreditCard } from 'twenty-ui/icon';\n\nexport const BillingLink = () => (\n <TabButton\n href=\"/billing\"\n active\n aria-current=\"page\"\n startIcon={<IconCreditCard />}\n >\n Billing\n </TabButton>\n);\n```\n\nFor client-side routing, supply your router link through `render`, set `nativeButton={false}` and `role=\"link\"`, and pass the resolved destination as `href`. Keep route state and history options on the router link. Custom wrappers must forward the supplied props and ref to their anchor.\n\n```tsx\nimport { TabButton } from 'twenty-ui/components/navigation';\n\nexport const ComposedBillingLink = () => (\n <TabButton\n nativeButton={false}\n role=\"link\"\n href=\"/billing\"\n render={<a />}\n aria-current=\"page\"\n active\n >\n Billing\n </TabButton>\n);\n```\n\nAn explicit `nativeButton` controls the interaction contract even when `href` is present. Match it to the actual rendered element. Disabled links retain their link role and block activation.\n\n## Actions\n\nWithout `href`, the control renders a native button with `type=\"button\"`. Native attributes, refs, styles, class names, and event handlers pass through. `render` accepts an element or a function receiving the Button props and state. Refs point to the actual rendered button or anchor, including refs supplied on a composed element.\n\n```tsx\nimport { useState } from 'react';\nimport { TabButton } from 'twenty-ui/components/navigation';\nimport { IconPlus } from 'twenty-ui/icon';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const AddTabAction = () => {\n const [count, setCount] = useState(1);\n\n return (\n <>\n <TabButton startIcon={<IconPlus />} onClick={() => setCount(count + 1)}>\n New Tab\n </TabButton>\n <Text role=\"status\">Tabs: {count}</Text>\n </>\n );\n};\n```\n\nUse `startIcon`, `endIcon`, and `badge` for supporting content. An avatar passed to an icon slot is decorative when the text names the destination. `size` retains the public Button size contract. An explicit size takes priority over a surrounding `ButtonGroup` size; otherwise the component defaults to `sm`.\n\n## Props\n\n<TabButtonReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"TabButton","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/tab-button","props":[{"name":"active","type":"boolean","required":false,"defaultValue":"false","description":"Highlights the current destination or an action associated with the active tab. Does not change the control role."},{"name":"badge","type":"ReactNode","required":false,"defaultValue":null,"description":"Content following the label and trailing icon, such as a count."},{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Padding of the tab content: sm or md. Explicit size takes precedence over the ButtonGroup size, then sm applies."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}},{"name":"AvatarGroup","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: AvatarGroup\ndescription: Overlapping avatars with a derived overflow indicator.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AvatarGroupReference from '/snippets/ui/generated/components/data-display/avatar-group.mdx';\n\n## Overview\n\n`AvatarGroup` receives rendered avatars and derives the hidden count. `maxVisible` counts actual avatars; the overflow indicator is additional. Eight supplied avatars with `maxVisible={3}` show three avatars and `+5`.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--display\"\n title=\"Eight avatars with three visible\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const TeamAvatars = () => (\n <AvatarGroup\n maxVisible={3}\n overflowShape=\"circle\"\n overlap=\"left\"\n overlapOffset=\"4px\"\n avatars={[\n 'Ada',\n 'Grace',\n 'Margaret',\n 'Annie',\n 'Mary',\n 'Dorothy',\n 'Katherine',\n 'Joan',\n ].map((name) => (\n <Avatar\n key={name}\n name={name}\n shape=\"circle\"\n imageProps={{ alt: name }}\n />\n ))}\n />\n);\n```\n\nSupply stable keys to keep surviving avatars mounted when the limit, total, or display order changes. Avatars are decorative by default. When the group is the only representation of its members, supply each member's name through `imageProps.alt` to label the image and default fallback. Keep avatars decorative when visible text or an owner label already supplies that identity.\n\n## Visual options\n\nCompare circle and square avatars at each size. The group keeps three visible members in this comparison.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--catalog\"\n title=\"Compare avatar shapes and sizes\"\n height={850}\n/>\n\n## Partially loaded collections\n\nUse `total` for the full collection size when only some avatars are loaded. Three supplied and visible avatars with `total={20}` show `+17`. Pass all loaded avatars and let the group apply `maxVisible`.\n\n```tsx\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const LoadedTeamAvatars = () => (\n <AvatarGroup\n maxVisible={3}\n total={20}\n avatars={['Ada', 'Grace', 'Margaret'].map((name) => (\n <Avatar key={name} name={name} imageProps={{ alt: name }} />\n ))}\n />\n);\n```\n\n`total` is floored and cannot be smaller than the supplied renderable avatar count. Nonfinite totals use the supplied count. The derived hidden count is always nonnegative.\n\n`maxVisible` defaults to `4`. Finite limits are floored and clamped to zero, `Infinity` shows all supplied avatars, and `NaN` shows none. Empty React nodes do not count as avatars. A zero limit can show only the overflow indicator. An empty group with a positive total can show that total in its indicator; an empty group with no hidden avatars renders nothing.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--partially-loaded\"\n title=\"Three loaded members from a team of twenty\"\n height={100}\n/>\n\n## Custom overflow\n\n`renderOverflow` receives the same derived hidden count as the default `+N` indicator. It runs only when that count is positive. Return `null` to hide the indicator without changing which avatars are visible.\n\nUse an explicit control when the indicator performs an action. Its accessible name should explain the action and the count.\n\n```tsx\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype TeamAvatarsWithActionProps = { onShowAll: () => void };\n\nexport const TeamAvatarsWithAction = ({\n onShowAll,\n}: TeamAvatarsWithActionProps) => (\n <AvatarGroup\n maxVisible={3}\n total={20}\n avatars={['Ada', 'Grace', 'Margaret'].map((name) => (\n <Avatar key={name} name={name} imageProps={{ alt: name }} />\n ))}\n renderOverflow={(hiddenCount) => (\n <Button\n size=\"sm\"\n aria-label={`Show ${hiddenCount} more members`}\n onClick={onShowAll}\n >\n +{hiddenCount}\n </Button>\n )}\n />\n);\n```\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--custom-overflow\"\n title=\"Custom overflow button\"\n height={100}\n/>\n\n## Appearance\n\nLater avatars always render above earlier ones. `overlap` picks the physical margin, `left` or `right`, that carries the negative offset. `overlapOffset` sets that offset as a CSS length. `overflowShape` sets the shape of the default numeric indicator.\n\n## Root customization\n\nNative attributes, event handlers, `className`, and `style` reach the root. Its default element is a `div`, including when `onClick` is supplied. Use native interactive elements for actions, such as the overflow button above.\n\nThe root accepts a ref and `render`, which can be an element or a function. Custom components must forward the supplied props and ref to their native root. See [custom components](/ui/primitives/overview#custom-components) for composition requirements.\n\n```tsx\nimport { useRef } from 'react';\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const NamedTeamAvatars = () => {\n const groupRef = useRef<HTMLDivElement>(null);\n\n return (\n <AvatarGroup\n ref={groupRef}\n role=\"group\"\n aria-label=\"Project members\"\n style={{ marginBlock: 8 }}\n render={<div data-location=\"project-header\" />}\n avatars={['Ada', 'Grace', 'Margaret'].map((name) => (\n <Avatar key={name} name={name} imageProps={{ alt: name }} />\n ))}\n />\n );\n};\n```\n\n## Props\n\n`AvatarGroupProps` is exported from `twenty-ui/components/data-display`.\n\n<AvatarGroupReference />\n\n<PageBanner illustration=\"page-cover-users\" />\n","api":{"name":"AvatarGroup","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/avatar-group","props":[{"name":"avatars","type":"ReactNode[]","required":true,"defaultValue":null,"description":"Avatar elements in display order. Empty React nodes are ignored. Supply stable keys to preserve identity when reordering."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the group container."},{"name":"maxVisible","type":"number","required":false,"defaultValue":"4","description":"Maximum number of actual avatars to show, excluding the overflow indicator. Floored and clamped to zero; Infinity shows all avatars and NaN shows none."},{"name":"overflowShape","type":"\"circle\" | \"rounded-square\" | \"square\"","required":false,"defaultValue":"square","description":"Shape of the numeric overflow indicator."},{"name":"overlap","type":"\"left\" | \"right\"","required":false,"defaultValue":"right","description":"Physical margin, left or right, that carries the negative overlap offset. Later avatars always render above earlier ones."},{"name":"overlapOffset","type":"string","required":false,"defaultValue":"3px","description":"CSS length of the overlap between avatars."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the rendered root element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render function for the root. Forward the supplied props and ref; the default element is a div."},{"name":"renderOverflow","type":"((hiddenCount: number) => ReactNode)","required":false,"defaultValue":null,"description":"Called with the derived hidden count when it is positive. Return a custom indicator, or null to hide it."},{"name":"total","type":"number","required":false,"defaultValue":null,"description":"Total collection size for partially loaded avatars. Floored and never smaller than the supplied renderable count; nonfinite values use the supplied count."}]}},{"name":"CommandBlock","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: CommandBlock\ndescription: Display command lines with an optional action.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CommandBlockReference from '/snippets/ui/generated/components/data-display/command-block.mdx';\n\n## Overview\n\n`CommandBlock` displays each supplied command with a prompt marker. It does not execute commands or provide copying automatically. Supply `actions` with any React node, such as a [Button](/ui/primitives/input/button), link or status. Command text uses `pre` and `code` semantics, preserves line breaks, and wraps within the available width. Prompt markers are decorative.\n\n<StoryEmbed\n storyId=\"ui-components-data-display-commandblock--display\"\n title=\"CommandBlock example\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { CommandBlock } from 'twenty-ui/components/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const InstallCommand = () => {\n const [copyLabel, setCopyLabel] = useState('Copy command');\n\n return (\n <CommandBlock\n commands={['yarn add twenty-ui']}\n actions={\n <Button\n onClick={async () => {\n try {\n await navigator.clipboard.writeText('yarn add twenty-ui');\n setCopyLabel('Copied');\n } catch {\n setCopyLabel('Select and copy the command');\n }\n }}\n >\n {copyLabel}\n </Button>\n }\n />\n );\n};\n```\n\nNative attributes, event handlers, classes, styles and refs target the outer `div`. Use `render` to compose another root, for example `render={<section aria-label=\"Installation commands\" />}`. `CommandBlockProps` is exported from `twenty-ui/components/data-display`.\n\nWhen migrating, replace `button` with `actions`.\n\n## Props\n\n<CommandBlockReference />\n\n<PageBanner illustration=\"card-page-cli\" />\n","api":{"name":"CommandBlock","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/command-block","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Content beside the command lines, such as a copy button, link or status."},{"name":"commands","type":"readonly string[]","required":true,"defaultValue":null,"description":"Command lines to display. The component prefixes each line with > and does not execute commands."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]}},{"name":"JsonTree","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: JsonTree\ndescription: Explore JSON values with expandable nodes and custom labels.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport JsonTreeReference from '/snippets/ui/generated/components/data-display/json-tree.mdx';\n\n## Overview\n\n`JsonTree` displays either a JSON `value` or an array of named `entries`. Pass all empty-value and expand/collapse labels so your application controls the text.\n\n<StoryEmbed\n storyId=\"ui-jsonvisualizer-jsontree--display\"\n title=\"Expandable record details\"\n height={320}\n/>\n\n## Usage\n\n```tsx\nimport { JsonTree } from 'twenty-ui/components/data-display';\n\nexport const RecordDetails = () => (\n <JsonTree\n value={{ name: 'Acme', active: true, contacts: [] }}\n emptyStringLabel=\"Empty text\"\n emptyArrayLabel=\"No items\"\n emptyObjectLabel=\"No properties\"\n arrowButtonCollapsedLabel=\"Expand node\"\n arrowButtonExpandedLabel=\"Collapse node\"\n />\n);\n```\n\nEach entry has an `id`, `label`, and JSON `value`. Use entries when display labels differ from stored keys. The default expands depths 0 and 1. Override `shouldExpandNodeInitially={({ depth }) => depth === 0}` to expand only the root; later expansion is owned by each node.\n\n`getNodeHighlighting(keyPath)` returns `blue`, `red`, `partial-blue`, or `undefined`. `onNodeValueClick` receives the displayed text: leaf values as strings, and the matching empty label for empty strings, arrays, and objects. The tree displays data and does not edit it.\n\nWhen `onNodeValueClick` is provided, values are native buttons named by their displayed text. Tab moves focus to a value; Enter, Space, or a pointer click activates it. Without the callback, values remain non-interactive text. Value buttons do not submit enclosing forms.\n\n## Props\n\n<JsonTreeReference />\n\n<PageBanner illustration=\"page-cover-hierarchy\" />\n","api":{"name":"JsonTree","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/json-tree","props":[{"name":"arrowButtonCollapsedLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible label for the expand control on a collapsed node."},{"name":"arrowButtonExpandedLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible label for the collapse control on an expanded node."},{"name":"emptyArrayLabel","type":"string","required":true,"defaultValue":null,"description":"Display text for an empty array."},{"name":"emptyObjectLabel","type":"string","required":true,"defaultValue":null,"description":"Display text for an empty object."},{"name":"emptyStringLabel","type":"string","required":true,"defaultValue":null,"description":"Display text for an empty string."},{"name":"entries","type":"JsonTreeEntry[]","required":false,"defaultValue":null,"description":"Named entries with stable id, label, and JSON value fields. Supply entries or value, not both."},{"name":"getNodeHighlighting","type":"GetJsonNodeHighlighting","required":false,"defaultValue":null,"description":"Returns blue, red, or partial-blue highlighting for a node key path."},{"name":"onNodeValueClick","type":"((valueAsString: string) => void)","required":false,"defaultValue":null,"description":"Called with the clicked value as displayed: leaf values as strings, and the empty label for empty strings, arrays, and objects."},{"name":"shouldExpandNodeInitially","type":"((params: ShouldExpandNodeInitiallyProps) => boolean)","required":false,"defaultValue":"({ depth }: ShouldExpandNodeInitiallyProps) =>\n depth <= 1","description":"Chooses initial expansion from the node keyPath and depth. The default expands the first two depths."},{"name":"value","type":"JsonValue","required":false,"defaultValue":null,"description":"JSON value to display. Supply value or entries, not both."}]}},{"name":"TintedIconTile","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: TintedIconTile\ndescription: An icon on a tinted background derived from a theme color.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport TintedIconTileReference from '/snippets/ui/generated/components/data-display/tinted-icon-tile.mdx';\n\n## Overview\n\nPass icon content through the lowercase `icon` node slot. The tile derives its background and inherited foreground color from the theme palette. Icon content is decorative. Keep a visible label beside it, or give the root `role=\"img\"` and an accessible name for a standalone labeled image.\n\n<StoryEmbed\n storyId=\"ui-components-data-display-tintedicontile--display\"\n title=\"Company icon on a tinted tile\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { TintedIconTile } from 'twenty-ui/components/data-display';\nimport { IconBuildingSkyscraper } from 'twenty-ui/icon';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const CompanyLabel = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>\n <TintedIconTile icon={<IconBuildingSkyscraper size={16} />} color=\"blue\" />\n <Text>Companies</Text>\n </Text>\n);\n```\n\n## Geometry and native composition\n\nThe tile defaults to 16px through the spacing token and uses the small border-radius token. Set icon dimensions and stroke on the node itself. Root `style` or `className` controls tile width, height, border, shape, and colors; explicit styles override palette defaults. Custom artwork should inherit `currentColor` when it uses the palette foreground.\n\n```tsx\nimport { TintedIconTile } from 'twenty-ui/components/data-display';\n\nexport const CustomCompanyTile = () => (\n <TintedIconTile\n icon={\n <svg width=\"20\" height=\"20\" viewBox=\"0 0 20 20\" fill=\"currentColor\">\n <path d=\"M2 2h16v16H2z\" />\n </svg>\n }\n color=\"blue\"\n role=\"img\"\n aria-label=\"Companies\"\n render={<span />}\n style={{ width: 32, height: 32 }}\n />\n);\n```\n\nNative attributes, events, `className`, `style`, and `ref` target the outer div. `render` replaces that target through Base UI composition while preserving the decorative icon content. Name the surrounding control when composing a tile into an action.\n\nReplace `Icon={CompanyIcon}` with `icon={<CompanyIcon size={16} />}`. Move the former `size` and `stroke` options to the icon node, and use root styles for custom tile dimensions.\n\n## Props\n\n<TintedIconTileReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n","api":{"name":"TintedIconTile","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/tinted-icon-tile","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the tile root."},{"name":"color","type":"string | null","required":false,"defaultValue":"gray","description":"Theme palette name used to derive the background and foreground shades. Invalid names use the default theme color."},{"name":"icon","type":"ReactNode","required":true,"defaultValue":null,"description":"Decorative icon content. The caller controls its dimensions and stroke."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the div root while preserving icon content and native props."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles override tile geometry and palette defaults."}]}},{"name":"StackIcon","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: StackIcon\ndescription: A 16px icon with a smaller item stacked on its bottom-right corner.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport StackIconReference from '/snippets/ui/generated/components/data-display/stack-icon.mdx';\n\n## Overview\n\nPass the main icon through the `icon` node slot and the stacked item through `stackedIcon`. The container is 16px wide and tall; the stacked item is positioned absolutely at 8px from the left and 7px from the top so it overflows the bottom-right corner. A 12px square avatar is the intended size for an application logo. Both nodes are decorative, so keep a visible label beside the icon.\n\nLeave room for the stacked item's overflow when placing neighboring content. The example uses a 12px gap between the icon container and its label.\n\n<StoryEmbed\n storyId=\"ui-components-data-display-stackicon--display\"\n title=\"Company icon with a stacked logo\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { StackIcon } from 'twenty-ui/components/data-display';\nimport { IconBuildingSkyscraper } from 'twenty-ui/icon';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const CompanyFieldLabel = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>\n <StackIcon\n icon={<IconBuildingSkyscraper size={16} />}\n stackedIcon={\n <Avatar size=\"xs\" shape=\"square\" variant=\"outline\" name=\"Stripe\" />\n }\n />\n <Text>Companies</Text>\n </Text>\n);\n```\n\nNative attributes, events, `className`, `style`, and `ref` target the outer div. `render` replaces that target through Base UI composition while preserving both icon nodes.\n\n## Props\n\n<StackIconReference />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"StackIcon","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/stack-icon","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the container root."},{"name":"icon","type":"ReactNode","required":true,"defaultValue":null,"description":"Main icon content. The caller controls its dimensions and stroke."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the div root while preserving the icon content and native props."},{"name":"stackedIcon","type":"ReactNode","required":true,"defaultValue":null,"description":"Smaller content stacked on the bottom-right corner of the main icon, such as a 12px avatar."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the container root."}]}},{"name":"Callout","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Callout\ndescription: Feedback with node content, actions, and caller-owned dismissal.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CalloutReference from '/snippets/ui/generated/components/feedback/callout.mdx';\n\n## Overview\n\n`Callout` combines title, description, icon, and action nodes. Use `status` for `neutral`, `info`, `success`, `warning`, or `error`. It defaults to `info` and supports the `soft` appearance. The status selects a gray, blue, green, orange, or red palette; `color` overrides that palette without changing the meaning.\n\n<StoryEmbed\n storyId=\"ui-feedback-callout--display\"\n title=\"Callout example\"\n height={230}\n/>\n\n## Usage\n\n```tsx\nimport { Callout } from 'twenty-ui/components/feedback';\n\nexport const WorkflowNotice = () => (\n <Callout\n status=\"neutral\"\n title=\"This form will appear in workflow runs.\"\n description=\"Because this workflow is not using a manual trigger, the form will not open on top of the interface. To fill it, open the corresponding workflow run and complete the form there.\"\n action={<Callout.Action>Learn more</Callout.Action>}\n />\n);\n```\n\n## Visual options\n\nCompare semantic statuses using the same content. Choose a status for the message meaning, and override color only when the surrounding design requires it.\n\n<StoryEmbed\n storyId=\"ui-feedback-callout--catalog\"\n title=\"Callout feedback statuses\"\n height={1010}\n/>\n\n## Dismissible notice\n\n```tsx\nimport { useState } from 'react';\nimport { Callout } from 'twenty-ui/components/feedback';\nimport { IconAlertTriangle } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const ImportNotice = ({ onReview }: { onReview: () => void }) => {\n const [isVisible, setIsVisible] = useState(true);\n\n return (\n <>\n {isVisible && (\n <Callout\n status=\"warning\"\n title=\"Some records need attention\"\n description=\"Review the missing email addresses before importing.\"\n icon={<IconAlertTriangle size={16} aria-hidden=\"true\" />}\n action={\n <Callout.Action onClick={onReview}>Review records</Callout.Action>\n }\n onDismiss={() => setIsVisible(false)}\n closeLabel=\"Dismiss import notice\"\n />\n )}\n <Button onClick={() => setIsVisible(true)}>Show notice</Button>\n </>\n );\n};\n```\n\n## Dismissal and labels\n\nPassing `onDismiss` exposes an accessible close button. Each pointer or keyboard activation calls it once. The callout remains rendered until its caller hides it. Omit `onDismiss` for a persistent message. `closeLabel` defaults to `Close`.\n\nYour application owns the content, actions, accessible names, and translations. Use `Callout.Action` for a small ghost button with regular font weight. It accepts Button props, including link attributes, disabled state, refs, and custom rendering; size and appearance are fixed. The action slot also accepts custom buttons, links, disabled controls, or multiple nodes. The default help icon is decorative; pass `icon={null}` to omit it or supply a node with appropriate accessible semantics. Twenty UI does not require an i18n provider.\n\n## Native integration\n\nNative attributes, `className`, `style`, and `ref` target the root `div`. Use `render` to compose a different root element or a callback receiving the root props and `{ status, variant, color }`. `title` and `description` are content slots. `fullWidth` removes the default 512px maximum width.\n\nThe component adds no live-region role or announcements. Supply native `role`, `aria-live`, and other accessible attributes when the surrounding workflow requires them.\n\n## Migration\n\nReplace the previous semantic `variant` with `status`, and constructor `Icon` with an `icon` node. Replace `{ label, onClick }` action objects with `Callout.Action` or custom controls. Replace `isClosable` and `onClose` with `onDismiss`, and conditionally render the callout in the caller when dismissal should hide it. Existing translated content and action labels stay in the application.\n\n## Props\n\n<CalloutReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Callout","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/callout","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional footer node. Use Callout.Action for the standard action or supply custom controls."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional class names merged onto the root."},{"name":"closeLabel","type":"string","required":false,"defaultValue":"Close","description":"Accessible name of the dismiss button. Defaults to `Close`."},{"name":"color","type":"\"blue\" | \"gray\" | \"green\" | \"orange\" | \"red\"","required":false,"defaultValue":"status palette","description":"Palette override: gray, blue, green, orange, or red. Defaults to the status palette."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional supporting content node. Empty slots are hidden."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Removes the default 512px maximum width."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":"decorative help icon","description":"Leading icon node. Defaults to a decorative help icon. Pass null to omit it."},{"name":"onDismiss","type":"(() => void)","required":false,"defaultValue":null,"description":"Shows a dismiss button and notifies the caller once per activation. The caller owns visibility."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CalloutState>","required":false,"defaultValue":null,"description":"Element or callback composition for the root. Receives status, variant, and color state."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"info","description":"Feedback meaning: neutral, info, success, warning, or error. Defaults to info."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles forwarded to the root."},{"name":"title","type":"ReactNode","required":true,"defaultValue":null,"description":"Main message node displayed beside the icon."},{"name":"variant","type":"\"soft\"","required":false,"defaultValue":"soft","description":"Supported appearance: soft."}],"parts":[{"name":"Action","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"InlineBanner","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: InlineBanner\ndescription: Inline feedback with node content, icons, and actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport InlineBannerReference from '/snippets/ui/generated/components/feedback/inline-banner.mdx';\n\n## Overview\n\n`InlineBanner` composes [Banner](/ui/primitives/feedback/banner) with a rounded inline layout and a decorative information icon. It shares Banner's independent `status`, `variant`, `color`, `icon` and `action` contracts. Its default appearance is `soft` and its default status is `info`.\n\n<StoryEmbed\n storyId=\"ui-feedback-inlinebanner--display\"\n title=\"Inline banner with an action\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { InlineBanner } from 'twenty-ui/components/feedback';\n\nexport const ModelsBanner = ({ onConfigure }: { onConfigure: () => void }) => (\n <InlineBanner\n status=\"error\"\n action={\n <InlineBanner.Action onClick={onConfigure}>\n Configure models\n </InlineBanner.Action>\n }\n >\n No AI models are enabled.\n </InlineBanner>\n);\n```\n\nThe `standard` layout fills the available width. Plain string children truncate, with keyboard focus, pointer hover or touch revealing the full string in a tooltip. Rich node children render directly, so embedded links and controls retain their own semantics. Compose explicit typography when rich content needs truncation.\n\nUse `layout=\"compact\"` for wrapping content, closer spacing and a maximum content width of 512px. Add `fullWidth` to remove that cap and fill the available parent width, including padding and borders. It defaults to `false` and does not change the standard layout, which already fills its parent. It has no bottom margin. Layout is independent of `solid` or `soft` appearance. `embedded` removes the standard layout's bottom margin.\n\n```tsx\nimport { InlineBanner } from 'twenty-ui/components/feedback';\nimport { IconInfoCircle } from 'twenty-ui/icon';\n\nexport const ConnectionBanner = () => (\n <InlineBanner\n layout=\"compact\"\n status=\"warning\"\n color=\"blue\"\n icon={<IconInfoCircle aria-hidden=\"true\" />}\n action={\n <InlineBanner.Action href=\"/settings/accounts\">\n Connection settings\n </InlineBanner.Action>\n }\n >\n Connect your account to sync contacts.\n </InlineBanner>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-feedback-inlinebanner--compact-link\"\n title=\"Compact banner with a destination link\"\n height={120}\n/>\n\n`InlineBanner.Action` provides a small outline button that inherits the banner’s displayed color, including explicit palette overrides and solid appearances. It supports Button interactions, links, refs and custom rendering. The `action` slot also accepts arbitrary controls.\n\nThe root target is a `div`. Native props, `className`, `style` and `ref` target that root; Base UI `render` can compose another element and receives resolved Banner state. `action` accepts any ReactNode, including multiple controls with their complete Button or link APIs. `icon={null}` removes the default icon.\n\nThe caller owns whether the banner is rendered and whether changes should be announced. Supply `role=\"status\"` and `aria-live=\"polite\"`, or an appropriate live-region wrapper, when needed. Status does not assign live-region semantics. Name action controls and mark decorative custom icons with `aria-hidden`.\n\n## Migration\n\nReplace `message` with `children`, `LeftIcon={Icon}` with `icon={<Icon />}`, and `button` configuration with an `action` node. Use `InlineBanner.Action` to keep action styling aligned with the banner. Replace `variant=\"compact\"` with `layout=\"compact\"`; standard is now the default layout. Use `status=\"error\"` for error meaning or `color=\"red\"` for a palette override.\n\n## Props\n\n<InlineBannerReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"InlineBanner","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/inline-banner","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trailing ReactNode. InlineBanner.Action supplies the shared banner action preset and inherits the resolved banner color; arbitrary controls are also accepted."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-provided content. Standard plain strings truncate with a focusable tooltip; rich nodes render directly. Compact content wraps."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged onto the root div or composed element."},{"name":"color","type":"\"blue\" | \"gray\" | \"green\" | \"orange\" | \"red\"","required":false,"defaultValue":"status palette","description":"Gray, blue, green, orange or red palette override. An omitted color follows status."},{"name":"embedded","type":"boolean","required":false,"defaultValue":"false","description":"Removes the standard bottom margin. Compact layouts have no bottom margin."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Fills the available parent width, including padding and borders, and removes the compact layout's 512px maximum. Defaults to false; standard layout already fills its parent."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":"decorative information icon","description":"Leading ReactNode. Defaults to a decorative information icon. Pass null to omit it."},{"name":"layout","type":"\"compact\" | \"standard\"","required":false,"defaultValue":"standard","description":"Standard full-width layout or compact wrapping layout with a 512px maximum content width. Defaults to standard."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or to the DOM element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, BannerState>","required":false,"defaultValue":null,"description":"Base UI root element or render callback, receiving native props/ref and resolved Banner state."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"info","description":"Feedback meaning: neutral, info, success, warning or error. Defaults to info. Roles and announcements remain caller-owned."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root div or composed element."},{"name":"variant","type":"\"soft\" | \"solid\"","required":false,"defaultValue":"soft","description":"Solid or soft appearance, independently of status and layout. Defaults to soft."}],"parts":[{"name":"Action","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"ToastProvider","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Toast\ndescription: Display status messages with optional details, actions, and progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ToastReference from '/snippets/ui/generated/components/feedback/toast.mdx';\nimport ToastProviderReference from '/snippets/ui/generated/components/feedback/toast-provider.mdx';\nimport ToasterReference from '/snippets/ui/generated/components/feedback/toaster.mdx';\n\n## Overview\n\n`Toast` renders one notification. Your application controls when it appears, its position, and when it is removed.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--display\"\n title=\"Toast example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SavedNotification = () => {\n const [isOpen, setIsOpen] = useState(true);\n\n return (\n <>\n <Button onClick={() => setIsOpen(true)}>Show notification</Button>\n {isOpen && (\n <Toast status=\"success\" progress={100} onClose={() => setIsOpen(false)}>\n Changes saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n## Visual options\n\nCompare neutral, success, error, information, and warning feedback with the same message and progress.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--catalog\"\n title=\"Toast feedback statuses\"\n height={530}\n/>\n\nFor application notifications, wrap the application in `ToastProvider`, mount a `Toaster` inside it, and use `useToast()` from descendants. Each provider owns an independent notification store, countdowns, and dismissal lifecycle. Multiple Toasters can mirror the same provider.\n\n## Application notifications\n\n```tsx\nimport { useState } from 'react';\n\nimport {\n ToastProvider,\n Toaster,\n useToast,\n} from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst SaveNotificationButton = () => {\n const { enqueueToast } = useToast();\n\n return (\n <Button\n onClick={() =>\n enqueueToast({\n children: 'Record saved',\n status: 'success',\n })\n }\n >\n Add saved notification\n </Button>\n );\n};\n\nexport const Notifications = () => {\n const [limit, setLimit] = useState(3);\n\n return (\n <ToastProvider limit={limit}>\n <SaveNotificationButton />\n <Button onClick={() => setLimit(1)}>Keep one notification</Button>\n <Button onClick={() => setLimit(3)}>Keep three notifications</Button>\n <Toaster />\n </ToastProvider>\n );\n};\n```\n\n`enqueueToast` accepts Toast props and an optional `dedupeKey`, and returns the notification ID. A matching visible key returns the existing ID without adding another notification. `updateToast({ id, ...changes })` patches that live notification. `closeToast(id)` dismisses one notification; `closeToast()` dismisses all visible notifications in the provider.\n\nThe provider defaults to three visible notifications. `limit` must be a positive integer and can change while the provider is mounted. Lowering it or adding above it dismisses the oldest visible notifications first. Increasing it leaves existing notifications unchanged and does not restore dismissed notifications. Configuration changes preserve the store, surviving IDs, order, and remaining countdown time.\n\n## Provider lifecycle\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--documentation\"\n title=\"Shared notification lifecycle\"\n height={430}\n/>\n\nMultiple Toasters inside a provider render the same notifications. Updates and dismissal apply to every mirror, and each notification has one shared countdown. Hover or focus inside any mirror pauses it; it resumes after all mirrors release both. Mounting another Toaster does not restart the countdown or create another callback lifecycle. Use separate providers for independent queues.\n\nFor provider notifications, expiry, the close button, `closeToast`, and limit eviction call the latest `onClose` once. The notification is already dismissed when the callback runs, so updates and repeated close requests for that ID have no effect. `onCancel` remains a separate action callback and does not dismiss automatically.\n\nDismissed notifications are inert during exit animations. Their entries are removed after all rendered mirrors finish their exit work or unmount. Unmounting the last Toaster clears dismissed entries and freezes the remaining time for visible notifications. Remounting a Toaster resumes that time. Unmounting the provider discards its notifications and cancels countdown and exit work without calling `onClose`. Captured `enqueueToast`, `updateToast`, and `closeToast` operations from that provider have no effect after it unmounts.\n\n`getToastProps` adapts each notification’s content and presentation. Set `duration` and `progress` in `enqueueToast` or `updateToast` so every mirror shares the same timing configuration. Existing timing overrides through `getToastProps` remain supported when all mirrors return the same duration and progress for a notification. The provider retains the ID, dismissal handler, and shared countdown.\n\n`container` selects a Toaster’s portal destination. When omitted, it uses the surrounding theme container or `document.body`. An explicit element renders there; `null` defers rendering. Visible notifications remain queued, with their countdowns paused while no Toaster is rendered. Portals retain the surrounding theme and direction. Set `aria-label` on each Toaster to localize its default region name, \"Notifications\", and give mirrored regions appropriate names.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--portal-documentation\"\n title=\"Scoped notification portal\"\n height={430}\n/>\n\n## Update a live notification\n\nUse the ID returned by `enqueueToast` to update content, feedback status, actions, or callbacks in place. Updates preserve the notification's ID and position. Unknown or dismissed IDs have no effect, including while the dismissal animation runs. Each `useToast()` call targets its closest provider.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster--updates-documentation\"\n title=\"Update a live notification\"\n height={380}\n/>\n\n```tsx\nimport { useToast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveButtonProps = {\n saveRecord: () => Promise<void>;\n onViewRecord: () => void;\n};\n\nexport const SaveButton = ({ saveRecord, onViewRecord }: SaveButtonProps) => {\n const { enqueueToast, updateToast } = useToast();\n\n const save = async () => {\n const id = enqueueToast({\n children: 'Saving record',\n status: 'info',\n progress: 0,\n });\n\n try {\n await saveRecord();\n updateToast({\n id,\n children: 'Record saved',\n status: 'success',\n progress: undefined,\n action: <Button onClick={onViewRecord}>View record</Button>,\n });\n } catch {\n updateToast({\n id,\n children: 'Record could not be saved',\n status: 'error',\n progress: undefined,\n });\n }\n };\n\n return <Button onClick={save}>Save record</Button>;\n};\n```\n\n`ToastUpdate` requires `id` and accepts partial Toast options. Omitted fields keep their current values. Explicit `undefined` clears an optional field or restores its component default, such as `progress: undefined` or `status: undefined`. Pass `null` to remove a content slot, including `description`, `icon`, or `action`. Setting `cancelLabel: null` hides the cancel control while preserving its callback. Callback changes take effect on the existing notification. `dedupeKey` belongs to enqueueing and cannot be updated.\n\n## Dismissal timing\n\nThe countdown defaults to 6,000 milliseconds. It pauses while the pointer is over the toast or keyboard focus is inside it, and resumes only after both leave. With multiple Toasters, pause state is shared across their mirrors. The visual countdown follows the remaining dismissal time. Automatic dismissal also works when reduced motion disables the animation.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-timing--documentation\"\n title=\"Toast timing controls\"\n height={480}\n/>\n\n| Operation | Countdown behavior |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Update content, status, actions, or callbacks | Preserve the remaining time. Repeated updates do not extend it. |\n| Supply `duration` to `updateToast` | Start a fresh duration, including when the value is unchanged. `duration: undefined` restores the default and restarts it. |\n| Change a standalone `Toast`'s `duration` prop | Start a fresh duration. Rendering the same value again keeps the remaining time. |\n| Set `duration: 0` | Keep the toast open until it is dismissed. |\n| Supply `progress` | Stop the countdown while progress is present. |\n| Remove `progress` | Start a fresh duration, or keep it open when its duration is zero. |\n| Update while hovered or focused | Apply the same rules, keeping the resulting countdown paused until both pointer and focus leave. |\n\nFor example, `updateToast({ id, children: 'Still saving' })` preserves the remaining time, while `updateToast({ id, duration: 6000 })` gives the reader another six seconds. These rules apply to the existing notification without changing its ID or position.\n\n## Dismissible notification\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveNotification = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <>\n <Button onClick={() => setVisible(true)}>Show saved notification</Button>\n {visible && (\n <Toast\n status=\"success\"\n description=\"Your changes are available to your team.\"\n duration={6000}\n onClose={() => setVisible(false)}\n >\n Record saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n`onClose` is called once by the close button or when the countdown completes. Remove the toast in that callback. Use `duration={0}` for a notification that stays open until dismissal.\n\n## Progress and cancellation\n\n```tsx\nimport { Toast } from 'twenty-ui/components/feedback';\n\ntype ImportProgressProps = { progress: number; onCancel: () => void };\n\nexport const ImportProgress = ({ progress, onCancel }: ImportProgressProps) => (\n <Toast\n status=\"info\"\n progress={progress}\n description=\"You can continue working while the import runs.\"\n onCancel={onCancel}\n cancelLabel=\"Cancel import\"\n >\n Importing records: {progress}%\n </Toast>\n);\n```\n\nPassing `progress` supplies a percentage and disables the countdown. Remove it after the operation finishes to start a fresh duration. Cancellation invokes `onCancel`; the parent owns cancellation and removal. `cancelLabel` accepts a React node for the button content. Children, `description`, `icon`, and `action` also accept caller-owned React nodes. Use Twenty UI controls for interactive actions and provide their accessible names.\n\n## Appearance and announcements\n\n`status` accepts `neutral`, `info`, `success`, `warning`, or `error` and defaults to `neutral`. It expresses feedback meaning and selects the icon and theme palette. Toast has one supported appearance, so it exposes no appearance `variant` or palette `color` option. Use `icon` to replace the icon, `icon={null}` to omit it, and `iconLabel` when the default icon needs its own accessible name.\n\nThe default role is `status` with polite announcements. Use `role=\"alert\"` for urgent feedback. Set `cancelLabel` and `closeLabel` to localize the controls, and allow enough time to read the content or interact with its actions.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, styles, class names, event handlers, and refs target the root. Use `render` to compose another element or component while retaining those props and the ref. Toaster portals inherit the surrounding theme and text direction.\n\n<ToastReference />\n\n### ToastProvider\n\n<ToastProviderReference />\n\n### Toaster\n\nNative div attributes, styles, class names, and refs target the notification region.\n\n<ToasterReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"ToastProvider","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/toast-provider","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Application content and any Toasters sharing this provider’s independent notification store and lifecycle."},{"name":"limit","type":"number","required":false,"defaultValue":"3","description":"Reactive maximum number of visible toasts, defaulting to three. Must be a positive integer. Lowering it or adding above it dismisses the oldest visible notifications and calls their onClose once. Surviving IDs, order, and countdowns are preserved."}]}},{"name":"Toaster","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Toast\ndescription: Display status messages with optional details, actions, and progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ToastReference from '/snippets/ui/generated/components/feedback/toast.mdx';\nimport ToastProviderReference from '/snippets/ui/generated/components/feedback/toast-provider.mdx';\nimport ToasterReference from '/snippets/ui/generated/components/feedback/toaster.mdx';\n\n## Overview\n\n`Toast` renders one notification. Your application controls when it appears, its position, and when it is removed.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--display\"\n title=\"Toast example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SavedNotification = () => {\n const [isOpen, setIsOpen] = useState(true);\n\n return (\n <>\n <Button onClick={() => setIsOpen(true)}>Show notification</Button>\n {isOpen && (\n <Toast status=\"success\" progress={100} onClose={() => setIsOpen(false)}>\n Changes saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n## Visual options\n\nCompare neutral, success, error, information, and warning feedback with the same message and progress.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--catalog\"\n title=\"Toast feedback statuses\"\n height={530}\n/>\n\nFor application notifications, wrap the application in `ToastProvider`, mount a `Toaster` inside it, and use `useToast()` from descendants. Each provider owns an independent notification store, countdowns, and dismissal lifecycle. Multiple Toasters can mirror the same provider.\n\n## Application notifications\n\n```tsx\nimport { useState } from 'react';\n\nimport {\n ToastProvider,\n Toaster,\n useToast,\n} from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst SaveNotificationButton = () => {\n const { enqueueToast } = useToast();\n\n return (\n <Button\n onClick={() =>\n enqueueToast({\n children: 'Record saved',\n status: 'success',\n })\n }\n >\n Add saved notification\n </Button>\n );\n};\n\nexport const Notifications = () => {\n const [limit, setLimit] = useState(3);\n\n return (\n <ToastProvider limit={limit}>\n <SaveNotificationButton />\n <Button onClick={() => setLimit(1)}>Keep one notification</Button>\n <Button onClick={() => setLimit(3)}>Keep three notifications</Button>\n <Toaster />\n </ToastProvider>\n );\n};\n```\n\n`enqueueToast` accepts Toast props and an optional `dedupeKey`, and returns the notification ID. A matching visible key returns the existing ID without adding another notification. `updateToast({ id, ...changes })` patches that live notification. `closeToast(id)` dismisses one notification; `closeToast()` dismisses all visible notifications in the provider.\n\nThe provider defaults to three visible notifications. `limit` must be a positive integer and can change while the provider is mounted. Lowering it or adding above it dismisses the oldest visible notifications first. Increasing it leaves existing notifications unchanged and does not restore dismissed notifications. Configuration changes preserve the store, surviving IDs, order, and remaining countdown time.\n\n## Provider lifecycle\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--documentation\"\n title=\"Shared notification lifecycle\"\n height={430}\n/>\n\nMultiple Toasters inside a provider render the same notifications. Updates and dismissal apply to every mirror, and each notification has one shared countdown. Hover or focus inside any mirror pauses it; it resumes after all mirrors release both. Mounting another Toaster does not restart the countdown or create another callback lifecycle. Use separate providers for independent queues.\n\nFor provider notifications, expiry, the close button, `closeToast`, and limit eviction call the latest `onClose` once. The notification is already dismissed when the callback runs, so updates and repeated close requests for that ID have no effect. `onCancel` remains a separate action callback and does not dismiss automatically.\n\nDismissed notifications are inert during exit animations. Their entries are removed after all rendered mirrors finish their exit work or unmount. Unmounting the last Toaster clears dismissed entries and freezes the remaining time for visible notifications. Remounting a Toaster resumes that time. Unmounting the provider discards its notifications and cancels countdown and exit work without calling `onClose`. Captured `enqueueToast`, `updateToast`, and `closeToast` operations from that provider have no effect after it unmounts.\n\n`getToastProps` adapts each notification’s content and presentation. Set `duration` and `progress` in `enqueueToast` or `updateToast` so every mirror shares the same timing configuration. Existing timing overrides through `getToastProps` remain supported when all mirrors return the same duration and progress for a notification. The provider retains the ID, dismissal handler, and shared countdown.\n\n`container` selects a Toaster’s portal destination. When omitted, it uses the surrounding theme container or `document.body`. An explicit element renders there; `null` defers rendering. Visible notifications remain queued, with their countdowns paused while no Toaster is rendered. Portals retain the surrounding theme and direction. Set `aria-label` on each Toaster to localize its default region name, \"Notifications\", and give mirrored regions appropriate names.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--portal-documentation\"\n title=\"Scoped notification portal\"\n height={430}\n/>\n\n## Update a live notification\n\nUse the ID returned by `enqueueToast` to update content, feedback status, actions, or callbacks in place. Updates preserve the notification's ID and position. Unknown or dismissed IDs have no effect, including while the dismissal animation runs. Each `useToast()` call targets its closest provider.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster--updates-documentation\"\n title=\"Update a live notification\"\n height={380}\n/>\n\n```tsx\nimport { useToast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveButtonProps = {\n saveRecord: () => Promise<void>;\n onViewRecord: () => void;\n};\n\nexport const SaveButton = ({ saveRecord, onViewRecord }: SaveButtonProps) => {\n const { enqueueToast, updateToast } = useToast();\n\n const save = async () => {\n const id = enqueueToast({\n children: 'Saving record',\n status: 'info',\n progress: 0,\n });\n\n try {\n await saveRecord();\n updateToast({\n id,\n children: 'Record saved',\n status: 'success',\n progress: undefined,\n action: <Button onClick={onViewRecord}>View record</Button>,\n });\n } catch {\n updateToast({\n id,\n children: 'Record could not be saved',\n status: 'error',\n progress: undefined,\n });\n }\n };\n\n return <Button onClick={save}>Save record</Button>;\n};\n```\n\n`ToastUpdate` requires `id` and accepts partial Toast options. Omitted fields keep their current values. Explicit `undefined` clears an optional field or restores its component default, such as `progress: undefined` or `status: undefined`. Pass `null` to remove a content slot, including `description`, `icon`, or `action`. Setting `cancelLabel: null` hides the cancel control while preserving its callback. Callback changes take effect on the existing notification. `dedupeKey` belongs to enqueueing and cannot be updated.\n\n## Dismissal timing\n\nThe countdown defaults to 6,000 milliseconds. It pauses while the pointer is over the toast or keyboard focus is inside it, and resumes only after both leave. With multiple Toasters, pause state is shared across their mirrors. The visual countdown follows the remaining dismissal time. Automatic dismissal also works when reduced motion disables the animation.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-timing--documentation\"\n title=\"Toast timing controls\"\n height={480}\n/>\n\n| Operation | Countdown behavior |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Update content, status, actions, or callbacks | Preserve the remaining time. Repeated updates do not extend it. |\n| Supply `duration` to `updateToast` | Start a fresh duration, including when the value is unchanged. `duration: undefined` restores the default and restarts it. |\n| Change a standalone `Toast`'s `duration` prop | Start a fresh duration. Rendering the same value again keeps the remaining time. |\n| Set `duration: 0` | Keep the toast open until it is dismissed. |\n| Supply `progress` | Stop the countdown while progress is present. |\n| Remove `progress` | Start a fresh duration, or keep it open when its duration is zero. |\n| Update while hovered or focused | Apply the same rules, keeping the resulting countdown paused until both pointer and focus leave. |\n\nFor example, `updateToast({ id, children: 'Still saving' })` preserves the remaining time, while `updateToast({ id, duration: 6000 })` gives the reader another six seconds. These rules apply to the existing notification without changing its ID or position.\n\n## Dismissible notification\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveNotification = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <>\n <Button onClick={() => setVisible(true)}>Show saved notification</Button>\n {visible && (\n <Toast\n status=\"success\"\n description=\"Your changes are available to your team.\"\n duration={6000}\n onClose={() => setVisible(false)}\n >\n Record saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n`onClose` is called once by the close button or when the countdown completes. Remove the toast in that callback. Use `duration={0}` for a notification that stays open until dismissal.\n\n## Progress and cancellation\n\n```tsx\nimport { Toast } from 'twenty-ui/components/feedback';\n\ntype ImportProgressProps = { progress: number; onCancel: () => void };\n\nexport const ImportProgress = ({ progress, onCancel }: ImportProgressProps) => (\n <Toast\n status=\"info\"\n progress={progress}\n description=\"You can continue working while the import runs.\"\n onCancel={onCancel}\n cancelLabel=\"Cancel import\"\n >\n Importing records: {progress}%\n </Toast>\n);\n```\n\nPassing `progress` supplies a percentage and disables the countdown. Remove it after the operation finishes to start a fresh duration. Cancellation invokes `onCancel`; the parent owns cancellation and removal. `cancelLabel` accepts a React node for the button content. Children, `description`, `icon`, and `action` also accept caller-owned React nodes. Use Twenty UI controls for interactive actions and provide their accessible names.\n\n## Appearance and announcements\n\n`status` accepts `neutral`, `info`, `success`, `warning`, or `error` and defaults to `neutral`. It expresses feedback meaning and selects the icon and theme palette. Toast has one supported appearance, so it exposes no appearance `variant` or palette `color` option. Use `icon` to replace the icon, `icon={null}` to omit it, and `iconLabel` when the default icon needs its own accessible name.\n\nThe default role is `status` with polite announcements. Use `role=\"alert\"` for urgent feedback. Set `cancelLabel` and `closeLabel` to localize the controls, and allow enough time to read the content or interact with its actions.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, styles, class names, event handlers, and refs target the root. Use `render` to compose another element or component while retaining those props and the ref. Toaster portals inherit the surrounding theme and text direction.\n\n<ToastReference />\n\n### ToastProvider\n\n<ToastProviderReference />\n\n### Toaster\n\nNative div attributes, styles, class names, and refs target the notification region.\n\n<ToasterReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Toaster","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/toaster","props":[{"name":"container","type":"HTMLElement | null","required":false,"defaultValue":null,"description":"Portal destination. Omit to use the theme container or document.body; null defers rendering. The provider retains visible notifications and pauses their countdowns while no Toaster is rendered."},{"name":"getToastProps","type":"((toast: ToastNotification) => Partial<Omit<ToastProps, \"ref\" | \"id\" | \"onClose\">>)","required":false,"defaultValue":null,"description":"Adapts notification content and presentation. The provider owns id, dismissal, and the shared countdown. Set timing through enqueueToast or updateToast; duration and progress overrides must match across Toasters sharing a provider."},{"name":"render","type":"RenderProp<Record<string, unknown>>","required":false,"defaultValue":null,"description":"Custom root element composed through Base UI."}]}},{"name":"FormFieldRow","entryPoint":"twenty-ui/components/input","content":"---\ntitle: FormFieldRow\ndescription: Align a field label, content and trailing controls in a shared row.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport FormFieldRowReference from '/snippets/ui/generated/components/input/form-field-row.mdx';\n\n## Overview\n\n`FormFieldRow` lays out a field label, optional decorative icon, field content and trailing controls. Use it for composer fields or other aligned field groups. Your application owns field values, validation, permissions and persistence.\n\n<StoryEmbed\n storyId=\"ui-input-formfieldrow--display\"\n title=\"Form field row\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { FormFieldRow, LightButton } from 'twenty-ui/components/input';\nimport { Input } from 'twenty-ui/primitives/input';\n\nexport const SubjectField = () => {\n const [subject, setSubject] = useState('Project update');\n\n return (\n <FormFieldRow\n label=\"Subject\"\n hasDivider={false}\n trailing={\n <LightButton size=\"sm\" onClick={() => setSubject('')}>\n Clear\n </LightButton>\n }\n >\n <Input\n variant=\"plain\"\n aria-label=\"Subject\"\n value={subject}\n onValueChange={setSubject}\n />\n </FormFieldRow>\n );\n};\n```\n\n## Layout and labels\n\n`labelWidth` defaults to 80 pixels and accepts a CSS width. Use the same value on sibling rows to align their labels. The label column is capped at 40% of the row, and content can wrap in narrow layouts. `startIcon` is decorative; the caller supplies its dimensions. Set `hasDivider={false}` on a final row when the surrounding surface provides its border.\n\nThe root is a group named by `label`. Supply `aria-label` or `aria-labelledby` when the visible label is omitted, and label each nested input separately. The row does not move focus or disable nested controls. Those controls retain their own keyboard behavior and focus styling.\n\n`contentPaddingInline` defaults to the `--t-spacing-2` theme token, which is 8 pixels in the standard theme, and accepts a CSS padding value. Numeric values use pixels. Set `contentPaddingInline={0}` to align recipient chips and an input with the row inset when there is no visible label.\n\n<StoryEmbed\n storyId=\"ui-input-formfieldrow--without-label\"\n title=\"Recipient row without a visible label\"\n height={110}\n/>\n\n## Events and customization\n\nNative attributes, event handlers, `className`, `style`, `ref` and `render` apply to the group root. Forward supplied props and ref when replacing the root through `render`. An `onClick` handler shows a pointer cursor. The caller owns click-to-focus behavior and guards events from nested controls or portals when needed. `isHoverable` independently enables a neutral hover background.\n\n`trailingProps` applies native attributes, handlers and ref to the existing trailing wrapper. Its `className` is merged with the shared layout class. Use its `onClick` handler to stop a trailing action from triggering a row click handler. The wrapper exists only when `trailing` has renderable content.\n\n## Props\n\n<FormFieldRowReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"FormFieldRow","entryPoint":"twenty-ui/components/input","slug":"components/input/form-field-row","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Field content, such as plain inputs, recipient chips, selectors or toggles. The caller owns input labels, state and click-to-focus behavior."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the group root."},{"name":"contentPaddingInline","type":"PaddingInline<string | number>","required":false,"defaultValue":"var(--t-spacing-2)","description":"Inline padding around the field content, defaulting to the --t-spacing-2 theme token (8 pixels in the standard theme). Numbers use pixels; CSS padding values are also supported. Set 0 to align content with the row inset when no visible label is present."},{"name":"hasDivider","type":"boolean","required":false,"defaultValue":"true","description":"Shows a decorative bottom divider. Set false on the final row when the surrounding surface supplies its own border."},{"name":"isHoverable","type":"boolean","required":false,"defaultValue":"false","description":"Enables a neutral hover background independently of click handlers. Keyboard focus remains on nested controls without changing the row background."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Optional visible field label and default group name. Supply aria-label or aria-labelledby when the label is omitted. Label each nested input separately."},{"name":"labelWidth","type":"Width<string | number>","required":false,"defaultValue":"80","description":"Preferred label column width, capped at 40% of the row. Numbers use pixels; use the same width for aligned sibling rows."},{"name":"onClick","type":"MouseEventHandler<HTMLDivElement>","required":false,"defaultValue":null,"description":"Native group click handler. Providing a handler shows a pointer cursor; the caller guards nested-control and portaled events as needed."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the group root div."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the group root. Forward its props and ref."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional decorative icon before the label. The caller controls icon dimensions."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the group root."},{"name":"trailing","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trailing content. Nested controls retain their own keyboard focus and event behavior."},{"name":"trailingProps","type":"Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"children\">","required":false,"defaultValue":null,"description":"Native props, event handlers and ref applied to the trailing content wrapper. The wrapper is rendered only when trailing content is present; className is merged with the shared layout class."}]}},{"name":"ImageInput","entryPoint":"twenty-ui/components/input","content":"---\ntitle: ImageInput\ndescription: Image selection, preview, and caller-owned upload actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ImageInputReference from '/snippets/ui/generated/components/input/image-input.mdx';\n\n## Overview\n\n`ImageInput` combines an image preview, a native file picker, and upload, remove, or abort actions. `onFileSelect` fires when a file is selected. Your application validates and uploads the file, owns upload progress and cancellation, and supplies the preview URL through `src`.\n\n<StoryEmbed\n storyId=\"ui-input-imageinput--display\"\n title=\"Choose, preview, and remove an image\"\n height={140}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { ImageInput } from 'twenty-ui/components/input';\n\nexport const WorkspaceImage = () => {\n const [preview, setPreview] = useState<{\n src?: string;\n reader?: FileReader;\n }>({});\n\n return (\n <ImageInput\n helperText=\"Choose a square image for your workspace.\"\n src={preview.src}\n onFileSelect={(file) => {\n const reader = new FileReader();\n setPreview((current) => ({ src: current.src, reader }));\n reader.onload = () => {\n setPreview((current) => {\n if (current.reader !== reader) {\n return current;\n }\n\n return { src: reader.result?.toString() };\n });\n };\n reader.readAsDataURL(file);\n }}\n onRemove={() => setPreview({})}\n />\n );\n};\n```\n\nThe example keeps the current preview while reading a replacement and ignores reads from removed or superseded selections.\n\n## Selection and preview\n\nThe preview and Upload button open the same native file picker. `onFileSelect` receives the selected `File`; it does not start an upload itself. Canceling or returning an empty selection leaves the current image unchanged. The file input clears after selection so the same file can be selected again, and the callback's `File` remains usable.\n\nFront components support native selection and readable `File` contents. The SDK-built React and Preact flows are verified in Chromium with pointer, Enter and Space activation. The picker opens only from a trusted click inside the component. Worker-created object URLs assigned to an image `src` support previews.\n\n`accept` defaults to `image/*` and filters the file picker. Validate allowed formats, dimensions, and size in your application. This callback-driven selector does not retain a file for native form submission. Its action buttons use `type=\"button\"`, so they do not submit a surrounding form.\n\nAn empty or failed image shows a placeholder. Changing `src` retries the preview, including after an earlier image failed to load. Removal calls `onRemove`; update `src` after your application removes the image. The application owns local preview URLs and revokes worker-created object URLs when they are no longer needed. The renderer owns cleanup of its host preview URLs.\n\n## Root and file input props\n\n`className`, `style`, and `ref` apply to the root div. The default root ref receives an `HTMLDivElement`; use `inputRef` for the hidden file input. Use `render={<div ... />}` to supply native root attributes or event handlers. Keep that root non-interactive, since the module already contains buttons. `dir` applies to both the root and file input; use `dir=\"rtl\"` for right-to-left layout.\n\nNative file input attributes are top-level props, including `accept`, `capture`, `name`, `id`, `title`, `form`, `required`, accessible attributes, data attributes, and event handlers. They apply to the hidden input. `inputRef` receives its `HTMLInputElement`. The control always uses `type=\"file\"`, accepts one file, and resets its value after every selection. `children`, `dangerouslySetInnerHTML`, `type`, `multiple`, `value`, `defaultValue`, and `hidden` cannot be customized.\n\nNative `required` validation still sees an empty input after selection because the input resets. Validate completed uploads in your application.\n\n`onChange` receives the native change event while the input still contains the selected file. The input then resets before `onFileSelect` fires. Native event props follow React's input contract. `onAbort` is the upload abort action.\n\n## Uploading and disabled states\n\n`isUploading` marks the root busy and makes selection and removal unavailable. Controls that were available stay focusable, so keyboard focus is not lost when an upload starts. Supply `onAbort` to replace Upload with Abort during an upload. Abort works before the first image URL exists. The application owns cancellation and sets `isUploading` back to `false` when the upload ends.\n\n`disabled` disables every action. Selection requires `onFileSelect`. Removal requires both `onRemove` and a nonempty `src`.\n\n<StoryEmbed\n storyId=\"ui-input-imageinput--uploading\"\n title=\"Image upload with an abort action\"\n height={140}\n/>\n\n## Labels, instructions, and errors\n\nSupply localized `uploadLabel`, `removeLabel`, and `abortLabel` strings. They default to `Upload`, `Remove`, and `Abort`. The upload label also names the preview button and the hidden file input. Native accessible attributes can provide a different file input name. `aria-describedby` also describes the selection buttons and combines with the application's helper and error text.\n\n`helperText` and `errorMessage` belong to the application. Both describe the selection controls, and errors are announced as alerts. There are no built-in file limits or product instructions.\n\n<StoryEmbed\n storyId=\"ui-input-imageinput--with-error\"\n title=\"Image input with instructions and an error\"\n height={160}\n/>\n\n## Migration\n\nReplace `onUpload` with `onFileSelect`. Keep `accept` as a top-level prop. The callback still receives a `File`; keep existing validation and upload code in your application.\n\n```tsx\nimport { ImageInput } from 'twenty-ui/components/input';\n\nexport const WorkspaceImageSelector = ({\n uploadImage,\n}: {\n uploadImage: (file: File) => void;\n}) => <ImageInput onFileSelect={uploadImage} accept=\"image/png, image/jpeg\" />;\n```\n\n## Props\n\n<ImageInputReference />\n\n<PageBanner illustration=\"page-cover-image\" />\n","api":{"name":"ImageInput","entryPoint":"twenty-ui/components/input","slug":"components/input/image-input","props":[{"name":"abortLabel","type":"string","required":false,"defaultValue":"Abort","description":"Label for the Abort action."},{"name":"accept","type":"string","required":false,"defaultValue":"image/*","description":"Native file picker filter. Defaults to image/*. The caller validates allowed formats."},{"name":"aria-describedby","type":"string","required":false,"defaultValue":null,"description":"Accessible description references for the hidden file input and selection buttons, combined with helperText and errorMessage."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name of the hidden file input. Defaults to uploadLabel."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"Accessible name reference for the hidden file input."},{"name":"capture","type":"boolean | \"user\" | \"environment\"","required":false,"defaultValue":null,"description":"Native device capture hint for the file picker."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the root element."},{"name":"dir","type":"string","required":false,"defaultValue":null,"description":"Text direction applied to both the root and hidden file input."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables file selection, removal, and abort actions."},{"name":"errorMessage","type":"string | null","required":false,"defaultValue":null,"description":"Application error, displayed as an alert and associated with the selection controls."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Native form identifier associated with the hidden file input."},{"name":"helperText","type":"string","required":false,"defaultValue":null,"description":"Application instructions, associated with the selection controls."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Native identifier of the hidden file input."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the hidden single-file HTMLInputElement."},{"name":"isUploading","type":"boolean","required":false,"defaultValue":"false","description":"Marks the module busy. Selection and removal controls that would otherwise be enabled stay focusable but unavailable. Shows Abort when onAbort is supplied."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Native name of the hidden file input."},{"name":"onAbort","type":"(() => void)","required":false,"defaultValue":null,"description":"Shows an abort action while uploading. It can cancel the first upload before a src exists."},{"name":"onChange","type":"ChangeEventHandler<HTMLInputElement, HTMLInputElement>","required":false,"defaultValue":null,"description":"Native file input change event, fired while the selected file is present and before the input resets. The input does not retain a file for form submission."},{"name":"onFileSelect","type":"((file: File) => void)","required":false,"defaultValue":null,"description":"Fires when a file is selected and receives its usable File after the input resets. Empty and canceled selections do not call it. Selection is disabled when omitted. The caller owns validation and uploading."},{"name":"onRemove","type":"(() => void)","required":false,"defaultValue":null,"description":"Requests removal of the current image. Removal is disabled without this callback or a nonempty src."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div element."},{"name":"removeLabel","type":"string","required":false,"defaultValue":"Remove","description":"Label for the Remove action."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Custom root element or render function. Supply root native attributes here and keep a non-interactive root."},{"name":"required","type":"boolean","required":false,"defaultValue":null,"description":"Native file input requirement. The input resets after selection, so the caller validates completed uploads."},{"name":"src","type":"string | null","required":false,"defaultValue":null,"description":"Resolved image URL. Empty or failed images show the image placeholder."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline style applied to the root element."},{"name":"title","type":"string","required":false,"defaultValue":null,"description":"Native title of the hidden file input."},{"name":"uploadLabel","type":"string","required":false,"defaultValue":"Upload","description":"Label for the preview, Upload action, and hidden file input."}]}},{"name":"DatePicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: DatePicker\ndescription: Share the existing calendar engine while browsing months independently from the selected date.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DatePickerReference from '/snippets/ui/generated/components/input/date-picker.mdx';\n\n## Overview\n\n`DatePicker` shares the `react-datepicker` calendar engine used by Twenty's date and date-time inputs. It provides date-only values and independent control over the selected date and viewed month.\n\n<StoryEmbed\n storyId=\"ui-components-datepicker--display\"\n title=\"DatePicker example\"\n height={330}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { DatePicker } from 'twenty-ui/components/input';\n\nexport const ChooseDate = () => {\n const [value, setValue] = useState<string | null>('2026-10-07');\n const [viewedMonth, setViewedMonth] = useState('2026-10');\n\n return (\n <DatePicker\n aria-label=\"Choose a date\"\n value={value}\n onValueChange={setValue}\n viewedMonth={viewedMonth}\n onViewedMonthChange={setViewedMonth}\n weekStart={1}\n weekdayLabels={['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']}\n locale=\"en-US\"\n previousMonthLabel=\"Previous month\"\n nextMonthLabel=\"Next month\"\n monthLabel=\"Month\"\n yearLabel=\"Year\"\n />\n );\n};\n```\n\n## Selection and browsing\n\nChanging the month or year calls `onViewedMonthChange` and leaves `value` unchanged. Choosing an available day calls `onValueChange` when the selected date changes.\n\nUse `onValueSelect` to commit a date or close a product picker. It receives the canonical `YYYY-MM-DD` date even when the user chooses the already-selected day. Keep closing behavior in the application adapter.\n\nUpdate each controlled prop in its matching callback. Prop changes do not select a replacement date. The default header provides month and year selectors and previous and next buttons; its year selector lists up to 100 years before and after the viewed year.\n\n## Date values and localization\n\nPass canonical Gregorian date-only strings: `YYYY-MM-DD` for `value` and highlighted range bounds, and `YYYY-MM` for `viewedMonth`. Set `value={null}` for no selection. These values contain no time or timezone. Supported years are 0001 through 9999.\n\n`locale` formats the default month/year header and full weekday titles when custom `weekdayLabels` are supplied. Day labels and the underlying calendar retain the existing `react-datepicker` locale behavior.\n\n`weekStart` sets the first column, using 0 for Sunday through 6 for Saturday. Use `weekdayLabels` for seven short visible labels in Sunday-first order, regardless of `weekStart`. The calendar engine supplies weekday names when this prop is omitted.\n\nCurrent-day presentation follows the calendar engine's browser-clock behavior. Product adapters own timezone conversion, initial date fallbacks, member preferences, and scheduling data.\n\n## Existing calendar behavior\n\nDay rendering, accessibility markup, keyboard date navigation, and unavailable-date handling use `react-datepicker`. Visible days from neighboring months remain selectable when available.\n\nSet `isDateUnavailable` to prevent selection of dates according to your application's policy. The callback receives a canonical `YYYY-MM-DD` string. Set `disabled` to disable date selection and the default header controls.\n\n`isKeyboardNavigationDisabled` defaults to `false`. Existing product input adapters can set it to preserve their keyboard behavior. Header controls keep their native keyboard interaction.\n\n## Highlighted ranges and read-only views\n\nPass `highlightedRange={{ start: '2026-10-05', end: '2026-10-11' }}` to highlight an inclusive date range. The application computes the range; highlighting does not select multiple dates or change `value`.\n\nUse `readOnly` to display a computed range or selected date while allowing month and year browsing. Use `isGridHidden` for a month-only navigator that retains the same header.\n\n## Custom headers\n\nUse `renderHeader` to compose an existing product header with date inputs, time inputs, or application-specific controls. Its `DatePickerHeaderProps` argument provides these values and actions:\n\n| Property | Purpose |\n| --- | --- |\n| `viewedMonth` | Current `YYYY-MM` month. |\n| `onPreviousMonth`, `onNextMonth` | Browse to the adjacent month. |\n| `onMonthChange` | Browse to a month number from 1 through 12. |\n| `onYearChange` | Browse to the supplied year. |\n| `isPreviousMonthDisabled`, `isNextMonthDisabled` | Whether each adjacent-month action is unavailable. |\n\nThese header actions change the viewed month and leave the selected date unchanged.\n\n```tsx\nimport { useState } from 'react';\nimport { DatePicker } from 'twenty-ui/components/input';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const CalendarWithProductHeader = () => {\n const [value, setValue] = useState<string | null>('2026-10-07');\n const [viewedMonth, setViewedMonth] = useState('2026-10');\n\n return (\n <DatePicker\n aria-label=\"Choose a date\"\n value={value}\n onValueChange={setValue}\n viewedMonth={viewedMonth}\n onViewedMonthChange={setViewedMonth}\n weekStart={1}\n locale=\"en-US\"\n previousMonthLabel=\"Previous month\"\n nextMonthLabel=\"Next month\"\n monthLabel=\"Month\"\n yearLabel=\"Year\"\n renderHeader={({\n viewedMonth: month,\n onPreviousMonth,\n onNextMonth,\n isPreviousMonthDisabled,\n isNextMonthDisabled,\n }) => (\n <Text\n style={{\n display: 'flex',\n alignItems: 'center',\n gap: themeCssVariables.spacing[2],\n }}\n >\n <Button size=\"sm\" disabled={isPreviousMonthDisabled} onClick={onPreviousMonth}>\n Previous month\n </Button>\n <Text>{month}</Text>\n <Button size=\"sm\" disabled={isNextMonthDisabled} onClick={onNextMonth}>\n Next month\n </Button>\n </Text>\n )}\n />\n );\n};\n```\n\n## Composition and product adapters\n\nSupply a group name with `aria-label` or `aria-labelledby`. Native attributes, `className`, `style`, and `ref` apply to the root. Use `render` to compose a different root while preserving the supplied props and ref.\n\nPass `loadingFallback` to preserve a product loading surface while the calendar engine loads. The default fallback is a 300px-high `Skeleton`.\n\nFor the default header, `portalContainer` mounts selector popups in a host-provided container. `onNavigationOpenChange` receives `{ open, control }` for `month` or `year`, with `open: true` when opening starts and `open: false` after closing completes. Hosts can retain their popup and focus handling through dismissal. Custom headers own their popup integration.\n\nKeep product headers, text inputs, time editing, timezone conversion, clear actions, and relative-filter computation in `twenty-front`. Date, date-time, and month-only adapters can compose this shared calendar engine with `highlightedRange`, `readOnly`, and `isGridHidden` as needed.\n\n## Props\n\n<DatePickerReference />\n\n<PageBanner illustration=\"calendar-emails\" />\n","api":{"name":"DatePicker","entryPoint":"twenty-ui/components/input","slug":"components/input/date-picker","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name of the calendar group."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element that labels the calendar group."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the root element."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables date selection and the default header controls."},{"name":"highlightedRange","type":"{ start: string; end: string; }","required":false,"defaultValue":null,"description":"Inclusive YYYY-MM-DD start and end dates to highlight. The application computes the range independently from the selected date."},{"name":"isDateUnavailable","type":"((date: string) => boolean)","required":false,"defaultValue":null,"description":"Returns whether a canonical YYYY-MM-DD date cannot be selected. The calendar engine handles unavailable-date presentation and navigation."},{"name":"isGridHidden","type":"boolean","required":false,"defaultValue":"false","description":"Hides weekday and date rows while retaining the header for a month-only navigator."},{"name":"isKeyboardNavigationDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables keyboard date navigation in the calendar engine for compatibility with existing input wrappers. Header controls retain their native keyboard behavior."},{"name":"loadingFallback","type":"ReactNode","required":false,"defaultValue":"300px-high Skeleton","description":"Custom Suspense fallback while the calendar engine loads. Defaults to a 300px-high Skeleton."},{"name":"locale","type":"string","required":true,"defaultValue":null,"description":"Locale for the default month/year header and custom weekday titles. Engine day labels retain their existing locale behavior; values remain Gregorian date-only strings."},{"name":"monthLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default month selector."},{"name":"nextMonthLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default next-month button."},{"name":"onNavigationOpenChange","type":"((args: { open: boolean; control: \"month\" | \"year\"; }) => void)","required":false,"defaultValue":null,"description":"Reports { open, control } when a default month or year popup starts opening, and when it finishes closing or its selector unmounts. Header arrow actions do not call this callback."},{"name":"onValueChange","type":"(date: string) => void","required":true,"defaultValue":null,"description":"Called when choosing an available day changes the selected date. Month and year browsing does not select another date."},{"name":"onValueSelect","type":"((date: string) => void)","required":false,"defaultValue":null,"description":"Called with the selected YYYY-MM-DD date after choosing an available day, including the already-selected day. Use it to commit or close a product picker."},{"name":"onViewedMonthChange","type":"(month: string) => void","required":true,"defaultValue":null,"description":"Requests the month shown by calendar navigation without changing the selected date."},{"name":"portalContainer","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Mount container for the default month and year selector popups. Accepts the shared Select portal container contract."},{"name":"previousMonthLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default previous-month button."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Prevents date selection while allowing month and year browsing and displaying the selected date or highlighted range."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Composes the root element while preserving its props and contents."},{"name":"renderHeader","type":"((props: DatePickerHeaderProps) => ReactNode)","required":false,"defaultValue":null,"description":"Renders a product header with the viewed month, previous/next actions, month numbers from 1 through 12, year change actions, and navigation-disabled states. Header actions only browse months."},{"name":"role","type":"AriaRole","required":false,"defaultValue":"group","description":"Root semantics. Defaults to a group; the caller supplies its accessible name."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root element."},{"name":"value","type":"string | null","required":true,"defaultValue":null,"description":"Controlled selected Gregorian date in YYYY-MM-DD form, or null for no selection."},{"name":"viewedMonth","type":"string","required":true,"defaultValue":null,"description":"Controlled Gregorian month in YYYY-MM form. It is independent from the selected date."},{"name":"weekdayLabels","type":"readonly [string, string, string, string, string, string, string]","required":false,"defaultValue":null,"description":"Optional short weekday labels in Sunday-first order. The calendar engine supplies weekday names when omitted."},{"name":"weekStart","type":"0 | 1 | 2 | 3 | 4 | 5 | 6","required":true,"defaultValue":null,"description":"First weekday column: 0 for Sunday through 6 for Saturday."},{"name":"yearLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default year selector."}]}},{"name":"SearchInput","entryPoint":"twenty-ui/components/input","content":"---\ntitle: SearchInput\ndescription: Controlled search text with optional actions, such as a filter popup.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SearchInputReference from '/snippets/ui/generated/components/input/search-input.mdx';\n\n## Overview\n\n`SearchInput` supplies a search icon and text input. `onValueChange` receives the new string; `onChange` receives the native React change event. Filtering, fetching, and debouncing belong to your application.\n\n<StoryEmbed\n storyId=\"ui-input-searchinput--display\"\n title=\"SearchInput example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { SearchInput } from 'twenty-ui/components/input';\n\nexport const RecordSearch = () => {\n const [value, setValue] = useState('');\n\n return (\n <SearchInput\n value={value}\n onValueChange={setValue}\n placeholder=\"Search...\"\n />\n );\n};\n```\n\nUse `aria-label` or `aria-labelledby` for an accessible name.\n\nNative input props, `className`, `style`, and `ref` apply to the input itself. The shared `InputGroup` owns the search adornment and focus treatment. The wrapper that lays out the field and its actions takes no props; place `SearchInput` in your own container to size or position it. Use `size=\"sm\"` for a compact search field.\n\n## Actions\n\n`actions` renders controls after the search field. Compose a filter popup with a [Dropdown](/ui/components/navigation/dropdown) whose trigger is an `IconButton`, and give that button an accessible name.\n\n```tsx\nimport { useState } from 'react';\nimport { IconButton, SearchInput } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { IconFilter } from 'twenty-ui/icon';\n\nexport const FilteredPeopleSearch = () => {\n const [search, setSearch] = useState('');\n const [includeInactive, setIncludeInactive] = useState(false);\n\n return (\n <SearchInput\n aria-label=\"Search people\"\n placeholder=\"Name or email\"\n value={search}\n onValueChange={setSearch}\n actions={\n <Dropdown.Root type=\"panel\">\n <Dropdown.Trigger\n render={\n <IconButton aria-label=\"Filter people\">\n <IconFilter />\n </IconButton>\n }\n />\n <Dropdown.Content align=\"end\">\n <Dropdown.Section>\n <SettingsRow\n checked={includeInactive}\n onCheckedChange={setIncludeInactive}\n >\n Include inactive people\n </SettingsRow>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Root>\n }\n />\n );\n};\n```\n\n`disabled` disables only the text input; disable action controls separately. With `size=\"sm\"`, pass `size=\"sm\"` to the action controls as well.\n\n<StoryEmbed\n storyId=\"ui-input-searchinput--with-filter\"\n title=\"SearchInput with a filter popup\"\n height={320}\n/>\n\n## Props\n\n<SearchInputReference />\n\n<PageBanner illustration=\"page-cover-search\" />\n","api":{"name":"SearchInput","entryPoint":"twenty-ui/components/input","slug":"components/input/search-input","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Controls rendered after the search field, such as a filter Dropdown. Set their size and accessible names on the controls."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name when aria-labelledby is absent."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element that labels the input. Takes precedence over aria-label."},{"name":"autoFocus","type":"boolean","required":false,"defaultValue":null,"description":"Focuses the input when mounted."},{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the input."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables the text input. Controls in actions keep their own state."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"false","description":"Shows the group focus border. Defaults to false for all search inputs. Set true to opt in. Error styling remains visible."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Input ID, generated when omitted."},{"name":"onChange","type":"((event: BaseUIEvent<ChangeEvent<HTMLInputElement, HTMLInputElement>>) => void)","required":false,"defaultValue":null,"description":"Native input change event handler."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Called with the new text. The application owns filtering."},{"name":"placeholder","type":"string","required":false,"defaultValue":null,"description":"Hint shown when the input is empty. Also used as the accessible name if no explicit label is supplied."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the native input element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, InputState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the input group."},{"name":"style","type":"CSSProperties | ((state: InputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"textAlign","type":"\"end\" | \"start\"","required":false,"defaultValue":null,"description":"Aligns text to the logical start or end of the input. Follows the text direction."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"Current search text."}]}},{"name":"AnimatedIconCrossfade","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: AnimatedIconCrossfade\ndescription: Crossfade between two icons as application state changes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AnimatedIconCrossfadeReference from '/snippets/ui/generated/components/layout/animated-icon-crossfade.mdx';\n\n## Overview\n\n`AnimatedIconCrossfade` crossfades between `activeIcon` and `inactiveIcon` node content according to `isActive`. It does not own the action or state. Compose it inside a labeled [Button](/ui/primitives/input/button).\n\n<StoryEmbed\n storyId=\"ui-components-layout-animatediconcrossfade--display\"\n title=\"AnimatedIconCrossfade example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { AnimatedIconCrossfade } from 'twenty-ui/components/layout';\nimport { IconPencil, IconX } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const EditToggle = () => {\n const [isEditing, setIsEditing] = useState(false);\n\n return (\n <Button\n size=\"sm\"\n aria-expanded={isEditing}\n onClick={() => setIsEditing(!isEditing)}\n startIcon={\n <AnimatedIconCrossfade\n isActive={isEditing}\n activeIcon={<IconX size={14} />}\n inactiveIcon={<IconPencil size={14} />}\n />\n }\n >\n Edit actions\n </Button>\n );\n};\n```\n\nBoth nodes stay mounted as `isActive` changes, preserving their local state. The layers animate opacity and scale, and disable transitions for reduced motion. Both layers are decorative; keep the accessible action name on the surrounding control. For a standalone labeled image, set `role=\"img\"` and `aria-label` on the root.\n\nNative attributes, events, `className`, `style`, and `ref` target an inline span, which can sit inside a button. `render` replaces that target through Base UI composition. The root dimensions default to the small icon theme token. Size each icon node explicitly, and use root width and height styles for larger artwork.\n\nReplace `ActiveIcon` and `InactiveIcon` constructors with lowercase `activeIcon` and `inactiveIcon` nodes. Move the former `size` option to the node dimensions and root styles.\n\n## Props\n\n<AnimatedIconCrossfadeReference />\n\n<PageBanner illustration=\"card-page-sync-recovery\" />\n","api":{"name":"AnimatedIconCrossfade","entryPoint":"twenty-ui/components/layout","slug":"components/layout/animated-icon-crossfade","props":[{"name":"activeIcon","type":"ReactNode","required":true,"defaultValue":null,"description":"Decorative node content for the active state."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the inline span root."},{"name":"inactiveIcon","type":"ReactNode","required":true,"defaultValue":null,"description":"Decorative node content for the inactive state."},{"name":"isActive","type":"boolean","required":true,"defaultValue":null,"description":"Shows activeIcon when true and inactiveIcon otherwise."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the span root while preserving both transition layers."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root, including width and height."}]}},{"name":"ThemeProvider","entryPoint":"twenty-ui/theme","content":"---\ntitle: Theming\ndescription: Use Twenty UI theme tokens and scope theme overrides to part of your application.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ThemeProviderReference from '/snippets/ui/generated/theme/theme-provider.mdx';\n\n## Overview\n\nTwenty UI components read public CSS custom properties prefixed with `--t-`. Prefer semantic tokens such as `background.secondary` and `font.color.primary` when styling your own components; these values adapt to the active palette.\n\n## Use tokens in styles\n\n`themeCssVariables` maps token paths to CSS variable references. Use it for values that CSS resolves:\n\n```tsx\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const Summary = () => (\n <section\n style={{\n background: themeCssVariables.background.secondary,\n color: themeCssVariables.font.color.primary,\n padding: themeCssVariables.spacing[4],\n borderRadius: themeCssVariables.border.radius.md,\n }}\n >\n Three tasks are due today.\n </section>\n);\n```\n\nThe equivalent CSS uses variables directly:\n\n```css\n.summary {\n background: var(--t-background-secondary);\n color: var(--t-font-color-primary);\n padding: var(--t-spacing-4);\n border-radius: var(--t-border-radius-md);\n}\n```\n\n## Read resolved values\n\n`useTheme()` reads the active provider's computed tokens. Use it when a component expects a JavaScript number, such as an icon size. The provider needs the theme stylesheet to be loaded in the browser to resolve CSS variables.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { useTheme } from 'twenty-ui/theme';\n\nexport const CompleteIcon = () => {\n const theme = useTheme();\n\n return <IconCheck size={theme.icon.size.md} aria-hidden />;\n};\n```\n\nEvery entry in `themeCssVariables` is a CSS reference string, including numeric tokens. Do not perform arithmetic on those strings. On the server, resolved browser values are unavailable; see [Server rendering](/ui/ssr).\n\n## Scope an override\n\nPass `applyToRoot={false}` to apply a theme to a subtree. Override public CSS variables by their full name:\n\n```tsx\nimport { type ReactNode } from 'react';\nimport { ThemeProvider } from 'twenty-ui/theme';\n\nexport const EmbeddedPanel = ({ children }: { children: ReactNode }) => (\n <ThemeProvider\n colorScheme=\"light\"\n applyToRoot={false}\n overrides={{ '--t-background-secondary': '#f4f6ff' }}\n >\n {children}\n </ThemeProvider>\n);\n```\n\nA scoped provider adds a wrapper with `display: contents`; it does not create a layout box. It also supplies a container for components that support themed portals. Portals created by other libraries need their own container configuration.\n\nVariables prefixed with `--tw-` are private component details. Use public props and `--t-` tokens instead of depending on those variables.\n\nSee the [token reference](/ui/tokens) for the available names and palette values.\n\n## Explicit values and scale\n\nThe `theme` prop supplies resolved JavaScript theme values instead of reading computed styles. It also flows to nested providers unless they supply another explicit theme. This changes values read by hooks; load the appropriate stylesheet and use CSS overrides to style components.\n\n`scale` writes `--t-scale-user` on the document root. It only affects interfaces whose CSS consumes that variable and is ignored by scoped providers. `className` applies to a scoped wrapper; passing it alone does not create a wrapper. `overrides` creates a scope even when `applyToRoot` remains true.\n\n## ThemeProvider props\n\n<ThemeProviderReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n","api":{"name":"ThemeProvider","entryPoint":"twenty-ui/theme","slug":"theme/theme-provider","props":[{"name":"applyToRoot","type":"boolean","required":false,"defaultValue":"true","description":"Applies the color-scheme class to the document root. Set false for a scoped wrapper."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Components that share this theme."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to a scoped wrapper; no wrapper is created for className alone."},{"name":"colorScheme","type":"\"dark\" | \"light\"","required":true,"defaultValue":null,"description":"Explicit light or dark palette; load its stylesheet before rendering."},{"name":"overrides","type":"ThemeOverrides","required":false,"defaultValue":null,"description":"CSS custom-property overrides. Supplying them creates a scoped wrapper."},{"name":"scale","type":"number","required":false,"defaultValue":null,"description":"Root interface scale stored in --t-scale-user. Ignored for scoped providers; application CSS must consume the variable."},{"name":"theme","type":"ThemeType | typeof THEME_LIGHT","required":false,"defaultValue":null,"description":"Explicit resolved theme values, bypassing computed-style token resolution."}]}},{"name":"Icon","entryPoint":"twenty-ui/icon/provider","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"Icon","entryPoint":"twenty-ui/icon/provider","slug":"icon/icon","props":[{"name":"aria-hidden","type":"boolean","required":false,"defaultValue":null,"description":"Hides a decorative icon from assistive technology."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class forwarded to the resolved icon."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"Color forwarded to the resolved icon."},{"name":"name","type":"string","required":true,"defaultValue":null,"description":"Icon name resolved through IconsProvider. Unknown names fall back to Icon123."},{"name":"size","type":"string | number","required":false,"defaultValue":null,"description":"Width and height forwarded to the resolved icon."},{"name":"stroke","type":"string | number","required":false,"defaultValue":null,"description":"Stroke width forwarded to the resolved icon."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Styles forwarded to the resolved icon."}]}},{"name":"IconsProvider","entryPoint":"twenty-ui/icon/provider","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"IconsProvider","entryPoint":"twenty-ui/icon/provider","slug":"icon/icons-provider","props":[{"name":"children","type":"Element","required":true,"defaultValue":null,"description":"One React element containing consumers of Icon or useIcons. Loads the complete icon map asynchronously."}]}},{"name":"IllustrationIconWrapper","entryPoint":"twenty-ui/icon","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"IllustrationIconWrapper","entryPoint":"twenty-ui/icon","slug":"icon/illustration-icon-wrapper","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Illustration content to center inside the wrapper."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged with the illustration wrapper styling."}]}},{"name":"ThinkingOrbitLoaderIcon","entryPoint":"twenty-ui/icon","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"ThinkingOrbitLoaderIcon","entryPoint":"twenty-ui/icon","slug":"icon/thinking-orbit-loader-icon","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the SVG. The icon is always hidden from assistive technology."},{"name":"size","type":"string | number","required":false,"defaultValue":"14","description":"Width and height in pixels."}]}},{"name":"ComponentStorybookLayout","entryPoint":"twenty-ui/testing","content":"---\ntitle: Storybook helpers\ndescription: Present component previews and variant catalogs with twenty-ui/testing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ComponentStorybookLayoutReference from '/snippets/ui/generated/testing/component-storybook-layout.mdx';\nimport GroupedCatalogReference from '/snippets/ui/generated/testing/grouped-catalog.mdx';\n\n## Overview\n\n`twenty-ui/testing` exposes Storybook decorators, preview layout helpers, and media-query overrides. Configure styles and a [ThemeProvider](/ui/theming) in your Storybook preview before rendering themed components.\n\n## Story roles\n\nStart each component guide with a `Display` story showing one representative, usable example. Follow it with Usage code that reproduces the preview using public imports. Compound components demonstrate their parts together. Providers and accessibility helpers demonstrate their effect in context.\n\nAdd a `Catalog` when a labeled comparison helps readers choose between visual options. Group variants, sizes, colors, and states separately; use a matrix only when comparing two dimensions together is useful. A simple component can use one alternative example. Dialogs, menus, and other interactive components usually need focused examples for each workflow.\n\nPreserve comprehensive screenshot coverage in separate `VisualRegression` stories, including dark themes and variant matrices. Tag those stories with `!autodocs` and keep them out of the component guides.\n\nName other stories after what they demonstrate, such as `Controlled`, `WithValidation`, or `MultipleSelection`. Keep interaction checks in separate stories with `play` functions. The display and other documentation previews remain usable by the reader without automated actions.\n\n## ComponentDecorator\n\n`ComponentDecorator` wraps a story in `ComponentStorybookLayout`. Set `parameters.container.width` and `parameters.container.height` in pixels. It also reads the story's `inverted` and `accent` args to choose an optional background.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentDecorator } from 'twenty-ui/testing';\n\nconst meta = {\n component: Button,\n decorators: [ComponentDecorator],\n parameters: { container: { width: 240, height: 100 } },\n};\n\nexport default meta;\n\nexport const Display = { args: { children: 'Save changes' } };\n```\n\n## GroupedCatalog\n\n`GroupedCatalog` gives curated catalogs a shared layout for headings, wrapping rows, and spacing. Each group has a `label` and an `examples` array. Every example needs a unique `label` within its group; it can carry any other data used by `renderExample`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { GroupedCatalog } from 'twenty-ui/testing';\n\nconst groups = [\n {\n label: 'Variants',\n examples: [\n { label: 'Solid', variant: 'solid' as const },\n { label: 'Outline', variant: 'outline' as const },\n ],\n },\n];\n\nexport const ButtonCatalog = () => (\n <GroupedCatalog\n groups={groups}\n renderExample={({ label, variant }) => (\n <>\n <Text>{label}</Text>\n <Button variant={variant}>Save changes</Button>\n </>\n )}\n />\n);\n```\n\n<GroupedCatalogReference />\n\n## CatalogDecorator\n\n`CatalogDecorator` renders combinations of up to four dimensions from `parameters.catalog.dimensions`. Each dimension has a `name`, `values`, a `props(value)` mapper, and an optional `labels(value)` formatter. The mapper returns the props for that cell. `parameters.catalog.options.elementContainer` accepts `width`, `style`, and `className`.\n\n```tsx\nimport { Button, type ButtonVariant } from 'twenty-ui/primitives/input';\nimport { CatalogDecorator } from 'twenty-ui/testing';\n\nconst meta = { component: Button };\nexport default meta;\n\nexport const VisualRegression = {\n tags: ['!autodocs'],\n args: { children: 'Save changes' },\n decorators: [CatalogDecorator],\n parameters: {\n catalog: {\n dimensions: [\n {\n name: 'variant',\n values: ['outline', 'solid', 'ghost'],\n props: (variant: ButtonVariant) => ({ variant }),\n },\n ],\n },\n },\n};\n```\n\n## ComponentStorybookLayout\n\nUse the layout directly when composing a preview outside a decorator. It accepts one child element.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentStorybookLayout } from 'twenty-ui/testing';\n\nexport const ButtonPreview = () => (\n <ComponentStorybookLayout width={240} height={100}>\n <Button>Save changes</Button>\n </ComponentStorybookLayout>\n);\n```\n\n<ComponentStorybookLayoutReference />\n\n## Media query overrides\n\nUse `overrideMediaQueryMatches` in a story's `beforeEach` to force responsive hook results. Return its cleanup function to restore `window.matchMedia` after the story:\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { overrideMediaQueryMatches } from 'twenty-ui/testing';\nimport { MOBILE_MEDIA_QUERY, useIsMobile } from 'twenty-ui/utilities';\n\nconst ResponsiveAction = () => {\n const isMobile = useIsMobile();\n\n return <Button fullWidth={isMobile}>Save changes</Button>;\n};\n\nconst meta = { component: ResponsiveAction };\nexport default meta;\n\nexport const Mobile = {\n beforeEach: () => overrideMediaQueryMatches({ [MOBILE_MEDIA_QUERY]: true }),\n};\n```\n\nQueries omitted from the override retain their native behavior. Override `TOUCH_DEVICE_MEDIA_QUERY` separately when an example depends on touch input. These overrides control `matchMedia` results; use a Storybook viewport to change CSS media queries and the preview width.\n\n## Documentation previews\n\nStories embedded in the documentation must be presentational and have no `play` function. Keep interaction tests in separate stories. Share explicit `args`, `render`, `decorators`, and `parameters` when needed, rather than spreading an interaction story into a preview. The documentation embed check rejects stories marked with Storybook's `play-fn` tag, including inherited play functions.\n\nEach component guide's first embed must reference a story exported as `Display`. Give every embed a descriptive title for its iframe and enough height to show the example. The shared preview supplies light and dark tabs and a link to Storybook, where readers can use controls to explore props.\n\nRun `npx nx check:ui-stories twenty-docs` to check the required display, preview titles, references, and presentation rules. Run `npx nx check:ui twenty-docs` to validate the generated API references and typecheck copyable examples.\n\n<PageBanner illustration=\"card-page-testing\" />\n","api":{"name":"ComponentStorybookLayout","entryPoint":"twenty-ui/testing","slug":"testing/component-storybook-layout","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"Background color override."},{"name":"children","type":"Element","required":true,"defaultValue":null,"description":"The component preview element."},{"name":"height","type":"number","required":false,"defaultValue":null,"description":"Container height in pixels. Defaults to fit-content."},{"name":"width","type":"number","required":false,"defaultValue":null,"description":"Container width in pixels. When omitted, the container has a 300px minimum width."}]}},{"name":"GroupedCatalog","entryPoint":"twenty-ui/testing","content":"---\ntitle: Storybook helpers\ndescription: Present component previews and variant catalogs with twenty-ui/testing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ComponentStorybookLayoutReference from '/snippets/ui/generated/testing/component-storybook-layout.mdx';\nimport GroupedCatalogReference from '/snippets/ui/generated/testing/grouped-catalog.mdx';\n\n## Overview\n\n`twenty-ui/testing` exposes Storybook decorators, preview layout helpers, and media-query overrides. Configure styles and a [ThemeProvider](/ui/theming) in your Storybook preview before rendering themed components.\n\n## Story roles\n\nStart each component guide with a `Display` story showing one representative, usable example. Follow it with Usage code that reproduces the preview using public imports. Compound components demonstrate their parts together. Providers and accessibility helpers demonstrate their effect in context.\n\nAdd a `Catalog` when a labeled comparison helps readers choose between visual options. Group variants, sizes, colors, and states separately; use a matrix only when comparing two dimensions together is useful. A simple component can use one alternative example. Dialogs, menus, and other interactive components usually need focused examples for each workflow.\n\nPreserve comprehensive screenshot coverage in separate `VisualRegression` stories, including dark themes and variant matrices. Tag those stories with `!autodocs` and keep them out of the component guides.\n\nName other stories after what they demonstrate, such as `Controlled`, `WithValidation`, or `MultipleSelection`. Keep interaction checks in separate stories with `play` functions. The display and other documentation previews remain usable by the reader without automated actions.\n\n## ComponentDecorator\n\n`ComponentDecorator` wraps a story in `ComponentStorybookLayout`. Set `parameters.container.width` and `parameters.container.height` in pixels. It also reads the story's `inverted` and `accent` args to choose an optional background.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentDecorator } from 'twenty-ui/testing';\n\nconst meta = {\n component: Button,\n decorators: [ComponentDecorator],\n parameters: { container: { width: 240, height: 100 } },\n};\n\nexport default meta;\n\nexport const Display = { args: { children: 'Save changes' } };\n```\n\n## GroupedCatalog\n\n`GroupedCatalog` gives curated catalogs a shared layout for headings, wrapping rows, and spacing. Each group has a `label` and an `examples` array. Every example needs a unique `label` within its group; it can carry any other data used by `renderExample`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { GroupedCatalog } from 'twenty-ui/testing';\n\nconst groups = [\n {\n label: 'Variants',\n examples: [\n { label: 'Solid', variant: 'solid' as const },\n { label: 'Outline', variant: 'outline' as const },\n ],\n },\n];\n\nexport const ButtonCatalog = () => (\n <GroupedCatalog\n groups={groups}\n renderExample={({ label, variant }) => (\n <>\n <Text>{label}</Text>\n <Button variant={variant}>Save changes</Button>\n </>\n )}\n />\n);\n```\n\n<GroupedCatalogReference />\n\n## CatalogDecorator\n\n`CatalogDecorator` renders combinations of up to four dimensions from `parameters.catalog.dimensions`. Each dimension has a `name`, `values`, a `props(value)` mapper, and an optional `labels(value)` formatter. The mapper returns the props for that cell. `parameters.catalog.options.elementContainer` accepts `width`, `style`, and `className`.\n\n```tsx\nimport { Button, type ButtonVariant } from 'twenty-ui/primitives/input';\nimport { CatalogDecorator } from 'twenty-ui/testing';\n\nconst meta = { component: Button };\nexport default meta;\n\nexport const VisualRegression = {\n tags: ['!autodocs'],\n args: { children: 'Save changes' },\n decorators: [CatalogDecorator],\n parameters: {\n catalog: {\n dimensions: [\n {\n name: 'variant',\n values: ['outline', 'solid', 'ghost'],\n props: (variant: ButtonVariant) => ({ variant }),\n },\n ],\n },\n },\n};\n```\n\n## ComponentStorybookLayout\n\nUse the layout directly when composing a preview outside a decorator. It accepts one child element.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentStorybookLayout } from 'twenty-ui/testing';\n\nexport const ButtonPreview = () => (\n <ComponentStorybookLayout width={240} height={100}>\n <Button>Save changes</Button>\n </ComponentStorybookLayout>\n);\n```\n\n<ComponentStorybookLayoutReference />\n\n## Media query overrides\n\nUse `overrideMediaQueryMatches` in a story's `beforeEach` to force responsive hook results. Return its cleanup function to restore `window.matchMedia` after the story:\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { overrideMediaQueryMatches } from 'twenty-ui/testing';\nimport { MOBILE_MEDIA_QUERY, useIsMobile } from 'twenty-ui/utilities';\n\nconst ResponsiveAction = () => {\n const isMobile = useIsMobile();\n\n return <Button fullWidth={isMobile}>Save changes</Button>;\n};\n\nconst meta = { component: ResponsiveAction };\nexport default meta;\n\nexport const Mobile = {\n beforeEach: () => overrideMediaQueryMatches({ [MOBILE_MEDIA_QUERY]: true }),\n};\n```\n\nQueries omitted from the override retain their native behavior. Override `TOUCH_DEVICE_MEDIA_QUERY` separately when an example depends on touch input. These overrides control `matchMedia` results; use a Storybook viewport to change CSS media queries and the preview width.\n\n## Documentation previews\n\nStories embedded in the documentation must be presentational and have no `play` function. Keep interaction tests in separate stories. Share explicit `args`, `render`, `decorators`, and `parameters` when needed, rather than spreading an interaction story into a preview. The documentation embed check rejects stories marked with Storybook's `play-fn` tag, including inherited play functions.\n\nEach component guide's first embed must reference a story exported as `Display`. Give every embed a descriptive title for its iframe and enough height to show the example. The shared preview supplies light and dark tabs and a link to Storybook, where readers can use controls to explore props.\n\nRun `npx nx check:ui-stories twenty-docs` to check the required display, preview titles, references, and presentation rules. Run `npx nx check:ui twenty-docs` to validate the generated API references and typecheck copyable examples.\n\n<PageBanner illustration=\"card-page-testing\" />\n","api":{"name":"GroupedCatalog","entryPoint":"twenty-ui/testing","slug":"testing/grouped-catalog","props":[{"name":"groups","type":"{ label: string; examples: CatalogExample[]; }[]","required":true,"defaultValue":null,"description":"Labeled groups of examples. Each example has a unique label within its group and can include additional data for the renderer."},{"name":"renderExample","type":"(example: CatalogExample) => ReactNode","required":true,"defaultValue":null,"description":"Renders one example, including its visible label or accessible name. The layout supplies the surrounding cell and spacing."}]}},{"name":"getting-started","content":"---\ntitle: Getting started\ndescription: Install Twenty UI in a React application and use its components and themes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\n## Overview\n\nTwenty UI is Twenty's open-source React UI library. It provides foundational primitives, shared components, icons, and theme tokens with prebuilt CSS, so your application does not need a CSS-in-JS compiler.\n\n## Install\n\nFor an existing React application, install the library. React 19 is required.\n\n```bash\nyarn add twenty-ui\n```\n\nThe [code editor](/ui/components/code-editor/code-editor) has a separate entry point, `twenty-ui/components/code-editor`. Other components do not require Monaco. To use the code editor, install its optional peer dependencies and configure Monaco workers for your bundler before mounting it:\n\n```bash\nyarn add @monaco-editor/react monaco-editor\n```\n\nIf you are building a Twenty app, follow [Using Twenty UI components](/developers/extend/apps/layout/front-components#using-twenty-ui-components). The front component renderer supplies the workspace theme and has a different setup from a standalone browser application. Keep `twenty-ui`, `twenty-sdk`, and `twenty-client-sdk` on the same version.\n\n## Load styles and provide a theme\n\nImport the component stylesheet and a theme stylesheet once at your application entry point. `ThemeProvider` applies the active theme class and makes theme values available to components.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\nimport { ThemeProvider } from 'twenty-ui/theme';\n\nimport 'twenty-ui/style.css';\nimport 'twenty-ui/theme-light.css';\n\nexport const App = () => (\n <ThemeProvider colorScheme=\"light\">\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input name=\"email\" type=\"email\" placeholder=\"[email protected]\" />\n <Field.Description>Use your work email address.</Field.Description>\n </Field.Root>\n </ThemeProvider>\n);\n```\n\nThe component stylesheet includes a global reset. Review its effect when adding Twenty UI to an existing application.\n\n## Override styles\n\nTwenty UI puts component styles and the reset in the `twenty-ui` cascade layer. Styles you write outside a layer, such as a `className`, a CSS module, or a CSS-in-JS rule, override those layered rules regardless of selector specificity or import order. Theme stylesheets and the optional editor's global Monaco rules remain unlayered.\n\nGlobal element resets in your application are unlayered too, so they would override Twenty UI components. Declare a layer for them before Twenty UI's stylesheet loads:\n\n```css\n@layer reset, twenty-ui;\n\n@layer reset {\n button {\n font: inherit;\n }\n}\n```\n\nWith Tailwind CSS v4, place Twenty UI between Tailwind's base and utility layers:\n\n```css\n@layer theme, base, twenty-ui, components, utilities;\n```\n\n## Choose an entry point\n\nImport components from their public subpath to keep imports focused:\n\nPrimitives are foundational controls, including compound controls such as Select,\nPopover, and AlertDialog. Shared components combine primitives into recurring\ndesign presets and reusable app building blocks. Both receive data and callbacks\nfrom the application.\n\nUse [MainButton](/ui/components/input/main-button) for prominent actions and\n[LightButton](/ui/components/input/light-button) for lightweight actions. Both\ncome from `twenty-ui/components/input` and share the foundational\n[Button](/ui/primitives/input/button) interaction contract. Routing and page\nlayout remain in the application.\n\nEach primitive and shared component family has a matching public entry point, such as\n`twenty-ui/primitives/input` and `twenty-ui/components/settings`. The aggregate\n`twenty-ui/primitives` and `twenty-ui/components` entries export their respective families.\nThe root `twenty-ui` entry re-exports primitives, shared components, icons, theme tokens,\nand utilities. Assets, testing helpers, and the optional code editor have separate entry points.\n\n| Import | Contents |\n| ------------------------------------ | ------------------------------------------------------------------- |\n| `twenty-ui/assets` | Logos and static assets |\n| `twenty-ui/components` | All shared component families except the optional editor |\n| `twenty-ui/components/data-display` | Avatar groups, command blocks, JSON trees, metrics, and icon tiles |\n| `twenty-ui/components/feedback` | Callouts, inline banners, and notifications |\n| `twenty-ui/components/input` | Button presets, specialized inputs, pickers, and segmented controls |\n| `twenty-ui/components/layout` | Sections, overflowing lists, and icon transitions |\n| `twenty-ui/components/navigation` | Dropdowns, menu compositions, and tab actions |\n| `twenty-ui/components/settings` | Settings rows with labeled controls |\n| `twenty-ui/components/code-editor` | Code editor, editor header, and editor theme helpers |\n| `twenty-ui/primitives` | All primitive families |\n| `twenty-ui/primitives/accessibility` | Hidden elements and keyboard interaction helpers |\n| `twenty-ui/primitives/data-display` | Avatars, badges, chips, tags, color samples, and status indicators |\n| `twenty-ui/primitives/feedback` | Banners, progress indicators, loaders, and skeletons |\n| `twenty-ui/primitives/input` | Buttons and form controls |\n| `twenty-ui/primitives/layout` | Expansion, separators, direction, and resizing |\n| `twenty-ui/primitives/navigation` | Breadcrumbs, list items, and tabs |\n| `twenty-ui/primitives/surfaces` | Cards, dialogs, popovers, and tooltips |\n| `twenty-ui/primitives/typography` | Text, headings, shortcuts, and overflowing text |\n| `twenty-ui/icon` | [Icons and dynamic lookup](/ui/icons) |\n| `twenty-ui/testing` | [Storybook decorators and layouts](/ui/testing) |\n| `twenty-ui/theme` | Theme provider, hooks, and CSS variable references |\n| `twenty-ui/utilities` | Hooks and shared utilities |\n\nImport individual icons, such as `IconCheck`, from `twenty-ui/icon`. The dynamic icon provider includes the full icon catalog, so reserve it for interfaces that need to look up icons at runtime.\n\n## Responsive hooks\n\nImport `useIsMobile`, `useIsTouchDevice`, and `useMediaQuery` from `twenty-ui/utilities`.\n\n| Hook | Query | Use |\n| ---------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |\n| `useIsMobile()` | `MOBILE_MEDIA_QUERY`, up to and including `MOBILE_VIEWPORT` | Choose a compact layout. |\n| `useIsTouchDevice()` | `TOUCH_DEVICE_MEDIA_QUERY`, `(hover: none) and (pointer: coarse)` | Choose touch interaction behavior independently of width. |\n| `useMediaQuery(query)` | Any media query supported by `window.matchMedia` | Subscribe to a custom media query. |\n\nThe query constants come from `twenty-ui/utilities`; `MOBILE_VIEWPORT` comes from `twenty-ui/theme`. Subscriptions share one `MediaQueryList` per query and update when its match changes. Hooks return `false` during server rendering, the first hydration render, and when `window.matchMedia` is unavailable.\n\nIn a [Twenty front component](/developers/extend/apps/layout/front-components#current-limitations), width queries follow the widget's box. `useIsMobile` therefore follows the widget width, while `useIsTouchDevice` follows the device's primary input. Use [story overrides](/ui/testing#media-query-overrides) to exercise these states in Storybook.\n\n## Continue\n\n- [Theming](/ui/theming): use semantic tokens and scoped overrides.\n- [Dark mode](/ui/dark-mode): switch between light and dark palettes.\n\n## Browse the library\n\n- [Primitives](/ui/primitives/overview): foundational controls grouped by family, with usage examples and API references.\n- [Components](/ui/components/overview): shared design presets and reusable app building blocks composed from primitives.\n\n<PageBanner illustration=\"card-page-ui-library\" />\n"},{"name":"theming","content":"---\ntitle: Theming\ndescription: Use Twenty UI theme tokens and scope theme overrides to part of your application.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ThemeProviderReference from '/snippets/ui/generated/theme/theme-provider.mdx';\n\n## Overview\n\nTwenty UI components read public CSS custom properties prefixed with `--t-`. Prefer semantic tokens such as `background.secondary` and `font.color.primary` when styling your own components; these values adapt to the active palette.\n\n## Use tokens in styles\n\n`themeCssVariables` maps token paths to CSS variable references. Use it for values that CSS resolves:\n\n```tsx\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const Summary = () => (\n <section\n style={{\n background: themeCssVariables.background.secondary,\n color: themeCssVariables.font.color.primary,\n padding: themeCssVariables.spacing[4],\n borderRadius: themeCssVariables.border.radius.md,\n }}\n >\n Three tasks are due today.\n </section>\n);\n```\n\nThe equivalent CSS uses variables directly:\n\n```css\n.summary {\n background: var(--t-background-secondary);\n color: var(--t-font-color-primary);\n padding: var(--t-spacing-4);\n border-radius: var(--t-border-radius-md);\n}\n```\n\n## Read resolved values\n\n`useTheme()` reads the active provider's computed tokens. Use it when a component expects a JavaScript number, such as an icon size. The provider needs the theme stylesheet to be loaded in the browser to resolve CSS variables.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { useTheme } from 'twenty-ui/theme';\n\nexport const CompleteIcon = () => {\n const theme = useTheme();\n\n return <IconCheck size={theme.icon.size.md} aria-hidden />;\n};\n```\n\nEvery entry in `themeCssVariables` is a CSS reference string, including numeric tokens. Do not perform arithmetic on those strings. On the server, resolved browser values are unavailable; see [Server rendering](/ui/ssr).\n\n## Scope an override\n\nPass `applyToRoot={false}` to apply a theme to a subtree. Override public CSS variables by their full name:\n\n```tsx\nimport { type ReactNode } from 'react';\nimport { ThemeProvider } from 'twenty-ui/theme';\n\nexport const EmbeddedPanel = ({ children }: { children: ReactNode }) => (\n <ThemeProvider\n colorScheme=\"light\"\n applyToRoot={false}\n overrides={{ '--t-background-secondary': '#f4f6ff' }}\n >\n {children}\n </ThemeProvider>\n);\n```\n\nA scoped provider adds a wrapper with `display: contents`; it does not create a layout box. It also supplies a container for components that support themed portals. Portals created by other libraries need their own container configuration.\n\nVariables prefixed with `--tw-` are private component details. Use public props and `--t-` tokens instead of depending on those variables.\n\nSee the [token reference](/ui/tokens) for the available names and palette values.\n\n## Explicit values and scale\n\nThe `theme` prop supplies resolved JavaScript theme values instead of reading computed styles. It also flows to nested providers unless they supply another explicit theme. This changes values read by hooks; load the appropriate stylesheet and use CSS overrides to style components.\n\n`scale` writes `--t-scale-user` on the document root. It only affects interfaces whose CSS consumes that variable and is ignored by scoped providers. `className` applies to a scoped wrapper; passing it alone does not create a wrapper. `overrides` creates a scope even when `applyToRoot` remains true.\n\n## ThemeProvider props\n\n<ThemeProviderReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n"},{"name":"icons","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n"},{"name":"accessibility","content":"---\ntitle: Accessibility\ndescription: Label controls, preserve keyboard behavior, and test accessible Twenty UI interfaces.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\n## Overview\n\nMigrated interactive components use Base UI primitives for semantics and keyboard behavior. Your application still supplies meaningful labels, descriptions, error messages, and focus order.\n\n## Label every control\n\nUse `Field.Label` with an input to associate a visible label with the control. `Field.Description` supplies supporting text:\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => (\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input type=\"email\" name=\"email\" required />\n <Field.Description>\n We send account updates to this address.\n </Field.Description>\n <Field.Error>Enter a valid email address.</Field.Error>\n </Field.Root>\n);\n```\n\nUse [VisuallyHidden](/ui/primitives/accessibility/visually-hidden) when supporting text should remain available to assistive technology without being displayed.\n\nPlaceholders supplement labels; they do not replace them. For a control without visible text, supply an accessible name using `aria-label` or `aria-labelledby`.\n\n## Preserve native behavior\n\nUse the component's state and change props, such as `checked` and `onCheckedChange` on `Switch`. Keep focus indicators visible. When using `render` to replace an element, preserve the ref, event handlers, and attributes the component passes to it.\n\nA disabled control cannot be changed and is generally excluded from keyboard navigation and form submission. A read-only control retains its value and may remain focusable; choose the state that matches the interaction you intend.\n\n## Test the complete interface\n\nCheck keyboard navigation, labels, error announcements, focus movement in overlays, and zoom in the context where the component is used. Verify contrast in both palettes and after applying custom token overrides.\n\nTwenty UI's stories contain interaction and automated accessibility checks. Some stories still defer color-contrast checks, so those checks do not establish full accessibility conformance for an application.\n\n<PageBanner illustration=\"page-cover-accessibility\" />\n"}]}
+{"version":"2.56.0","pages":[{"name":"CountrySelect","entryPoint":"twenty-ui/components/input","content":"---\ntitle: CountrySelect\ndescription: A complete country picker and shared parts for prepared choices, stable identifiers, and null clearing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CountrySelectReference from '/snippets/ui/generated/components/input/country-select.mdx';\n\n## Overview\n\n`CountrySelect` provides a complete country picker with a labeled trigger, decorative flags, search, and a no-country choice. `CountrySelect.Root`, `CountrySelect.Trigger`, and `CountrySelect.Options` expose the same implementation for composition with [Dropdown](/ui/components/navigation/dropdown). Your application supplies country data and translated text and decides how selected identifiers map to stored values.\n\n<StoryEmbed\n storyId=\"ui-input-countryselect--display\"\n title=\"Country selection\"\n height={340}\n/>\n\n## Usage\n\nSupply prepared choices with unique stable string identifiers and display labels. The picker reports identifiers unchanged, independently of the displayed language. Flags are optional decorative React nodes. A choice can set `disabled: true` to remain visible without allowing selection.\n\n```tsx\nimport { CountrySelect } from 'twenty-ui/components/input';\n\nconst COUNTRIES = [\n { value: 'FR', label: 'France', flag: '🇫🇷' },\n { value: 'DE', label: 'Germany', flag: '🇩🇪' },\n { value: 'JP', label: 'Japan', flag: '🇯🇵' },\n];\n\nexport const ShippingCountry = () => (\n <CountrySelect\n label=\"Shipping country\"\n countries={COUNTRIES}\n defaultValue=\"FR\"\n searchLabel=\"Search countries\"\n noCountryLabel=\"No country\"\n noResultsLabel=\"No countries found\"\n />\n);\n```\n\n`defaultValue` initializes uncontrolled selection. Use `value` and `onValueChange` for controlled selection. Updating `value` externally updates both the trigger and the selected option, including while the popup is open.\n\n```tsx\nimport { useState } from 'react';\nimport { CountrySelect, type CountryChoice } from 'twenty-ui/components/input';\n\nexport const ControlledCountry = ({\n countries,\n}: {\n countries: readonly CountryChoice[];\n}) => {\n const [country, setCountry] = useState<string | null>('FR');\n\n return (\n <CountrySelect\n label=\"Country\"\n countries={countries}\n value={country}\n onValueChange={setCountry}\n />\n );\n};\n```\n\n## Shared parts\n\n`Root` owns the prepared choices and selected identifier. It adds no DOM element. `Trigger` reads that selection and displays its label and flag. `Options` reads the same data and renders searchable rows inside `Dropdown.SelectionGroup`. Dropdown owns opening, popup placement, pages, navigation, and focus.\n\n```tsx\nimport { CountrySelect, type CountryChoice } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\nexport const ShippingCountryParts = ({\n countries,\n}: {\n countries: readonly CountryChoice[];\n}) => (\n <CountrySelect.Root countries={countries} defaultValue=\"FR\">\n <Dropdown.Root type=\"picker\">\n <CountrySelect.Trigger label=\"Shipping country\" />\n <Dropdown.Content>\n <CountrySelect.Options\n aria-label=\"Shipping country\"\n searchLabel=\"Search countries\"\n />\n </Dropdown.Content>\n </Dropdown.Root>\n </CountrySelect.Root>\n);\n```\n\nThe shorthand assembles these parts internally. Both forms share selection, clearing, disabled behavior, search matching, and selected-option presentation. `closeOnSelect` defaults to `true`. Set it to `false` on the shorthand or `Options` when selection should keep the popup open.\n\n## Clearing and cancellation\n\n`null` represents no country. Selecting the no-country row reports `null`; passing `value={null}` clears a controlled picker. An empty string (`''`) is a valid supplied choice identifier and stays distinct from `null`.\n\n`onValueChange` receives the next identifier or `null` and Dropdown selection event details: `event`, `reason`, `trigger`, `cancel`, and `isCanceled`. Call `details.cancel()` before updating controlled state to preserve the current selection and keep the popup open. Repeated selection of the current identifier does not emit another value change.\n\nAn identifier absent from `countries` displays `noCountryLabel` and the no-country icon. Rendering it does not emit a change or overwrite the host value. The application decides how to handle stored values absent from the current choices.\n\n## Search and interaction\n\nSearch matches prepared display labels. It ignores letter case, optional accents in Latin, Greek, Arabic, and Hebrew text, and Cyrillic stress marks, treats the Cyrillic `ё` as `е`, and folds letters such as `ø`, `æ`, and `ß` into `o`, `ae`, and `ss`. It also ignores standalone accent characters such as `^`, `` ` ``, `´`, `¨`, and `ˇ`, so a pending dead key does not hide matches. Marks that form distinct letters remain significant, such as Japanese voicing marks, Indic vowel signs, and the Cyrillic `й`. A partly typed Korean syllable, such as ㅎ or 하, matches syllables that start with it, such as 한. `noCountryLabel` participates in the same search. A query with no matching options displays `noResultsLabel`.\n\nArrow keys, Home, and End move focus without changing the selected identifier. Enter or Space on an enabled option commits selection through its selection group. Escape and outside interaction use Dropdown dismissal and focus handling. Each picker has independent selection and popup state.\n\nDropdown search activation and IME protection still need integration work, as do lazy page sessions and inactive-page behavior. Both picker forms reset their own search on reopen, including popups kept mounted. Their shared implementation does not yet complete Dropdown's page and browsing lifecycle.\n\n`disabled` on `Root` or the shorthand prevents opening and selection. A picker with no supplied countries is disabled as well. If either condition occurs while its popup is open, the picker requests closure. Closing returns focus to the trigger. Controlled hosts must accept that close request through `onOpenChange`; the shorthand also suppresses the popup while disabled. After accepting the close request, enabling the picker again does not reopen it automatically. The trigger stays focusable and exposes `aria-disabled`. Disabled triggers skip consumer activation handlers. Function forms of `className`, `style`, and `render` receive `disabled: true` in the trigger state.\n\n## Labels and customization\n\nProvide a visible `label`, or use `aria-label` or `aria-labelledby` on the trigger. Referenced labels take precedence over a nonempty `aria-label`, which takes precedence over the visible label. With one of these names, the selected country describes the trigger. Otherwise the selected country names it. The popup inherits the trigger name unless caller-owned popup labels or a Dropdown title name it. The shorthand also names its options listbox from those trigger labels unless `optionsProps` supplies its own accessible name. In composed usage, give `Options` an `aria-label` or `aria-labelledby` for an explicit listbox name. Otherwise it references the registered Dropdown title or trigger content. A tooltip reveals the full selected label when it is truncated.\n\n`searchLabel` supplies the search input's placeholder and accessible name, `noCountryLabel` the no-country text, and `noResultsLabel` the empty-result text. They default to `Search`, `No country`, and `No results`. Pass translated strings when your application is localized. Custom `Trigger` children replace the selected country display; the caller owns that content and its accessible presentation.\n\nNative trigger attributes, event handlers, `className`, `style`, `ref`, and `render` target the trigger button. `wrapperProps` targets the surrounding div that also contains the visible label. `Options` native props, `ref`, and `render` target its selection group div. Its `render` function receives `{ value, multiple: false }`, where `value` is the public country identifier or `null`, rather than an internal option identifier. `searchProps` targets the search input; search value and change handling remain owned by the picker. The shorthand accepts the same search props directly and group attributes through `optionsProps`. Forward supplied props and refs when replacing an element through `render`.\n\n## Host integration and storage\n\nThe shorthand accepts Dropdown's `open`, `defaultOpen`, `onOpenChange`, `onEscapeKeyDown`, `onInteractOutside`, and `defaultPage`. Composed usage sets them on `Dropdown.Root`. `onOpenChange` currently reports only a boolean, matching Dropdown's public contract. Opening event details and general opening cancellation remain unavailable upstream. Escape and outside dismissal callbacks can call `event.preventDefault()` to keep the popup open.\n\n`popupProps` accepts all `Dropdown.Content` props except `children`, including popup native attributes, `ref`, `render`, positioning, portal destination, accessible names, and `keepMounted`. In composed usage, pass them directly to `Dropdown.Content`.\n\nKeep dropdown IDs, focus stacks, field metadata, persistence, and editing lifecycle in the host adapter. Twenty's frontend adapter uses stable country codes for picker identifiers and converts explicit selections back to existing source country-name values. Its stored empty string maps to picker `null`; unmatched legacy values stay stored until an explicit selection changes them. Translated display labels do not become stored country names. Applications with another storage format should make the conversion in their adapter as well.\n\nNative form submission, reset, `required`, `readOnly`, and Field integration for this custom picker remain deferred.\n\n## Front component renderer\n\nReact and Preact front component fixtures verify pointer opening, filtering, and selection through the shorthand and compound APIs, including controlled and uncontrolled values, null clearing and reselection, canceled changes, external controlled updates, disabled interaction, translated labels, and decorative flags. They also verify native trigger and search input props and refs, plus trigger and option-group render targets and refs. Search keyboard activation and IME handling, page-session lifetime, and full renderer portal, geometry, scrolling, outside dismissal, and focus restoration acceptance remain open.\n\n## Migration\n\nReplace the previous empty-string no-country sentinel with `null` in controlled values and selection state. An empty string (`''`) is now a valid choice identifier, so `value=\"\"` no longer means no country. Keep each `CountryChoice.value` stable; existing string identifiers can remain unchanged and display labels can be translated independently.\n\nUpdate `onValueChange` handlers to accept `string | null`. The callback now also receives `eventDetails` as its second argument, including `cancel()` to reject a selection. Handlers that do not need event details can continue using only the first argument.\n\nIf your storage uses `''` for no country, convert it to `null` before passing it to the picker and convert reported `null` back to `''` when persisting. Keep that compatibility conversion in the application adapter, and omit it when `''` is an intentional choice identifier.\n\n## Props\n\n<CountrySelectReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"CountrySelect","entryPoint":"twenty-ui/components/input","slug":"components/input/country-select","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Closes the popup after a selection. Defaults to true. Cancelled selection keeps it open."},{"name":"countries","type":"readonly CountryChoice[]","required":true,"defaultValue":null,"description":"Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the uncontrolled popup is initially open."},{"name":"defaultPage","type":"string","required":false,"defaultValue":null,"description":"Dropdown page shown when the popup opens. Defaults to root."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":null,"description":"Initial uncontrolled selected identifier. Defaults to null."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Prevents opening and selection while the trigger stays focusable. An empty country list is also disabled."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. Generated when omitted."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Optional visible label that names the trigger."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"noCountryLabel","type":"string","required":false,"defaultValue":null,"description":"Text of the no-country choice, also displayed when no country is selected."},{"name":"noResultsLabel","type":"string","required":false,"defaultValue":null,"description":"Text displayed when no choice matches the search."},{"name":"onEscapeKeyDown","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before Escape dismisses the popup. Call event.preventDefault() to keep it open."},{"name":"onInteractOutside","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before outside interaction or Tab dismisses the popup. Call event.preventDefault() to keep it open."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Reports popup opening and closing with the next boolean state, matching Dropdown.Root."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Reports the selected identifier or null with cancellable event details. Call details.cancel() to preserve selection and keep the popup open."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controls whether the country popup is open."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"optionsProps","type":"Omit<CountrySelectOptionsProps, \"closeOnSelect\" | \"searchLabel\" | \"noResultsLabel\" | \"searchProps\">","required":false,"defaultValue":null,"description":"Native props, ref, and render for the selection group div rendered by CountrySelect.Options."},{"name":"popupProps","type":"Omit<DropdownContentProps, \"children\">","required":false,"defaultValue":null,"description":"Dropdown.Content props, including native popup attributes, ref, render, positioning, portal destination, and keepMounted. Explicit popup accessible names override the trigger name. Children are owned by the picker."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the trigger element while preserving its behavior and props."},{"name":"searchLabel","type":"string","required":false,"defaultValue":null,"description":"Placeholder and accessible name of the search input."},{"name":"searchProps","type":"Omit<DropdownSearchProps, \"defaultValue\" | \"value\" | \"onValueChange\">","required":false,"defaultValue":null,"description":"Native search input props, ref, and render. Search value and change handling are owned by the picker."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled selected identifier. Null selects no country; undefined leaves selection uncontrolled."},{"name":"wrapperProps","type":"Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"children\">","required":false,"defaultValue":null,"description":"Native props and ref for the div around the trigger and its visible label. Children are owned by the picker."}],"parts":[{"name":"Root","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Picker composition containing Dropdown.Root, CountrySelect.Trigger, and CountrySelect.Options. Root adds no DOM element."},{"name":"countries","type":"readonly CountryChoice[]","required":true,"defaultValue":null,"description":"Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled selected identifier. Defaults to null."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Prevents opening and selection. An empty country list is also disabled. The trigger stays focusable with aria-disabled."},{"name":"noCountryLabel","type":"string","required":false,"defaultValue":"No country","description":"Text for the null selection and its option. Defaults to No country."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Reports the selected identifier or null with event, reason, trigger, cancel and isCanceled details. Call cancel() to preserve selection and keep the popup open."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled selected identifier. Null selects no country; undefined leaves selection uncontrolled."}]},{"name":"Trigger","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger button."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Optional visible label that names the trigger."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the trigger element. Custom components must forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"wrapperProps","type":"Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"children\">","required":false,"defaultValue":null,"description":"Native props and ref for the div around the trigger and its visible label. Children are owned by the picker."}]},{"name":"Options","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name for the selection listbox. Overrides its default name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"Accessible name references for the selection listbox. Defaults to the registered Dropdown title or trigger element."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the selection group div."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Closes the popup after a selection. Defaults to true. Cancelled selection keeps it open."},{"name":"noResultsLabel","type":"string","required":false,"defaultValue":null,"description":"Text displayed when no choice matches the search. Defaults to No results."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the selection group element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CountrySelectOptionsState>","required":false,"defaultValue":null,"description":"Replaces the selection group div. Functions receive supplied props and { value, multiple: false } state, with the public string or null selection. Custom components must forward the supplied props and ref."},{"name":"searchLabel","type":"string","required":false,"defaultValue":null,"description":"Search placeholder and accessible name. Defaults to Search."},{"name":"searchProps","type":"Omit<DropdownSearchProps, \"defaultValue\" | \"value\" | \"onValueChange\">","required":false,"defaultValue":null,"description":"Native search input props, ref, and render. Search value and change handling are owned by the picker."}]}]}},{"name":"CurrencyPicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: CurrencyPicker\ndescription: Choose a currency with a complete picker or compose its parts in a dropdown.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CurrencyPickerReference from '/snippets/ui/generated/components/input/currency-picker.mdx';\n\n## Overview\n\n`CurrencyPicker` combines a compact currency trigger, searchable options, and a [Dropdown](/ui/components/navigation/dropdown). Supply a currency catalogue and use one component for ordinary selection. Compose `Root`, `Trigger`, and `Options` with Dropdown when the popup needs other content or pages.\n\n<StoryEmbed\n storyId=\"ui-input-currencypicker--display\"\n title=\"Currency picker\"\n height={420}\n/>\n\n## Usage\n\nEach currency has a unique `code`, a `name`, and optional `symbol` and `disabled` properties. The code is the stable selection identifier. The picker does not ship a currency catalogue or choose an application default.\n\n```tsx\nimport { CurrencyPicker } from 'twenty-ui/components/input';\n\nconst CURRENCIES = [\n { code: 'EUR', name: 'Euro', symbol: '€' },\n { code: 'USD', name: 'US Dollar', symbol: '$' },\n];\n\nexport const InvoiceCurrency = () => (\n <CurrencyPicker\n currencies={CURRENCIES}\n defaultValue=\"USD\"\n aria-label=\"Invoice currency\"\n optionsProps={{\n searchLabel: 'Search currencies',\n emptyLabel: 'No currencies found',\n }}\n contentProps={{ width: 280 }}\n />\n);\n```\n\nUse `defaultValue` for uncontrolled selection. For controlled selection, pass `value` and update it from `onValueChange`. The callback receives the next code or `null` and Dropdown selection details containing `event`, `reason`, `trigger`, `cancel`, and `isCanceled`. Call `details.cancel()` to preserve the current selection and keep the popup open. Selecting the current code does not emit another change.\n\n`null` clears the selection. An empty string remains a valid code and does not clear it. An unknown value stays unchanged and appears as its raw code in the trigger; it does not add an option to the catalogue. A later controlled update or catalogue change updates the trigger and selected row.\n\n```tsx\nimport { useState } from 'react';\nimport { CurrencyPicker } from 'twenty-ui/components/input';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst CURRENCIES = [\n { code: 'EUR', name: 'Euro' },\n { code: 'USD', name: 'US Dollar' },\n];\n\nexport const ClearableCurrency = () => {\n const [value, setValue] = useState<string | null>('USD');\n\n return (\n <>\n <CurrencyPicker\n currencies={CURRENCIES}\n value={value}\n onValueChange={setValue}\n aria-label=\"Invoice currency\"\n triggerProps={{ placeholder: 'Choose a currency' }}\n />\n <Button onClick={() => setValue(null)}>Clear currency</Button>\n </>\n );\n};\n```\n\n## Advanced composition\n\n`CurrencyPicker.Root` prepares the catalogue and owns selection for both parts. It adds no DOM element and must be inside `Dropdown.Root`. Keep `Trigger` and `Options` under the same picker root, including when the options live in another dropdown page. The root's render-function children expose `value`, `selectedCurrency`, and `disabled` for caller-owned labels and supporting content.\n\n```tsx\nimport { CurrencyPicker } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\nconst CURRENCIES = [\n { code: 'EUR', name: 'Euro' },\n { code: 'USD', name: 'US Dollar' },\n];\n\nexport const ComposedCurrency = () => (\n <Dropdown.Root type=\"picker\">\n <CurrencyPicker.Root\n currencies={CURRENCIES}\n defaultValue=\"USD\"\n closeOnSelect={false}\n >\n {({ value }) => (\n <>\n <CurrencyPicker.Trigger\n aria-label={`Invoice currency: ${value ?? 'none'}`}\n placeholder=\"Choose a currency\"\n />\n <Dropdown.Content aria-label=\"Invoice currency\" width={280}>\n <Dropdown.Title>Invoice currency</Dropdown.Title>\n <CurrencyPicker.Options\n searchLabel=\"Search currencies\"\n emptyLabel=\"No currencies found\"\n />\n </Dropdown.Content>\n </>\n )}\n </CurrencyPicker.Root>\n </Dropdown.Root>\n);\n```\n\nDropdown owns opening, popup placement, pages, search navigation, and focus. The picker uses a Dropdown selection group for persistent selected values and the close policy. `Root.closeOnSelect` defaults to `true`; use `false` to keep the popup open after choosing a currency. Arrow keys, Home, and End move focus without changing the value. Enter, Space, or pointer activation selects an enabled option. Disabled currencies stay visible and cannot be selected.\n\n## Search and ordering\n\nOptions are searchable by default. Search ignores surrounding whitespace and matches codes, names, symbols, and the default `Name (CODE)` label without case sensitivity, using the same rules in every browser locale. `getSearchText` on the root replaces the searchable text for each currency. Display customization and search text are independent.\n\nResults retain catalogue order. Set `selectedFirst` on the shorthand or root to move the selected currency before the other matches. A query that excludes it also removes its row. An unknown value does not create a selected result. Empty results show `emptyLabel` in a status region.\n\nSet `Options.searchable={false}` to omit the search field. `Options.searchProps` targets the native search input, including its `ref`, `render`, accessible attributes, and controlled `value` or uncontrolled `defaultValue`. `searchProps.onValueChange` receives the query. In shorthand use, pass these options through `optionsProps`.\n\nThe search field receives focus when a searchable picker opens. Enter with a nonempty query activates the first enabled result. With an empty query, move focus to an option before selecting it. Search activation during IME composition and fresh search on reopen remain subject to the shared Dropdown search and page-session contracts.\n\n## Presentation and native targets\n\nThe trigger shows the selected code by default. `renderValue` receives `{ value, selectedCurrency, disabled }` to customize that display without looking up the currency again. `Trigger.children` overrides the value display, and `Trigger.placeholder` supplies the empty display. `getOptionLabel` customizes each option's content, with the default `Name (CODE)` label. Currency names, symbols, labels, and option content belong to the caller.\n\nThe shorthand's native button attributes, event handlers, `className`, `style`, `ref`, and `render` target its trigger. `triggerProps` customizes that same button. Use `optionsProps` for the options wrapper div and its nested `searchProps` for the input. `contentProps` customizes Dropdown's popup. `open`, `defaultOpen`, and `onOpenChange` coordinate the shorthand's open state.\n\nIn compound use, native attributes, `ref`, and `render` on `Trigger` target its button, while those on `Options` target its wrapper div. `Options.listLabel` names only the inner selection listbox. Forward the supplied props and ref from a custom `render` component. Wrapper styling does not change the input's native target.\n\nSet `disabled` on the shorthand or root to disable opening, search, and selection. A part's `disabled` prop can additionally disable that part. Selection is a picker value; native form submission, reset, required validation, and Field integration remain outside this API.\n\n## Labels and application integration\n\n`searchLabel` defaults to `Search` and supplies the search placeholder and accessible name. `emptyLabel` defaults to `No results` and accepts content. Supply localized source labels, an accessible trigger name, and any placeholder from your application. Dropdown content takes the trigger name unless a `Dropdown.Title` or explicit content label names it. The selection listbox takes the registered Dropdown title or trigger name by default. Set `Options.listLabel` to give only that listbox its own accessible name, or pass `optionsProps.listLabel` in shorthand use. Native `aria-label` and `aria-labelledby` on `Options` label only its wrapper. The trigger keeps its own accessible name.\n\nThe application owns amount editing, currency storage, formatting, catalogue loading, and its initial value. An adapter should map stored currency codes and clearing behavior to `value` and `onValueChange`, preserving the application's formatting and fallback rules. Keep translated currency names and labels in the application.\n\n## Front-component renderer\n\nThe React and Preact sandbox fixtures cover shorthand and compound search and selection, disabled controls and options, trigger refs, null clearing, external controlled updates, reopening, and Escape focus restoration. They also verify that clearing an earlier query and typing `$` preserves the symbol query.\n\nPopup visibility, geometry, scrolling, and dismissal depend on the shared renderer's Dropdown and portal support. The picker uses that shared implementation.\n\n## Props\n\n<CurrencyPickerReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"CurrencyPicker","entryPoint":"twenty-ui/components/input","slug":"components/input/currency-picker","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned trigger content that overrides the selected value display."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger button."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Whether committing an enabled option closes the dropdown. Defaults to true. A canceled selection never closes automatically."},{"name":"contentProps","type":"Omit<DropdownContentProps, \"children\">","required":false,"defaultValue":null,"description":"Dropdown popup props, including placement, width, and accessible attributes."},{"name":"currencies","type":"readonly CurrencyPickerOption[]","required":true,"defaultValue":null,"description":"Available currencies in display order. Each code is a unique stable identifier; name and optional symbol are caller-owned data. A currency can be disabled."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is initially open when uncontrolled."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled currency code, or null for an empty selection. Defaults to null."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables opening, search, and every currency option."},{"name":"getOptionLabel","type":"((currency: CurrencyPickerOption) => ReactNode)","required":false,"defaultValue":"Name (CODE)","description":"Returns caller-owned content for a currency option. Defaults to Name (CODE). Display content does not change the search text."},{"name":"getSearchText","type":"((currency: CurrencyPickerOption) => string)","required":false,"defaultValue":"Name (CODE) and symbol","description":"Returns searchable text for a currency. Defaults to Name (CODE) and its optional symbol. Search trims the query and matches without case sensitivity."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID forwarded to the trigger button."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"onEscapeKeyDown","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before Escape closes the popup. Call event.preventDefault() to keep it open."},{"name":"onInteractOutside","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called before an outside press or Tab out closes the popup. Call event.preventDefault() to keep it open."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Called with the next open state when the popup opens or closes."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next code or null and cancellable Dropdown selection details: event, reason, trigger, cancel and isCanceled. Calling cancel() preserves selection and prevents automatic close. Repeated single selection does not emit a change."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is open. Use with onOpenChange to control it."},{"name":"optionsProps","type":"CurrencyPickerOptionsProps","required":false,"defaultValue":null,"description":"Props for the options wrapper div, listLabel, and search behavior. Native input customization belongs in optionsProps.searchProps."},{"name":"placeholder","type":"ReactNode","required":false,"defaultValue":null,"description":"Trigger content displayed when the selected value is null."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the native trigger button. Forward the supplied props and ref when rendering a custom component."},{"name":"renderValue","type":"((state: CurrencyPickerState) => ReactNode)","required":false,"defaultValue":null,"description":"Returns selected trigger content from { value, selectedCurrency, disabled }. The default display is the raw code, or the trigger placeholder when null. Trigger children override it."},{"name":"selectedFirst","type":"boolean","required":false,"defaultValue":"false","description":"Moves the matching selected currency before other results. Defaults to false, preserving catalogue order."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the trigger button."},{"name":"triggerProps","type":"CurrencyPickerTriggerProps","required":false,"defaultValue":null,"description":"Props for the trigger button, including native attributes, ref, render, placeholder, and caller-owned children. These override shorthand trigger props."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled currency code or null for an empty selection. Undefined leaves selection uncontrolled. Empty and unknown strings remain identifiers."}],"parts":[{"name":"Root","props":[{"name":"children","type":"ReactNode | ((state: CurrencyPickerState) => ReactNode)","required":true,"defaultValue":null,"description":"Picker parts and supporting content, or a render function receiving { value, selectedCurrency, disabled }. Root owns selection and prepared data without adding a DOM element."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Whether committing an enabled option closes the dropdown. Defaults to true. A canceled selection never closes automatically."},{"name":"currencies","type":"readonly CurrencyPickerOption[]","required":true,"defaultValue":null,"description":"Available currencies in display order. Each code is a unique stable identifier; name and optional symbol are caller-owned data. A currency can be disabled."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled currency code, or null for an empty selection. Defaults to null."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the trigger, search input, and every currency option."},{"name":"getOptionLabel","type":"((currency: CurrencyPickerOption) => ReactNode)","required":false,"defaultValue":"Name (CODE)","description":"Returns caller-owned content for a currency option. Defaults to Name (CODE). Display content does not change the search text."},{"name":"getSearchText","type":"((currency: CurrencyPickerOption) => string)","required":false,"defaultValue":"Name (CODE) and symbol","description":"Returns searchable text for a currency. Defaults to Name (CODE) and its optional symbol. Search trims the query and matches without case sensitivity."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next code or null and cancellable Dropdown selection details: event, reason, trigger, cancel and isCanceled. Calling cancel() preserves selection and prevents automatic close. Repeated single selection does not emit a change."},{"name":"renderValue","type":"((state: CurrencyPickerState) => ReactNode)","required":false,"defaultValue":null,"description":"Returns selected trigger content from { value, selectedCurrency, disabled }. The default display is the raw code, or the trigger placeholder when null. Trigger children override it."},{"name":"selectedFirst","type":"boolean","required":false,"defaultValue":"false","description":"Moves the matching selected currency before other results. Defaults to false, preserving catalogue order."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled currency code or null for an empty selection. Undefined leaves selection uncontrolled. Empty and unknown strings remain identifiers."}]},{"name":"Trigger","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned trigger content that overrides the selected value display."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the trigger button."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Additionally disables the native trigger button. Root disabled state always takes precedence."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID forwarded to the trigger button."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"placeholder","type":"ReactNode","required":false,"defaultValue":null,"description":"Trigger content displayed when the selected value is null."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Replaces the native trigger button. Forward the supplied props and ref when rendering a custom component."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the trigger button."}]},{"name":"Options","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the options wrapper div."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Additionally disables search and every currency option. Root disabled state always takes precedence."},{"name":"emptyLabel","type":"ReactNode","required":false,"defaultValue":"No results","description":"Content announced when no currencies match. Defaults to No results."},{"name":"listLabel","type":"string","required":false,"defaultValue":null,"description":"Accessible name for the selection listbox. Defaults to the registered Dropdown title or trigger name. Native accessible attributes on Options target only its wrapper."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the options wrapper div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the non-interactive wrapper div. Forward the supplied props and ref when rendering a custom component. Use searchProps.render to customize the input."},{"name":"searchable","type":"boolean","required":false,"defaultValue":"true","description":"Renders a search input above the options. Defaults to true."},{"name":"searchLabel","type":"string","required":false,"defaultValue":"Search","description":"Search placeholder and accessible name. Defaults to Search."},{"name":"searchProps","type":"DropdownSearchProps","required":false,"defaultValue":null,"description":"Native input attributes, ref, render, and controlled or uncontrolled query props forwarded to Dropdown.Search. Use value with onValueChange or defaultValue."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the options wrapper div."}]}]}},{"name":"ProgressRing","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: ProgressRing\ndescription: Show measured or indeterminate progress in a compact circular indicator.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ProgressRingReference from '/snippets/ui/generated/feedback/progress-ring.mdx';\n\n## Overview\n\n`ProgressRing` supplies a circular appearance for [Progress](/ui/primitives/feedback/progress). It shares the root's custom range, null, formatting, labeling, native prop, ref, and render contract. Optional children display a preformatted value beside the ring.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressring-progressring--display\"\n title=\"Progress ring example\"\n height={90}\n/>\n\n## Usage\n\nSupply the raw controlled value and an accessible name. Use `aria-valuetext` when a formatted value explains progress more clearly than a percentage.\n\n```tsx\nimport { ProgressRing } from 'twenty-ui/primitives/feedback';\n\nexport const ImportProgress = () => (\n <ProgressRing\n value={600}\n max={1000}\n aria-label=\"Importing records\"\n aria-valuetext=\"600 of 1,000 records\"\n >\n 600 / 1,000\n </ProgressRing>\n);\n```\n\nUse `aria-labelledby` to associate the ring with an existing visible label, or compose `Progress.Label` as a child. Preformatted children do not automatically provide the ring's accessible name.\n\n## Controlled progress and ranges\n\nThe application calculates `value` and formats display content. The ring does not fetch data, advance progress, or calculate quotas. `min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for semantic values and arc geometry. The arc fills by the normalized percentage, including when the minimum is nonzero.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressring-progressring--custom-range\"\n title=\"Circular progress in a custom range\"\n height={90}\n/>\n\nPass `value={null}` for indeterminate progress. The ring omits `aria-valuenow` and displays an indeterminate arc. Non-finite values also remain indeterminate; they do not become zero or completion. Display content stays controlled by the application.\n\nUse `locale`, `format`, and `getAriaValueText` as described in [Progress](/ui/primitives/feedback/progress). Compose `Progress.Value` to display the root's formatted value.\n\nUse [ProgressBar](/ui/primitives/feedback/progress-bar) for horizontal progress or [MetricRow](/ui/components/data-display/metric-row) for a label and aligned value.\n\n## Appearance and composition\n\n`size=\"md\"` renders a 16px ring; `size=\"sm\"` renders a 14px ring. Both use a 2px stroke and fill clockwise from the top. `barColor` accepts CSS colors, including theme variables. The SVG is decorative and hidden from accessibility APIs.\n\nValue changes animate for 300ms. Reduced-motion preferences disable the transition and indeterminate rotation. Native attributes, `className`, `style`, and `ref` target the outer progress element. `className` and `style` can receive the progress state. `render` can replace the root while retaining its semantics.\n\n## Props\n\n<ProgressRingReference />\n\n<PageBanner illustration=\"card-page-usage-limits\" />\n","api":{"name":"ProgressRing","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/progress-ring","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name identifying the measured operation."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the visible label that names the operation."},{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"Human-readable progress value overriding the default formatted value."},{"name":"barColor","type":"string","required":false,"defaultValue":null,"description":"CSS color of the filled arc. Defaults to the blue theme color."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional preformatted value or Progress parts displayed before the ring."},{"name":"className","type":"string | ((state: ProgressRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the progress root, or a callback receiving its status."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number | null) => string)","required":false,"defaultValue":null,"description":"Receives the formatted value and raw value, including null, and returns an accessible value description."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format the value. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"Inclusive maximum. Defaults to 100."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"Inclusive minimum. Defaults to 0."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>","required":false,"defaultValue":null,"description":"Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Ring diameter: sm (14px) or md (16px). Defaults to md."},{"name":"style","type":"CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the progress root, or a callback receiving its status."},{"name":"value","type":"number | null","required":true,"defaultValue":null,"description":"Controlled value in the min/max range. Use null for indeterminate progress."}]}},{"name":"DetailsRow","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: DetailsRow\ndescription: Align detail labels with wrapping values and optional actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DetailsRowReference from '/snippets/ui/generated/components/data-display/details-row.mdx';\n\n## Overview\n\n`DetailsRow` pairs a label with a value in a description list. Add a decorative icon, multiple value items, or an action supplied by your application.\n\n<StoryEmbed\n storyId=\"ui-data-display-detailsrow--display\"\n title=\"Details row example\"\n height={220}\n/>\n\n## Usage\n\n```tsx\nimport { DetailsRow } from 'twenty-ui/components/data-display';\nimport { IconNotes, IconTag, IconUser } from 'twenty-ui/icon';\nimport { Chip, Tag } from 'twenty-ui/primitives/data-display';\nimport { Card } from 'twenty-ui/primitives/surfaces';\n\nexport const CollectionDetails = () => (\n <Card.Root>\n <Card.Content>\n <dl style={{ display: 'grid', gap: 8, margin: 0 }}>\n <DetailsRow label=\"Owner\" startIcon={<IconUser size={16} />}>\n <Chip>Jordan Lee</Chip>\n </DetailsRow>\n <DetailsRow label=\"Categories\" startIcon={<IconTag size={16} />}>\n <Tag color=\"blue\">Research</Tag>\n <Tag color=\"purple\">Design</Tag>\n </DetailsRow>\n <DetailsRow label=\"Description\" startIcon={<IconNotes size={16} />}>\n A shared collection of customer research and design decisions.\n </DetailsRow>\n </dl>\n </Card.Content>\n </Card.Root>\n);\n```\n\nPlace each row directly inside a `dl`. Pass the label through `label` and its value through `children`. The application owns labels, localization, formatted values, and placeholders for missing values.\n\n## Alignment and wrapping\n\nLabels and values wrap rather than truncate. Multiple value items, such as chips or tags, wrap onto additional lines. Rows align their content at the top as that content grows.\n\nThe label column defaults to `7rem` and is capped at 40% of the row's width to leave space for the value in narrow containers. Set the same `labelWidth` on sibling rows to adjust their alignment. Numbers use pixels; CSS lengths such as `'8rem'` are also supported.\n\n```tsx\nimport { DetailsRow } from 'twenty-ui/components/data-display';\n\nexport const PublicationDetails = () => (\n <dl style={{ display: 'grid', gap: 8, margin: 0, maxWidth: 360 }}>\n <DetailsRow label=\"Primary contributor\" labelWidth={128}>\n Jordan Lee\n </DetailsRow>\n <DetailsRow label=\"Review notes\" labelWidth={128}>\n Include findings from the customer interviews before publication.\n </DetailsRow>\n </dl>\n);\n```\n\n## Actions\n\nUse `action` for a control beside the value. The row does not add editing, click, or keyboard behavior. Supply a control with an accessible name and connect its handler to the application behavior.\n\n```tsx\nimport { DetailsRow } from 'twenty-ui/components/data-display';\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { IconCopy } from 'twenty-ui/icon';\n\nexport const ContactDetails = ({ onCopy }: { onCopy: () => void }) => (\n <dl style={{ margin: 0 }}>\n <DetailsRow\n label=\"Email\"\n action={\n <LightIconButton aria-label=\"Copy email address\" onClick={onCopy}>\n <IconCopy size={16} />\n </LightIconButton>\n }\n >\n [email protected]\n </DetailsRow>\n </dl>\n);\n```\n\n## Composition and accessibility\n\nEach row renders a `div` grouping with a `dt` label and a `dd` containing the value and optional action. The caller supplies the enclosing `dl`. Provide meaningful text in the label. The optional `startIcon` is hidden from assistive technology, and the caller controls its dimensions.\n\nNative attributes, `className`, `style`, and `ref` target the outer `div`. When using `render` with a custom wrapper, preserve that `div` directly inside the `dl` and forward all supplied props and the ref. Keep actions inside their slot so the term and definition remain the row's direct children.\n\nUse [MetricRow](/ui/components/data-display/metric-row) for a metric with optional progress. `DetailsRow` provides only the label, value, and action layout.\n\n## Props\n\n<DetailsRowReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"DetailsRow","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/details-row","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional action content beside the value. The caller supplies controls, accessible names, and handlers."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Value content rendered in the description definition. Text and multiple items wrap within the available space."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row root."},{"name":"label","type":"ReactNode","required":true,"defaultValue":null,"description":"Visible label rendered as the description term."},{"name":"labelWidth","type":"Width<string | number>","required":false,"defaultValue":"7rem","description":"Preferred label column width. Numbers use pixels. The column is capped at 40% of the row width; use the same width for aligned sibling rows."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the row root div."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the row root. Preserve a div directly inside a dl and forward its props and ref to retain valid description-list grouping."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative node before the label. The caller controls icon dimensions."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row root."}]}},{"name":"MetricRow","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: MetricRow\ndescription: Align a metric label and formatted value with optional progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport MetricRowReference from '/snippets/ui/generated/components/data-display/metric-row.mdx';\n\n## Overview\n\n`MetricRow` aligns a label, optional icon, and preformatted value. An optional [ProgressRing](/ui/primitives/feedback/progress-ring) uses the visible label as its accessible name.\n\n<StoryEmbed\n storyId=\"ui-data-display-metricrow--display\"\n title=\"Metric row example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { MetricRow } from 'twenty-ui/components/data-display';\nimport { IconFiles } from 'twenty-ui/icon';\n\nexport const ImportMetric = () => (\n <MetricRow\n startIcon={<IconFiles size={14} />}\n value=\"75 of 100\"\n progress={75}\n >\n Imported files\n </MetricRow>\n);\n```\n\nPass a nonempty text label as required children and the formatted value through `value`. Add `progress` when the metric has a known percentage.\n\nThe application owns calculations, units, number formatting, and the meaning of the metric. `progressColor` accepts a CSS color for the filled arc.\n\n## Values without progress\n\nOmit `progress` to show a plain value. Numeric zero displays as `0`; content is never replaced with a placeholder. Supply your own placeholder when data is unavailable.\n\n```tsx\nimport { MetricRow } from 'twenty-ui/components/data-display';\n\nexport const CompletedMetric = () => (\n <MetricRow value={0}>Completed imports</MetricRow>\n);\n```\n\n## Composition and accessibility\n\nLabel content accepts nodes. Its accessible text names the progress ring through `aria-labelledby`, including nested text. Provide a meaningful visible label. A nonempty string value is also exposed as its accessible value text. For formatted value content, supply `progressValueText` when a percentage does not describe the metric fully. This text overrides the string value fallback. Without it, other content keeps the ring's percentage value text. An empty `progressValueText` also uses the percentage, including when `value` is a string. The optional `startIcon` node is decorative. The caller controls its dimensions and stroke.\n\n```tsx\nimport { MetricRow } from 'twenty-ui/components/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const FormattedStorageMetric = () => (\n <MetricRow\n value={<Text render={<bdi />}>12 / 20 GB</Text>}\n progress={60}\n progressValueText=\"12 of 20 gigabytes used\"\n >\n <Text render={<strong />}>Storage</Text>\n </MetricRow>\n);\n```\n\nReplace `startIcon={IconDatabase}` with `startIcon={<IconDatabase size={14} />}`. Values stay preformatted by the application.\n\nNative attributes, `className`, `style`, and `ref` target the outer row. `render` can replace that element. Progress stays controlled and bounded to 0 to 100, with the same reduced-motion behavior as `ProgressRing`.\n\n## Props\n\n<MetricRowReference />\n\n<PageBanner illustration=\"dashboards\" />\n","api":{"name":"MetricRow","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/metric-row","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Label content whose accessible text also names the optional progress ring."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row root."},{"name":"progress","type":"number","required":false,"defaultValue":null,"description":"Optional controlled progress from 0 to 100. Omitting it displays the value without a ring."},{"name":"progressColor","type":"string","required":false,"defaultValue":null,"description":"CSS color of the filled arc when progress is provided."},{"name":"progressValueText","type":"string","required":false,"defaultValue":null,"description":"Accessible value text for the progress ring. Nonempty text overrides the string value fallback; an empty string uses the ring percentage. Supply it when formatted content needs more context than a percentage."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the row root element while preserving its contents."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative node content before the label. The caller controls icon geometry."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row root."},{"name":"value","type":"ReactNode","required":true,"defaultValue":null,"description":"Preformatted value displayed at the end of the row. Nonempty string values also supply the progress ring accessible value text."}]}},{"name":"Shortcut","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: Shortcut\ndescription: Display simultaneous key combinations and sequential shortcuts.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ShortcutReference from '/snippets/ui/generated/typography/shortcut.mdx';\n\n## Overview\n\nImport `Shortcut` and `formatShortcut` from `twenty-ui/primitives/typography`. Both share the same model, symbols, and separators. Register shortcuts in your application. `Shortcut` only formats the hint; it does not register keyboard actions. Native attributes, event handlers, styles, class names, and refs target its outer span. `ShortcutProps` and `ShortcutFormatOptions` are public types.\n\n<StoryEmbed\n storyId=\"ui-typography-shortcut--display\"\n title=\"Shortcut presentations\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Shortcut } from 'twenty-ui/primitives/typography';\n\nexport const SearchShortcut = () => <Shortcut shortcut={['Mod', 'K']} />;\n```\n\n## Combinations and sequences\n\n```tsx\nimport { Shortcut, formatShortcut } from 'twenty-ui/primitives/typography';\n\nexport const ShortcutExamples = () => (\n <>\n <Shortcut shortcut={['Enter']} />\n <Shortcut shortcut={['Mod', 'K']} />\n <Shortcut shortcut={[['G'], ['P']]} sequenceJoinLabel=\"then\" />\n <Shortcut\n shortcut={[\n ['Mod', 'K'],\n ['Mod', 'C'],\n ]}\n sequenceJoinLabel=\"then\"\n />\n </>\n);\n\nconst hint = formatShortcut({\n shortcut: ['Mod', 'Enter'],\n});\n```\n\nA flat array is a simultaneous combination: `['Mod', 'K']` means press Mod and K together. A nested array is an ordered sequence: `[['G'], ['P']]` means press G, then P. Each nested array is one combination, so `[['Mod', 'K'], ['Mod', 'C']]` means press Mod and K, then Mod and C. Use a one-element array for a single key. Both array forms can be readonly.\n\n`Mod` and `CommandOrControl` display Command on macOS and iOS, and Control elsewhere. Explicit `Command`, `Control`, `Alt`, and `Enter` keys also have display labels. Other strings are displayed as supplied. Device detection is safe without browser globals; `platform` optionally overrides it with `mac` or `other`.\n\nUse `sequenceJoinLabel` for localized join text. `combinationSeparator` can preserve a host convention such as `+`. The default text separator is empty on Apple devices and a space elsewhere. `variant` selects `keys`, `text`, or `button`. `visibility=\"desktop\"` hides the hint at mobile viewport widths while `always` remains visible.\n\nKey symbols have readable accessible names. Use `accessibleKeyLabels` to localize individual key names in screen reader output. Supply `aria-label` or `aria-labelledby` for a localized name for the whole shortcut, or `aria-hidden` for a decorative hint. Buttons keep their action names and hide their decorative hints on mobile. Menu and list rows keep their hints visible.\n\n## Appearance\n\nUse `keys` for individual keycaps, `text` for an inline hint, or `button` for the compact hint inside an action. These variants only change the presentation.\n\n<StoryEmbed\n storyId=\"ui-typography-shortcut--catalog\"\n title=\"Shortcut appearance variants\"\n height={160}\n/>\n\n## Migration\n\n| Previous prop | Replacement |\n| ----------------------------------------- | ---------------------------------------------------------- |\n| Button `hotkeys={['⌘', 'K']}` | `shortcut={['Mod', 'K']}` |\n| ListItem sequential `hotkeys` / `hotKeys` | `shortcut={[['G'], ['P']]}` |\n| `hotkeysJoinLabel` / `hotKeysJoinLabel` | `shortcutJoinLabel` on Button, ListItem and Dropdown parts |\n| Manual tooltip key concatenation | `formatShortcut({ shortcut: ['Mod', 'Enter'] })` |\n\nFlat stored arrays that represent successive key presses need nesting before being passed to `shortcut`: `hotKeys.map((key) => [key])`. Arrays that represent simultaneous keys can be passed directly. Key strings remain literal tokens, so `['Mod', '+']` contains a plus key and `['Space']` contains the Space key; no shortcut-string parsing is required.\n\n## Props\n\n<ShortcutReference />\n\n<PageBanner illustration=\"card-page-command-menu\" />\n","api":{"name":"Shortcut","entryPoint":"twenty-ui/primitives/typography","slug":"typography/shortcut","props":[{"name":"accessibleKeyLabels","type":"Readonly<Record<string, string>>","required":false,"defaultValue":null,"description":"Optional localized names for individual keys in screen reader output."},{"name":"combinationSeparator","type":"string","required":false,"defaultValue":null,"description":"Optional separator between simultaneous keys. Defaults to no separator on Apple devices and a space elsewhere."},{"name":"platform","type":"\"mac\" | \"other\"","required":false,"defaultValue":null,"description":"Optional mac or other platform override. Defaults to server-safe device detection."},{"name":"sequenceJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequence steps. Defaults to then."},{"name":"shortcut","type":"ShortcutDefinition","required":true,"defaultValue":null,"description":"Flat key array for a simultaneous combination, or nested key arrays for an ordered sequence of combinations."},{"name":"variant","type":"\"button\" | \"keys\" | \"text\"","required":false,"defaultValue":"keys","description":"Keycaps, inline text, or a separated button hint."},{"name":"visibility","type":"\"always\" | \"desktop\"","required":false,"defaultValue":"always","description":"Always visible by default. Desktop hints hide on mobile viewports."}]}},{"name":"VisuallyHidden","entryPoint":"twenty-ui/primitives/accessibility","content":"---\ntitle: VisuallyHidden\ndescription: Keep supporting text available to assistive technology without displaying it visually.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport VisuallyHiddenReference from '/snippets/ui/generated/accessibility/visually-hidden.mdx';\n\n## Overview\n\n`VisuallyHidden` renders a visually hidden `span`. Its content stays in the accessibility tree and can supply an accessible name. It accepts native span props, a span ref, and Base UI `render` composition. Import `VisuallyHiddenProps` from the same entry point.\n\n<StoryEmbed\n storyId=\"ui-accessibility-visuallyhidden--display\"\n title=\"Visually hidden example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { VisuallyHidden } from 'twenty-ui/primitives/accessibility';\nimport { IconPlus } from 'twenty-ui/icon';\n\ntype AddRecordActionProps = { onAdd: () => void };\n\nexport const AddRecordAction = ({ onAdd }: AddRecordActionProps) => (\n <Button onClick={onAdd}>\n <IconPlus aria-hidden />\n <VisuallyHidden>Add record</VisuallyHidden>\n </Button>\n);\n```\n\nUse a visible label when space permits. For controls that already accept `aria-label`, that attribute is another way to supply an accessible name.\n\n## Hidden content\n\nPlace supporting text inside the wrapper. Avoid placing focusable controls inside it: the wrapper stays visually hidden when its children receive focus. It does not add a live region, remove content from assistive technology, or hide confidential data.\n\nUse `id` to associate hidden descriptions with `aria-describedby`. Native attributes, `className`, `style`, and `ref` target the hidden span or the element supplied through `render`. See [accessibility](/ui/accessibility) for labeling and announcement patterns.\n\n## Props\n\n<VisuallyHiddenReference />\n\n<PageBanner illustration=\"page-cover-accessibility\" />\n","api":{"name":"VisuallyHidden","entryPoint":"twenty-ui/primitives/accessibility","slug":"accessibility/visually-hidden","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content hidden visually while remaining available to assistive technology."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render function composed with the hidden span props and ref."}]}},{"name":"ColorSample","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: ColorSample\ndescription: Display a theme color or a custom color alongside a text label.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ColorSampleReference from '/snippets/ui/generated/data-display/color-sample.mdx';\n\n## Overview\n\n`ColorSample` is a non-interactive color swatch. Use it next to a label so the meaning does not depend on color alone. Selection belongs to the surrounding control.\n\n<StoryEmbed\n storyId=\"ui-data-display-colorsample--display\"\n title=\"ColorSample example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { ColorSample } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const PriorityColor = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <ColorSample colorName=\"red\" render={<span />} aria-hidden=\"true\" />\n High priority\n </Text>\n);\n```\n\n`colorName` selects a theme palette entry for the fill and border. `variant` accepts `default` or `circle`. Omitting it uses the default shape.\n\n## Custom colors\n\n```tsx\nimport { ColorSample } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const BrandColor = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <ColorSample\n colorName=\"blue\"\n color=\"#2563eb\"\n render={<span />}\n aria-hidden=\"true\"\n />\n Brand blue\n </Text>\n);\n```\n\nA custom `color` overrides the fill; `colorName` remains required and still determines the border color. Native props, `className`, `style`, and `ref` target the swatch div. `render` accepts an element or callback through Base UI composition, for example a span inside text. Consumer styles override the default fill, border, or geometry. Decorative swatches use `aria-hidden=\"true\"`; a standalone meaningful swatch uses `role=\"img\"` with `aria-label` or `aria-labelledby`. To offer selectable colors, compose the swatch inside a labeled [ListItem](/ui/primitives/navigation/list-item).\n\n## Migration\n\n`ColorSampleProps` and `ColorSampleVariant` remain available from the data-display family. The unused `pipeline` variant is removed. Product-specific indicators belong in the application, using native styles or composition. Default and circle swatches keep their existing appearance.\n\n## Props\n\n<ColorSampleReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n","api":{"name":"ColorSample","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/color-sample","props":[{"name":"aria-hidden","type":"Booleanish","required":false,"defaultValue":null,"description":"Mark decorative swatches as hidden from assistive technology."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name when the caller supplies role=\"img\"."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the swatch class."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"CSS color that overrides the background; the border still uses `colorName`."},{"name":"colorName","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"turquoise\" | \"violet\" | \"yellow\"","required":true,"defaultValue":null,"description":"Theme color used for the background and border. Required even when `color` overrides the background."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the swatch div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles merged with the swatch color defaults. Explicit styles win."},{"name":"variant","type":"\"circle\" | \"default\"","required":false,"defaultValue":null,"description":"Generic swatch shape: `default` or `circle`. Omitting it uses the default shape."}]}},{"name":"Badge","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Badge\ndescription: Display compact inline information with caller-provided content.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport BadgeReference from '/snippets/ui/generated/data-display/badge.mdx';\n\n## Overview\n\n`Badge` displays compact inline information, including short labels and counts. Use [Tag](/ui/primitives/data-display/tag) for categories, [Chip](/ui/primitives/data-display/chip) for compact controls, or [Status](/ui/primitives/data-display/status) for a named state with an indicator.\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--display\"\n title=\"Badge example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\n\nexport const PreviewLabel = () => <Badge>Preview</Badge>;\n```\n\nPass text, numbers, or nodes as children. Badge displays the content you supply and adds no count formatting or visibility rules. The default element is a non-interactive `span`.\n\n## With an icon\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { IconPaperclip } from 'twenty-ui/icon';\n\nexport const AttachmentLabel = () => (\n <Badge>\n <IconPaperclip size={12} aria-hidden />\n Attachment\n </Badge>\n);\n```\n\nIcons are ordinary child nodes. Give decorative icons `aria-hidden` and keep a visible label to explain the content.\n\n## Appearance\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--catalog\"\n title=\"Badge sizes and shapes\"\n height={200}\n/>\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const BadgeAppearances = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <Badge size=\"sm\" color=\"tertiary\" shape=\"pill\">\n Preview\n </Badge>\n <Badge size=\"md\" color=\"inherit\">\n In review\n </Badge>\n <Badge size=\"xs\" color=\"primary\" shape=\"circle\">\n 3\n </Badge>\n <Badge size=\"xs\" color=\"secondary\" shape=\"circle\">\n 12\n </Badge>\n <Badge color=\"accent\">Last used</Badge>\n </Text>\n);\n```\n\n`size` accepts `xs`, `sm`, or `md`. `color` accepts `tertiary`, `inherit`, `primary`, `secondary`, or `accent`. The `accent` treatment pairs an accent-tertiary fill with accent11 text in both themes. The solid `primary` treatment keeps its blue fill and on-accent text. `shape` accepts `pill` or `circle`. The defaults are `sm`, `tertiary`, and `pill`. The circular treatment has a fixed width equal to its height. Use `pill` for longer content, including abbreviated counts.\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--colors\"\n title=\"Badge text colors\"\n height={140}\n/>\n\n<StoryEmbed\n storyId=\"ui-data-display-badge--accent\"\n title=\"Soft accent badges in light and dark themes\"\n height={140}\n/>\n\n## Counts and visibility\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype InboxButtonProps = {\n count: number;\n};\n\nexport const InboxButton = ({ count }: InboxButtonProps) => (\n <Button aria-label={`Inbox, ${count} unread messages`}>\n Inbox\n {count > 0 && (\n <Badge size=\"xs\" color=\"primary\" shape=\"pill\" aria-hidden>\n {count > 99 ? '99+' : count}\n </Badge>\n )}\n </Button>\n);\n```\n\nYour application owns number formatting, abbreviations, clamping, zero visibility, and translated labels. Include the full meaning in the surrounding control's accessible name when its compact count is decorative. A standalone badge can use native accessible attributes, including `aria-label` or `aria-labelledby`.\n\n## Native composition\n\n```tsx\nimport { useRef } from 'react';\nimport { Badge } from 'twenty-ui/primitives/data-display';\n\nexport const BuildStatus = () => {\n const badgeRef = useRef<HTMLSpanElement>(null);\n\n return (\n <Badge ref={badgeRef} title=\"Current build status\" data-build=\"preview\">\n Preview\n </Badge>\n );\n};\n```\n\nNative attributes, event handlers, `className`, `style`, and `ref` target the actual root element. `render` accepts an element or callback through Base UI composition. Choose an appropriate native owner for interactive content:\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const ReleaseLink = () => (\n <Badge render={<Button href=\"#release-notes\" size=\"sm\" />}>\n Release notes\n </Badge>\n);\n```\n\nThe rendered Button owns navigation behavior and link semantics. Badge keeps its presentational default and does not infer interaction from its content.\n\n## Props\n\nTypes and defaults are generated from the public `BadgeProps` type. Native attributes and event handlers are also accepted.\n\n<BadgeReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Badge","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/badge","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-provided text, numbers, icons, or other inline content."},{"name":"color","type":"\"accent\" | \"inherit\" | \"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"tertiary","description":"Neutral tertiary, inherited text, solid primary accent, soft accent tint, or secondary treatment."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default span. Native props, handlers, and the ref target the rendered element."},{"name":"shape","type":"\"circle\" | \"pill\"","required":false,"defaultValue":"pill","description":"Rounded pill label or fixed circle with width equal to its height. Use pill for longer content."},{"name":"size","type":"\"md\" | \"sm\" | \"xs\"","required":false,"defaultValue":"sm","description":"Compact height, font size, and spacing: xs, sm, or md."}]}},{"name":"Banner","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Banner\ndescription: Feedback content with independent status, appearance, and palette.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport BannerReference from '/snippets/ui/generated/feedback/banner.mdx';\n\n## Overview\n\n`Banner` lays out caller-provided content, an optional `icon` node and an optional `action` node. `status` describes feedback meaning: `neutral`, `info`, `success`, `warning` or `error`. `variant` selects `solid` or `soft` appearance. An explicit `color` overrides the status palette without changing its meaning.\n\nDefaults are `status=\"info\"` and `variant=\"solid\"`. The default status palettes are gray, blue, green, orange and red, respectively.\n\n<StoryEmbed\n storyId=\"ui-feedback-banner--display\"\n title=\"Banner example\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { Banner } from 'twenty-ui/primitives/feedback';\n\nexport const SyncBanner = () => (\n <Banner status=\"info\" variant=\"solid\">\n Contact sync is temporarily paused. Your saved records remain available.\n </Banner>\n);\n```\n\n## Actions and appearance\n\n<StoryEmbed\n storyId=\"ui-feedback-banner--catalog\"\n title=\"Banner feedback palettes and variants\"\n height={560}\n/>\n\n```tsx\nimport { Banner } from 'twenty-ui/primitives/feedback';\nimport { IconInfoCircle } from 'twenty-ui/icon';\n\nexport const SyncBanner = ({ onRetry }: { onRetry: () => void }) => (\n <Banner\n status=\"error\"\n variant=\"soft\"\n color=\"blue\"\n icon={<IconInfoCircle aria-hidden=\"true\" />}\n action={<Banner.Action onClick={onRetry}>Retry sync</Banner.Action>}\n >\n Contact sync could not finish.\n </Banner>\n);\n```\n\n`Banner.Action` provides a small outline button that inherits the banner’s displayed color, including explicit palette overrides and solid appearances. It supports Button interactions, links, refs and custom rendering. The `action` slot also accepts arbitrary controls.\n\nThe root target is a `div`. Native attributes, event handlers, `className`, `style` and `ref` apply to that root. `render` accepts a Base UI element or callback; the callback receives native props and ref plus resolved `status`, `variant` and `color` state. Preserve the supplied props and ref when composing another element.\n\n```tsx\nimport { Banner } from 'twenty-ui/primitives/feedback';\n\nexport const SyncResult = () => (\n <Banner\n status=\"success\"\n variant=\"soft\"\n role=\"status\"\n aria-live=\"polite\"\n aria-atomic=\"true\"\n render={<section aria-label=\"Sync result\" />}\n >\n Contacts are up to date.\n </Banner>\n);\n```\n\nStatus does not automatically assign `role`, `aria-live` or announcements. Choose them at the caller when updates should be announced. Supply accessible names for controls and mark decorative icon nodes with `aria-hidden`. The caller owns visibility and dismissal.\n\n## Dismissal\n\nPass `onDismiss` to show a 24px ghost close control at the logical inline end. The control inherits the banner color and has `type=\"button\"`. `closeLabel` defaults to `Close`; supply localized text in your application. Balanced inline spacing keeps centered content and actions clear of the control.\n\nThe caller owns visibility. Activating the close control calls `onDismiss` and leaves the banner mounted until its caller updates state. Other actions remain in the `action` slot.\n\n```tsx\nimport { useState } from 'react';\nimport { Banner } from 'twenty-ui/primitives/feedback';\n\nexport const DismissibleSyncBanner = () => {\n const [isVisible, setIsVisible] = useState(true);\n\n return isVisible ? (\n <Banner\n onDismiss={() => setIsVisible(false)}\n closeLabel=\"Dismiss sync message\"\n >\n Contacts are syncing in the background.\n </Banner>\n ) : null;\n};\n```\n\n<StoryEmbed\n storyId=\"ui-feedback-banner--dismissible\"\n title=\"Dismissible banner\"\n height={160}\n/>\n\n## Migration\n\nReplace `variant=\"primary\"` with `variant=\"solid\"` and `variant=\"secondary\"` with `variant=\"soft\"`. Replace `color=\"danger\"` with `status=\"error\"`, or `color=\"red\"` when only the palette should change. Blue information banners can use `status=\"info\"`.\n\n## Props\n\n<BannerReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Banner","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/banner","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trailing ReactNode. Banner.Action supplies a small outline action that inherits the resolved banner color; arbitrary controls are also accepted."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-provided content, including text, links and controls."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged onto the root div or composed element."},{"name":"closeLabel","type":"string","required":false,"defaultValue":"Close","description":"Accessible label for the close control. Defaults to Close; supply localized text when needed."},{"name":"color","type":"\"blue\" | \"gray\" | \"green\" | \"orange\" | \"red\"","required":false,"defaultValue":"status palette","description":"Palette override: gray, blue, green, orange or red. When omitted, status selects the corresponding palette."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional leading ReactNode. The caller supplies decorative or accessible icon semantics."},{"name":"onDismiss","type":"(() => void)","required":false,"defaultValue":null,"description":"Renders a 24px ghost close control and calls this callback when activated. The caller owns visibility."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or to the DOM element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, BannerState>","required":false,"defaultValue":null,"description":"Base UI element or render callback. The callback receives native props/ref and resolved status, variant and color state."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"info","description":"Feedback meaning: neutral, info, success, warning or error. Defaults to info. Does not assign a role or live region."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root div or composed element."},{"name":"variant","type":"\"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Solid or soft appearance. Defaults to solid, independently of status."}],"parts":[{"name":"Action","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Loader","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Loader\ndescription: Display a compact animated loading indicator beside a status label.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport LoaderReference from '/snippets/ui/generated/feedback/loader.mdx';\n\n## Overview\n\n`Loader` shows an animated dot inside a small bordered capsule. Use it while an operation is in progress and the percentage is unknown. For numeric progress, use [ProgressBar](/ui/primitives/feedback/progress-bar).\n\n<StoryEmbed\n storyId=\"ui-feedback-loader--display\"\n title=\"Loader example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Loader } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype SaveFeedbackProps = { isSaving: boolean };\n\nexport const SaveFeedback = ({ isSaving }: SaveFeedbackProps) => (\n <Text\n render={<div />}\n role=\"status\"\n style={{ display: 'flex', alignItems: 'center', gap: 8 }}\n >\n {isSaving && <Loader color=\"blue\" aria-hidden=\"true\" render={<span />} />}\n {isSaving ? 'Saving changes' : 'Changes saved'}\n </Text>\n);\n```\n\nPlace visible status text beside the loader in a wrapper. The loader is a fixed-size visual indicator and does not accept children.\n\nThe application owns loading state. Keep the status wrapper mounted so text updates can be announced. The loader assigns no label or live-region role by default. Use `aria-hidden=\"true\"` when surrounding text or a button already supplies loading feedback.\n\n## Native composition and labeling\n\nNative props, `className`, `style`, and `ref` target the container div. `render` accepts an element or callback through Base UI composition. Styles override color defaults. `LoaderProps` is exported from the feedback family.\n\nFor a standalone indicator, provide an explicit status role and accessible name. The animated dot remains decorative.\n\n```tsx\nimport { Loader, type LoaderProps } from 'twenty-ui/primitives/feedback';\n\nconst loadingProps: LoaderProps = {\n role: 'status',\n 'aria-label': 'Loading results',\n color: 'blue',\n};\n\nexport const LoadingResults = () => (\n <Loader {...loadingProps} render={<span />} />\n);\n```\n\nUse `aria-labelledby` instead when visible text names the status. Keep a live-region owner mounted when it needs to announce changing text. The application owns when feedback appears and what it says.\n\n## Color\n\nPass a theme palette color to set both the border and dot. Without a color, the loader inherits a surrounding button color when available, otherwise it uses the tertiary text color. For a button action, prefer [Button's loading state](/ui/primitives/input/button#state-ownership), which keeps the feedback inside the control.\n\n## Props\n\n<LoaderReference />\n\n<PageBanner illustration=\"card-page-background-jobs\" />\n","api":{"name":"Loader","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/loader","props":[{"name":"aria-hidden","type":"Booleanish","required":false,"defaultValue":null,"description":"Hide a decorative loader when another element supplies loading feedback."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name for a labeled loader status."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of text that names the loader status."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the loader container class."},{"name":"color","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"turquoise\" | \"violet\" | \"yellow\"","required":false,"defaultValue":null,"description":"Theme color for the animated dot and border. When omitted, inherits the button color if available, otherwise the tertiary text color."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the container div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Supply status to expose loading feedback as a live region. No role is assigned by default."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles merged with the loader color defaults. Explicit styles win."}]}},{"name":"Skeleton","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Skeleton\ndescription: Show themed placeholder shapes while content loads.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport SkeletonReference from '/snippets/ui/generated/feedback/skeleton.mdx';\n\n## Overview\n\n`Skeleton` provides a placeholder shape with theme colors and a moving highlight. Compose shapes in the layout of the content being loaded. The application owns loading state and feature-specific layouts.\n\n<StoryEmbed\n storyId=\"ui-feedback-skeleton--display\"\n title=\"Skeleton shapes\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { Skeleton, SKELETON_HEIGHT_SIZES } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const LoadingProfile = () => (\n <Text render={<div />} style={{ display: 'flex', gap: 16 }}>\n <Skeleton width={40} height={40} borderRadius=\"50%\" />\n <Text\n render={<div />}\n style={{ display: 'flex', flexDirection: 'column', gap: 8 }}\n >\n <Skeleton width={180} height={SKELETON_HEIGHT_SIZES.s} />\n <Skeleton width={120} height={SKELETON_HEIGHT_SIZES.xs} />\n </Text>\n </Text>\n);\n```\n\nSkeleton renders as a block and never grows wider than its container. Use `layout=\"inline\"` to place a placeholder inside a line of text.\n\nNumeric dimensions use pixels. CSS lengths such as percentages and `em` are also supported. Without dimensions, the placeholder fills the available width and uses the inherited font height. Use equal dimensions and `borderRadius=\"50%\"` for a circle.\n\n`SKELETON_HEIGHT_SIZES` provides shared heights for `xs` (13px), `s` (16px), `m` (24px), `l` (32px) and `xl` (40px). Keep layout-specific dimensions in the application.\n\nEach `Skeleton` renders one placeholder. Keep repeated lines, text-line spacing and loading regions in application components that wrap the primitive.\n\n## Motion and accessibility\n\nSkeletons are decorative and have `aria-hidden=\"true\"` by default. Keep loading announcements in a host-owned status region instead of announcing each shape. Skeleton does not accept children.\n\nThe highlight moves from left to right on a 1.5-second ease-in-out loop and is hidden when the user prefers reduced motion. Pass `animated={false}` for a static placeholder.\n\n<StoryEmbed\n storyId=\"ui-feedback-skeleton--static\"\n title=\"Static skeleton\"\n height={90}\n/>\n\n## Composition and theme\n\nNative props, `className`, `style` and `ref` target the placeholder span. Use `render` to compose another element. Explicit native styles override dimension and color props.\n\nThe base and highlight colors default to the theme tertiary background and lighter transparent background. Use `baseColor`, `highlightColor` and `borderRadius` to override them. Corners stay round, including when the theme uses squircles. The default radius uses the `smRound` theme token (4px). Pass `themeCssVariables.border.radius.mdRound` from `twenty-ui/theme` for 8px corners. Custom pixel and CSS radii remain supported, including `borderRadius={80}` for a narrow capsule and `borderRadius=\"50%\"` for a circle. No skeleton-specific provider or stylesheet import is needed after loading `twenty-ui/style.css` and the UI theme.\n\n## Props\n\n<SkeletonReference />\n\n<PageBanner illustration=\"section-ui-primitives\" />\n","api":{"name":"Skeleton","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/skeleton","props":[{"name":"animated","type":"boolean","required":false,"defaultValue":"true","description":"Animate the highlight by default. Reduced-motion preferences always disable animation."},{"name":"aria-hidden","type":"Booleanish","required":false,"defaultValue":null,"description":"Placeholders are decorative and hidden from assistive technology by default. The host owns loading announcements."},{"name":"baseColor","type":"BackgroundColor","required":false,"defaultValue":null,"description":"Placeholder background color. Defaults to the theme tertiary background."},{"name":"borderRadius","type":"BorderRadius<string | number>","required":false,"defaultValue":null,"description":"Round corner radius in pixels or a CSS length. Defaults to the 4px smRound theme token. Use mdRound for 8px corners or a custom radius for circles and capsules."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the placeholder class."},{"name":"height","type":"Height<string | number>","required":false,"defaultValue":null,"description":"Placeholder height in pixels or a CSS length. Defaults to the inherited font height."},{"name":"highlightColor","type":"BackgroundColor","required":false,"defaultValue":null,"description":"Animated highlight color. Defaults to the theme lighter transparent background."},{"name":"layout","type":"\"block\" | \"inline\"","required":false,"defaultValue":"block","description":"`block` renders a block without a text node. `inline` sizes and aligns the placeholder like a line of text."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the placeholder span, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles merged with the placeholder dimensions and colors. Explicit styles win."},{"name":"width","type":"Width<string | number>","required":false,"defaultValue":null,"description":"Placeholder width in pixels or a CSS length. Defaults to the available width and never exceeds the container."}]}},{"name":"Progress","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: Progress\ndescription: Compose accessible progress with shared range, labeling, and value semantics.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ProgressReference from '/snippets/ui/generated/feedback/progress.mdx';\n\n## Overview\n\n`Progress` exposes the installed Base UI parts: `Root`, `Track`, `Indicator`, `Label`, and `Value`. Import them from `twenty-ui/primitives/feedback`. Use [ProgressBar](/ui/primitives/feedback/progress-bar) or [ProgressRing](/ui/primitives/feedback/progress-ring) for a convenient appearance with the same semantic contract.\n\n<StoryEmbed\n storyId=\"ui-feedback-progress--display\"\n title=\"Composed progress example\"\n height={100}\n/>\n\n## Usage\n\n`Root` owns the controlled value and accessible progressbar semantics. `Label` supplies its accessible name. `Value` displays the formatted value. `Track` and `Indicator` describe the visual fill; the indicator width comes from the root's normalized range. The parts do not impose an appearance.\n\n```tsx\nimport { Progress } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportProgress = () => (\n <Progress.Root\n value={70}\n min={20}\n max={120}\n style={{\n display: 'grid',\n gridTemplateColumns: '1fr auto',\n alignItems: 'center',\n gap: 8,\n width: 320,\n maxWidth: '100%',\n }}\n >\n <Progress.Label render={<Text />}>Importing records</Progress.Label>\n <Progress.Value render={<Text />} />\n <Progress.Track\n style={{\n gridColumn: '1 / -1',\n height: 8,\n background: 'var(--t-background-tertiary)',\n }}\n >\n <Progress.Indicator\n style={{\n height: '100%',\n background: 'var(--t-font-color-primary)',\n }}\n />\n </Progress.Track>\n </Progress.Root>\n);\n```\n\nThis range displays `50%` while `aria-valuenow` is `70`, `aria-valuemin` is `20`, and `aria-valuemax` is `120`. The application owns requests, timing, and progress updates. There is no `defaultValue` or automatic advancement.\n\n## Values, ranges, and indeterminate progress\n\n`min` defaults to `0`, and `max` defaults to `100`. Supply finite bounds with `min < max`. Finite values outside the range are clamped for the semantic value, formatted value, and visual fill. Completion occurs at the maximum. Changing the range recalculates the percentage without changing the raw value supplied by the application.\n\nPass `value={null}` when the amount of progress is unknown. The root then has indeterminate status, omits `aria-valuenow`, and uses `indeterminate progress` as its default accessible value text. Non-finite values also remain indeterminate; they are not converted to zero. The raw `Indicator` has no computed percentage width in that state, so the composition chooses its indeterminate appearance.\n\n```tsx\nimport { ProgressBar } from 'twenty-ui/primitives/feedback';\n\nexport const PendingImport = () => (\n <ProgressBar value={null} aria-label=\"Preparing the import\" />\n);\n```\n\n## Labels and formatting\n\nCompose `Progress.Label` inside `Root`, or set native `aria-label` or `aria-labelledby`. Use `aria-valuetext` for a human-readable alternative when a percentage is insufficient.\n\nThe default formatter displays the normalized percentage. `locale` and `format` retain the installed `Intl.NumberFormat` contract; an explicit `format` formats the clamped numeric value. `getAriaValueText(formattedValue, value)` receives that formatted text and the raw application value, including `null`. It changes the accessible value text without changing the fill.\n\n```tsx\nimport { Progress } from 'twenty-ui/primitives/feedback';\n\nexport const RecordCount = () => (\n <Progress.Root\n value={600}\n max={1000}\n format={{ style: 'decimal' }}\n getAriaValueText={(formattedValue) => `${formattedValue} of 1,000 records`}\n >\n <Progress.Label>Importing records</Progress.Label>\n <Progress.Value>\n {(formattedValue) => `${formattedValue} / 1,000`}\n </Progress.Value>\n </Progress.Root>\n);\n```\n\n`Progress.Value` receives both the formatted value and raw value through its optional child callback. For indeterminate progress, the callback receives `indeterminate` as formatted text; without a callback, the value part displays no content. Display content does not automatically become the accessible name or accessible value text.\n\n## Native props, refs, and composition\n\n| Part | Default DOM and ref target |\n| ----------- | -------------------------------------- |\n| `Root` | Outer `div` with progressbar semantics |\n| `Track` | Track `div` |\n| `Indicator` | Fill `div` |\n| `Label` | Label `span` |\n| `Value` | Value `span` |\n\nEvery part preserves native props, refs, and the installed `render` composition contract. Forward the supplied props and ref when replacing an element. `className`, `style`, and `render` callbacks receive the public state with `status`: `progressing`, `complete`, or `indeterminate`. State attributes make the same status available to styles.\n\nThe entry point exports `ProgressStatus` and the `Props` and `State` types for every part, including `ProgressRootProps`, `ProgressRootState`, `ProgressIndicatorProps`, and `ProgressIndicatorState`. Each part forwards native event handlers. Applications own feature choreography and completion callbacks.\n\n## Props\n\n<ProgressReference />\n\n<PageBanner illustration=\"card-page-usage-limits\" />\n","api":{"name":"Progress","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/progress","props":[],"parts":[{"name":"Root","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name identifying the measured operation."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the visible label that names the operation."},{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"Human-readable progress value overriding the default formatted value."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Composed Progress parts and supporting content."},{"name":"className","type":"string | ((state: ProgressRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number | null) => string)","required":false,"defaultValue":null,"description":"Receives the formatted value and raw value, including null, and returns an accessible value description."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format the value. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"Inclusive maximum. Defaults to 100."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"Inclusive minimum. Defaults to 0."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through Root.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."},{"name":"value","type":"number | null","required":true,"defaultValue":null,"description":"Controlled value in the min/max range. Use null for indeterminate progress."}]},{"name":"Track","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The indicator and optional supporting content."},{"name":"className","type":"string | ((state: ProgressTrackState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the track div, or the element composed through Track.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressTrackState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressTrackState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: ProgressIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the indicator div, or the element composed through Indicator.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressIndicatorState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]},{"name":"Value","props":[{"name":"children","type":"((formattedValue: string | null, value: number | null) => ReactNode) | null","required":false,"defaultValue":null,"description":"Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content."},{"name":"className","type":"string | ((state: ProgressValueState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the value span, or the element composed through Value.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressValueState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressValueState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]},{"name":"Label","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Visible text that supplies the accessible name of the root."},{"name":"className","type":"string | ((state: ProgressLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its progress status."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the label span, or the element composed through Label.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressLabelState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: ProgressLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its progress status."}]}]}},{"name":"ProgressBar","entryPoint":"twenty-ui/primitives/feedback","content":"---\ntitle: ProgressBar\ndescription: Show measured or indeterminate progress with a horizontal bar.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ProgressBarReference from '/snippets/ui/generated/feedback/progress-bar.mdx';\n\n## Overview\n\n`ProgressBar` supplies a horizontal appearance for [Progress](/ui/primitives/feedback/progress). It preserves the complete root contract, including native attributes, refs, render composition, formatting, custom ranges, and indeterminate progress. Give it an `aria-label` that identifies the operation.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressbar-progressbar--display\"\n title=\"ProgressBar example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { ProgressBar } from 'twenty-ui/primitives/feedback';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype ImportProgressProps = { importedRecords: number | null };\n\nexport const ImportProgress = ({ importedRecords }: ImportProgressProps) => (\n <Text style={{ display: 'grid', gap: 8, width: 300 }}>\n <Text>Importing records: {importedRecords ?? 'preparing'}</Text>\n <ProgressBar\n value={importedRecords}\n max={1000}\n aria-label=\"Importing records\"\n />\n </Text>\n);\n```\n\n## State ownership and ranges\n\n`value` is required and controlled by the application. There is no `defaultValue` mode. The component does not start a request or advance progress by itself. Pass `null` when progress is unknown. Non-finite values also remain indeterminate.\n\n`min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for the semantic value and normalized fill. A value of `70` in the range `20` to `120` fills half the bar and reports `50%`, while `aria-valuenow` stays `70`.\n\n<StoryEmbed\n storyId=\"ui-feedback-progressbar-progressbar--custom-range\"\n title=\"A nonzero minimum and custom maximum\"\n height={80}\n/>\n\nUse `aria-valuetext`, `getAriaValueText`, `locale`, and `format` as described in [Progress](/ui/primitives/feedback/progress). Use composed Progress parts when labels and values need their own visible layout.\n\nUse [Toast](/ui/components/feedback/toast) for notifications with a dismiss countdown and hover pause.\n\n## Appearance and composition\n\n`size` selects a 6px or 8px track. `barColor` and `backgroundColor` accept CSS colors, including theme variables. `withBorderRadius` rounds the track and indicator. `withMinimumFillWidth` keeps a small cosmetic fill only between the minimum and completion. This minimum is at most 12px and half the track width, so a narrow track still distinguishes incomplete progress from completion. It does not fill an empty bar or change semantic values.\n\nNative attributes, `className`, `style`, and `ref` target the root. `className` and `style` can receive the progress state. `render` can replace the root while preserving its semantics. Indeterminate progress has its own appearance without reporting a numeric percentage. Reduced-motion preferences disable fill transitions and indeterminate motion.\n\nCompose [Progress parts](/ui/primitives/feedback/progress) for custom layouts or feature animation. Feature timing, grow-in, glints, springs, and completion callbacks belong to the application composition.\n\n## Migration\n\nReplace `ariaLabel` with native `aria-label`. The `withGrowIn`, `withGlint`, `withSpringFill`, and `onGrowInComplete` props are removed. Implement their appearance, timing, and completion callbacks in an application composition using [Progress parts](/ui/primitives/feedback/progress). Native `onAnimationEnd` remains available on the root.\n\n## Props\n\n<ProgressBarReference />\n\n<PageBanner illustration=\"card-page-usage-limits\" />\n","api":{"name":"ProgressBar","entryPoint":"twenty-ui/primitives/feedback","slug":"feedback/progress-bar","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name identifying the measured operation."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the visible label that names the operation."},{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"Human-readable progress value overriding the default formatted value."},{"name":"backgroundColor","type":"string","required":false,"defaultValue":"none","description":"CSS background color of the track."},{"name":"barColor","type":"string","required":false,"defaultValue":null,"description":"CSS color of the filled bar. Defaults to the primary text color."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Additional Progress parts or supporting content inside the root."},{"name":"className","type":"string | ((state: ProgressRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the progress root, or a callback receiving its status."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number | null) => string)","required":false,"defaultValue":null,"description":"Receives the formatted value and raw value, including null, and returns an accessible value description."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format the value. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"Inclusive maximum. Defaults to 100."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"Inclusive minimum. Defaults to 0."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>","required":false,"defaultValue":null,"description":"Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Bar height: sm (6px) or md (8px)."},{"name":"style","type":"CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the progress root, or a callback receiving its status."},{"name":"value","type":"number | null","required":true,"defaultValue":null,"description":"Controlled value in the min/max range. Use null for indeterminate progress."},{"name":"withBorderRadius","type":"boolean","required":false,"defaultValue":"false","description":"Rounds the track and indicator corners."},{"name":"withMinimumFillWidth","type":"boolean","required":false,"defaultValue":"true","description":"Applies a cosmetic minimum of up to 12px, capped at half the track width, only above the minimum and below completion."}]}},{"name":"SegmentedControl","entryPoint":"twenty-ui/components/input","content":"---\ntitle: SegmentedControl\ndescription: Choose one value from a compact group of labeled or icon options.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport SegmentedControlReference from '/snippets/ui/generated/components/input/segmented-control.mdx';\n\n## Overview\n\n`SegmentedControl` is a preset assembled from [Radio](/ui/primitives/input/radio) and [RadioGroup](/ui/primitives/input/radio-group), with joined options. Use it for a short, mutually exclusive choice. For navigation between content panels, use [Tabs](/ui/primitives/navigation/tabs).\n\n<StoryEmbed\n storyId=\"components-input-segmentedcontrol--display\"\n title=\"SegmentedControl example\"\n height={110}\n/>\n\n## Usage\n\nSupply an accessible group name with `aria-label` or `aria-labelledby`. Each option needs a unique string `value`. Selection belongs to the group; options do not have independent checked state.\n\n```tsx\nimport { SegmentedControl } from 'twenty-ui/components/input';\n\nexport const BillingPeriod = () => (\n <SegmentedControl\n aria-label=\"Billing period\"\n name=\"billingPeriod\"\n defaultValue=\"annual\"\n options={[\n { label: 'Annual', value: 'annual' },\n { label: 'Monthly', value: 'monthly' },\n ]}\n />\n);\n```\n\n`defaultValue` initializes selection. The group owns later changes. Add `onValueChange` if you need to observe them without controlling the value.\n\n## Controlled state\n\n```tsx\nimport { useState } from 'react';\nimport { SegmentedControl } from 'twenty-ui/components/input';\n\nexport const BillingPeriod = () => {\n const [period, setPeriod] = useState('annual');\n\n return (\n <SegmentedControl\n aria-label=\"Billing period\"\n name=\"billingPeriod\"\n value={period}\n onValueChange={setPeriod}\n options={[\n { label: 'Annual', value: 'annual' },\n { label: 'Monthly', value: 'monthly' },\n ]}\n />\n );\n};\n```\n\nKeep `value` in application state and update it in `onValueChange`. Do not combine `value` and `defaultValue` or switch ownership modes after mounting.\n\n## Icon options\n\n```tsx\nimport { SegmentedControl } from 'twenty-ui/components/input';\nimport { IconList, IconLayoutKanban } from 'twenty-ui/icon';\n\nexport const RecordLayout = () => (\n <SegmentedControl\n aria-label=\"Record layout\"\n defaultValue=\"list\"\n itemWidth=\"content\"\n options={[\n { value: 'list', startIcon: <IconList />, 'aria-label': 'List' },\n {\n value: 'kanban',\n startIcon: <IconLayoutKanban />,\n 'aria-label': 'Kanban',\n },\n ]}\n />\n);\n```\n\nAn icon-only option requires an `aria-label`. `startIcon` is decorative and hidden from assistive technology. Options with visible text use `label` and may also provide `startIcon`. Set `disabled` on an option to prevent its selection, or on the group to disable every option.\n\n## Keyboard, forms, and direction\n\nTab enters the group; arrow keys move between enabled options and update selection. This follows radio behavior. Dropdown selection groups move focus with arrow keys and select on activation. `itemWidth=\"equal\"` is the default; use `content` when labels should determine widths. Set `name` to include the selected value in native form submission. The preset preserves RadioGroup's `required`, `readOnly`, disabled state, and native form integration. `onValueChange` receives the selected value and Base UI event details, including `reason` and `cancel()`.\n\nFor right-to-left content, pair [DirectionProvider](/ui/primitives/layout/direction-provider) with a matching `dir` attribute. The provider controls directional interaction; `dir` controls the document layout.\n\n## Composition and native props\n\nNative props, `className`, `style`, `render`, and `ref` target the group's `div`. Use `render` to compose that group with another element; preserve its accessible name and radio-group semantics. Options render `span` elements with `role=\"radio\"` and hidden native radio inputs. The preset does not assign tab or tab-panel roles. For custom radio content, per-option native props, or a different radio render target, compose `Radio.Root` and `RadioGroup` directly.\n\n## Props\n\n<SegmentedControlReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"SegmentedControl","entryPoint":"twenty-ui/components/input","slug":"components/input/segmented-control","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Accessible group name. Supply this or `aria-labelledby`."},{"name":"aria-labelledby","type":"string","required":true,"defaultValue":null,"description":"ID of an element that labels the group. Supply this or `aria-label`."},{"name":"className","type":"string | ((state: RadioGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string","required":false,"defaultValue":null,"description":"The uncontrolled value of the radio button that should be initially selected.\n\nTo render a controlled radio group, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the radio inputs.\nUseful when the radio group is rendered outside the form."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Stretch the control to the width of its container."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"itemWidth","type":"\"content\" | \"equal\"","required":false,"defaultValue":"equal","description":"Use equal-width options or size each option to its content."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onValueChange","type":"((value: TValue, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Callback fired when the value changes."},{"name":"options","type":"readonly SegmentedControlOption<TValue>[]","required":true,"defaultValue":null,"description":"Options with a unique string `value`, a `label` or `startIcon`, and optional `disabled`. Icon-only options require an `aria-label`."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to select a different radio button in the group."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Control height: `sm` (24px) or `md` (32px)."},{"name":"style","type":"CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The controlled value of the radio item that should be currently selected.\n\nTo render an uncontrolled radio group, use the `defaultValue` prop instead."},{"name":"variant","type":"\"rectangle\" | \"round\"","required":false,"defaultValue":"round","description":"Shape: `round` is a pill, `rectangle` fills its container with form-field corners."}]}},{"name":"Collapsible","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: Collapsible\ndescription: Compose an accessible trigger and animated panel with controlled or uncontrolled expansion.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CollapsibleReference from '/snippets/ui/generated/layout/collapsible.mdx';\n\n## Overview\n\n`Collapsible` exposes Base UI's Root, Trigger, and Panel contracts. Root owns expansion state, Trigger supplies keyboard activation and the panel relationship, and Panel owns animation and content lifetime.\n\n<StoryEmbed\n storyId=\"ui-layout-collapsible--display\"\n title=\"Collapsible example\"\n height={160}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Collapsible } from 'twenty-ui/primitives/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportDetails = () => (\n <Collapsible.Root defaultOpen style={{ width: 360, maxWidth: '100%' }}>\n <Collapsible.Trigger render={<Button />}>\n Import details\n </Collapsible.Trigger>\n <Collapsible.Panel>\n <Text\n style={{\n paddingTop: 12,\n color: 'var(--t-font-color-secondary)',\n lineHeight: 1.5,\n }}\n >\n Match each CSV column to a record field before importing.\n </Text>\n </Collapsible.Panel>\n </Collapsible.Root>\n);\n```\n\nUse `defaultOpen` for uncontrolled expansion. Use `open` and `onOpenChange` when the application owns the state. The callback receives the requested boolean and Base UI event details, including `reason`, `event`, and `cancel()`. Canceling a change preserves the current state. An externally controlled panel can omit Trigger when its state comes from another control or application condition.\n\nTriggers inherit Root's `disabled` state and can override it with their own `disabled` prop. The native trigger supports Enter and Space and supplies `aria-expanded` and `aria-controls` automatically. Give each trigger a meaningful accessible name.\n\n## Anatomy\n\n```text\nCollapsible.Root\n├── Collapsible.Trigger\n└── Collapsible.Panel\n └── Content\n```\n\n## Native customization\n\nRoot and Panel render a `div`; Trigger renders a `button`. Each part accepts native attributes, handlers, `className`, `style`, refs, and Base UI `render` composition. Class and style callbacks receive the part's state. Forward all supplied props and the ref from custom render components. Set `nativeButton={false}` when Trigger renders a non-button element.\n\nPublic types include `CollapsibleRootProps`, `CollapsibleTriggerProps`, `CollapsiblePanelProps`, the three part state types, and `CollapsibleRootChangeEventDetails` and `CollapsibleRootChangeEventReason`.\n\n## Animation and content lifetime\n\nPanel defaults to `dimension=\"height\"`. Use `dimension=\"width\"` for horizontal expansion and constrain the content's width when needed. `containAnimation` defaults to `true`, clips overflow, and lays content out in a column. Set it to `false` when content needs to overflow during the transition.\n\nPanel's `duration` chooses a theme preset (`instant`, `fast`, `normal`, or `slow`) and defaults to `normal`. Reduced-motion preferences disable the transitions.\n\nPanel unmounts after closing by default. Use `keepMounted` to preserve local content state while hiding the closed panel. `hiddenUntilFound` lets browser page search reveal closed content and takes precedence over `keepMounted`.\n\n## Props\n\n<CollapsibleReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Collapsible","entryPoint":"twenty-ui/primitives/layout","slug":"layout/collapsible","props":[],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: CollapsibleRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Initial uncontrolled expansion state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Default disabled state inherited by the triggers in this root."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the requested open state and cancelable Base UI event details."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controlled expansion state. Use defaultOpen for uncontrolled state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsibleRootState>","required":false,"defaultValue":null,"description":"Replaces the root div. Forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: CollapsibleRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: CollapsibleTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables this trigger."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Set to false when render replaces the native button with another element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsibleTriggerState>","required":false,"defaultValue":null,"description":"Replaces the linked trigger button. Forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: CollapsibleTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Panel","props":[{"name":"className","type":"string | ((state: CollapsiblePanelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"containAnimation","type":"boolean","required":false,"defaultValue":"true","description":"Clips overflowing content during expansion and uses a column layout."},{"name":"dimension","type":"\"height\" | \"width\"","required":false,"defaultValue":"height","description":"Dimension animated when the panel opens and closes."},{"name":"duration","type":"\"fast\" | \"instant\" | \"normal\" | \"slow\"","required":false,"defaultValue":"normal","description":"Theme timing preset for both size and opacity. Native style can customize transition timing."},{"name":"hiddenUntilFound","type":"boolean","required":false,"defaultValue":"false","description":"Uses hidden until-found so browser page search can reveal the contents. Overrides keepMounted."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the closed panel mounted and hidden, preserving local content state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsiblePanelState>","required":false,"defaultValue":null,"description":"Replaces the animated panel div. Forward the supplied props and ref."},{"name":"style","type":"CSSProperties | ((state: CollapsiblePanelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Separator","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: Separator\ndescription: Separate adjacent content with a horizontal or vertical divider.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport SeparatorReference from '/snippets/ui/generated/layout/separator.mdx';\n\n## Overview\n\n`Separator` renders a `div` with `role=\"separator\"` and an accessible orientation. It uses the Base UI separator contract, including native props, refs, and `render` composition. Import `SeparatorProps` from the same entry point.\n\n<StoryEmbed\n storyId=\"ui-layout-separator--display\"\n title=\"Horizontal separator\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { Separator } from 'twenty-ui/primitives/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportSources = () => (\n <Text style={{ display: 'grid', gap: 'var(--t-spacing-3)' }}>\n <Text>Import records from a CSV file.</Text>\n <Separator />\n <Text>Connect an external data source.</Text>\n </Text>\n);\n```\n\n## Orientation and appearance\n\n`orientation` defaults to `horizontal`. Margins default to zero in both orientations. Horizontal separators fill the available width. Vertical separators stretch along their flex container. Give a standalone vertical separator a height. Control spacing through the parent layout, or use native `style` or `className` for explicit margins and line color. Base UI also accepts functions of the orientation for these props.\n\n<StoryEmbed\n storyId=\"ui-layout-separator--vertical-documentation\"\n title=\"Vertical separator\"\n height={150}\n/>\n\n## Labeled dividers\n\nUse [LabeledSeparator](/ui/components/layout/labeled-separator) for a text label between divider lines or at the end of a rule. It provides the layout and a single accessible separator name.\n\n```tsx\nimport { LabeledSeparator } from 'twenty-ui/components/layout';\n\nexport const SignInDivider = () => <LabeledSeparator>Or</LabeledSeparator>;\n```\n\n## Migration\n\nReplace the former horizontal helper with `Separator`. Remove `noMargin`, since margins now default to zero. To keep the former default spacing, add `style={{ marginBlock: 'var(--t-spacing-3)' }}`. Replace `color` with `style={{ backgroundColor: color }}`. Use `LabeledSeparator` for labeled dividers, pass the label as children, and rename `textPosition` to `labelPosition`. Replace separators used only for invisible spacing with layout spacing.\n\n## Props\n\n<SeparatorReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Separator","entryPoint":"twenty-ui/primitives/layout","slug":"layout/separator","props":[{"name":"className","type":"string | ((state: SeparatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class or function of the separator orientation."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"Direction of the divider: horizontal or vertical."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState>","required":false,"defaultValue":null,"description":"Element or render function composed with the native separator props and ref."},{"name":"style","type":"CSSProperties | ((state: SeparatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Native style or function of the separator orientation. Use it for spacing and line color."}]}},{"name":"ResizeHandle","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: ResizeHandle\ndescription: Resize a panel with pointer dragging or keyboard controls.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ResizeHandleReference from '/snippets/ui/generated/layout/resize-handle.mdx';\n\n## Overview\n\n`ResizeHandle` manages a numeric size and exposes a focusable separator. The application applies that size to the panel; the handle does not resize another element automatically.\n\n<StoryEmbed\n storyId=\"ui-layout-resizehandle--display\"\n title=\"ResizeHandle example\"\n height={600}\n/>\n\n## Usage\n\nUse `edge` for a panel boundary, or `axis=\"y\"` for inline height resizing and `axis=\"x\"` for inline width resizing. Give the handle a specific accessible name and use `aria-controls` to identify the panel.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { ResizeHandle } from 'twenty-ui/primitives/layout';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ResizableNotes = () => {\n const panelId = useId();\n const [height, setHeight] = useState(150);\n\n return (\n <Card.Root style={{ width: 300, maxWidth: '100%' }}>\n <Text\n id={panelId}\n style={{\n height,\n overflow: 'auto',\n padding: 16,\n boxSizing: 'border-box',\n }}\n >\n <Text\n style={{\n color: 'var(--t-font-color-primary)',\n fontWeight: 'var(--t-font-weight-medium)',\n }}\n >\n Record notes\n </Text>\n <Text style={{ marginTop: 8, lineHeight: 1.5 }}>\n Follow up with Morgan about the proposal. Share the revised timeline\n before Friday.\n </Text>\n </Text>\n <Text style={{ padding: 4 }}>\n <ResizeHandle\n axis=\"y\"\n defaultValue={150}\n onValueChange={setHeight}\n min={50}\n max={500}\n aria-label=\"Resize notes height\"\n aria-controls={panelId}\n />\n </Text>\n </Card.Root>\n );\n};\n```\n\nThe handle owns its value. `onValueChange` copies the latest size to the panel layout without controlling the handle. `defaultValue` only sets the initial size.\n\n## Controlled state\n\n```tsx\nimport { useId, useState } from 'react';\nimport { ResizeHandle } from 'twenty-ui/primitives/layout';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ResizableNotes = () => {\n const panelId = useId();\n const [height, setHeight] = useState(150);\n\n return (\n <Card.Root style={{ width: 300, maxWidth: '100%' }}>\n <Text\n id={panelId}\n style={{\n height,\n overflow: 'auto',\n padding: 16,\n boxSizing: 'border-box',\n }}\n >\n <Text\n style={{\n color: 'var(--t-font-color-primary)',\n fontWeight: 'var(--t-font-weight-medium)',\n }}\n >\n Record notes\n </Text>\n <Text style={{ marginTop: 8, lineHeight: 1.5 }}>\n Follow up with Morgan about the proposal. Share the revised timeline\n before Friday.\n </Text>\n </Text>\n <Text style={{ padding: 4 }}>\n <ResizeHandle\n axis=\"y\"\n value={height}\n onValueChange={setHeight}\n min={50}\n max={500}\n aria-label=\"Resize notes height\"\n aria-controls={panelId}\n />\n </Text>\n </Card.Root>\n );\n};\n```\n\nThe application owns the value and can update it from other controls. Reflect live changes in `value`; use `onValueCommitted` to save the final size. Keep `value` and `defaultValue` separate and retain the same ownership mode throughout the component's lifetime.\n\n## Panel edges and gaps\n\n`edge=\"left\"`, `\"right\"`, `\"top\"` or `\"bottom\"` determines both the axis and the physical increasing direction. Leftward movement grows a left edge, upward movement grows a top edge, and the opposite applies to right and bottom edges. This behavior stays the same in right-to-left content. Use either `edge` or `axis` and `direction`.\n\nWith `edge`, placement defaults to `\"edge\"`. Put the handle inside a panel with `position: 'relative'` to position it along that boundary. `placement=\"inline\"` keeps it in normal flow. Use `placement=\"gap\"` between sibling panels and set its width or height through `style` when the layout needs a gap. Gap handles have no visible grip by default.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { ResizeHandle } from 'twenty-ui/primitives/layout';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ResizableDetails = ({\n saveWidth,\n}: {\n saveWidth: (value: number) => void;\n}) => {\n const detailsId = useId();\n const [width, setWidth] = useState(380);\n\n return (\n <div style={{ display: 'flex', height: 200 }}>\n <Card.Root style={{ flex: 1 }}>\n <Text>Activity</Text>\n </Card.Root>\n <ResizeHandle\n edge=\"left\"\n placement=\"gap\"\n value={width}\n onValueChange={setWidth}\n onValueCommitted={saveWidth}\n min={280}\n max={800}\n style={{ width: 12 }}\n aria-label=\"Resize details\"\n aria-controls={detailsId}\n />\n <Card.Root id={detailsId} style={{ width }}>\n <Text>Details</Text>\n </Card.Root>\n </div>\n );\n};\n```\n\n<StoryEmbed\n storyId=\"ui-layout-resizehandle-panels--documentation\"\n title=\"ResizeHandle panel edge example\"\n height={250}\n/>\n\n<StoryEmbed\n storyId=\"ui-layout-resizehandle-panels--gap\"\n title=\"ResizeHandle panel gap example\"\n height={520}\n/>\n\nThe application owns the layout, saved size, collapse state and focus destination when collapsing removes the handle. Use `onActivate` for an optional collapse action.\n\n## Keyboard and bounds\n\nFor `axis=\"y\"`, Down increases the size and Up decreases it. For `axis=\"x\"`, Right increases and Left decreases in left-to-right content; the directions reverse under [DirectionProvider](/ui/primitives/layout/direction-provider) with `direction=\"rtl\"`.\n\nArrow keys use `step`, which defaults to `10`. Home moves to `min`, and End moves to `max`. Keys pressed with Alt, Control or Meta are ignored. Pointer dragging uses the pixel movement and is not snapped to `step`. Both interactions stay within the bounds. Pointer presses do not move focus; keyboard users reach the handle with Tab. `disabled` prevents resizing and removes the handle from the tab order.\n\nThe separator orientation describes the dividing edge: horizontal for height resizing and vertical for width resizing.\n\n## Physical directions and zoom\n\nSet `direction=\"normal\"` or `direction=\"reverse\"` when increasing size must follow a fixed physical direction, regardless of text direction. Normal increases with rightward or downward movement. Reverse increases with leftward or upward movement. Omit `direction` to retain the text-direction behavior described above.\n\n`scale` accepts a positive zoom factor or a function returning one. The handle samples it at pointer down and divides pointer movement by that value. Keyboard steps remain unchanged.\n\n## Gesture lifecycle\n\n`onValueChange` reports live values. `onValueCommitted` reports the final value after a successful pointer drag or an effective keyboard change. Home, End and arrow keys commit immediately when they change the size.\n\n`onResizeStart` receives the first bounded candidate after the pointer passes `dragThreshold`. The threshold defaults to `5` with `edge` and `0` otherwise, measured in physical pixels. `onResizeEnd` receives `{ cancelled, value }` for a started drag. Escape, pointer cancellation, lost pointer capture and unmounting cancel the gesture without committing; disabling the handle cancels it on its next pointer event. Cancellation calls `onValueChange` with the starting value, clamped to the current bounds. `onResizeEnd` receives that restored value.\n\nSupply `onActivate` to handle a click without dragging, Enter or Space. Crossing the threshold prevents the following pointer click from activating, even when the pointer returns to its starting position.\n\nNative handlers run before the handle's interaction. Calling `preventDefault()` in `onPointerDown` or `onKeyDown` skips that interaction. Preventing `onPointerMove` skips only that update and leaves the gesture active. Preventing `onPointerUp` cancels the drag, restores the starting bounded value and skips `onValueCommitted`. Pointer cancellation and lost capture still end the gesture.\n\n## Custom handle\n\n`ref`, native attributes, `className`, `style` and native event handlers target the separator root, a `div` by default. The ref does not target the resized panel or the visible grip.\n\n`children` replaces the visible grip, and `children={null}` hides it; it does not replace the separator behavior. `render` can replace the root element, and the ref then targets that replacement. Custom wrappers must [forward the supplied props and ref](/ui/primitives/overview#custom-components) so focus, pointer capture, keyboard handlers, and accessibility attributes reach the same element.\n\n## Props\n\n<ResizeHandleReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"ResizeHandle","entryPoint":"twenty-ui/primitives/layout","slug":"layout/resize-handle","props":[{"name":"axis","type":"\"x\" | \"y\"","required":false,"defaultValue":"y without edge","description":"Pointer movement axis without `edge`: `y` for height or `x` for width."},{"name":"defaultValue","type":"number | (readonly string[] & number)","required":false,"defaultValue":"150","description":"Initial size when the handle owns its state."},{"name":"direction","type":"\"normal\" | \"reverse\"","required":false,"defaultValue":null,"description":"Physical increasing direction. Omit to follow the horizontal text direction; use `normal` or `reverse` for a fixed physical edge."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables resizing and removes the handle from the tab order."},{"name":"dragThreshold","type":"number","required":false,"defaultValue":"5 with edge; 0 otherwise","description":"Physical pointer distance required before resizing starts. Movement below the threshold remains a click. Defaults to 5 with `edge` and 0 otherwise."},{"name":"edge","type":"\"bottom\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Physical panel edge. Determines the movement axis and increasing direction, independently of text direction."},{"name":"max","type":"number","required":false,"defaultValue":"500","description":"Maximum allowed size."},{"name":"min","type":"number","required":false,"defaultValue":"50","description":"Minimum allowed size."},{"name":"onActivate","type":"(() => void)","required":false,"defaultValue":null,"description":"Called for a click without dragging, Enter, or Space."},{"name":"onResizeEnd","type":"((details: { cancelled: boolean; value: number; }) => void)","required":false,"defaultValue":null,"description":"Called after a started drag ends, with its final value and whether it was cancelled. Cancellation restores the starting value within the current bounds."},{"name":"onResizeStart","type":"((value: number) => void)","required":false,"defaultValue":null,"description":"Called once with the first bounded drag value after the threshold is crossed."},{"name":"onValueChange","type":"((value: number) => void)","required":false,"defaultValue":null,"description":"Called with the bounded size during pointer or keyboard interaction and with the restored value on cancellation."},{"name":"onValueCommitted","type":"((value: number) => void)","required":false,"defaultValue":null,"description":"Called with the final size after a successful drag or an effective keyboard size change. Cancellation does not commit."},{"name":"placement","type":"\"edge\" | \"gap\" | \"inline\"","required":false,"defaultValue":"edge with edge; inline otherwise","description":"Layout mode: `inline` stays in normal flow, `edge` positions the handle on the panel edge, and `gap` sits between panels. Defaults to `edge` when `edge` is set and `inline` otherwise."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"scale","type":"number | (() => number)","required":false,"defaultValue":"1","description":"Pointer scale or resolver sampled at pointer down. Movement is divided by this positive scale; keyboard steps are unchanged."},{"name":"step","type":"number","required":false,"defaultValue":"10","description":"Keyboard arrow increment. Pointer movement uses the pixel delta."},{"name":"value","type":"number","required":false,"defaultValue":null,"description":"Current controlled size. Update it in `onValueChange` and apply it to the element being resized."}]}},{"name":"DirectionProvider","entryPoint":"twenty-ui/primitives/layout","content":"---\ntitle: DirectionProvider\ndescription: Coordinate directional keyboard and pointer interactions with the document direction.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport DirectionProviderReference from '/snippets/ui/generated/layout/direction-provider.mdx';\n\n## Overview\n\n`DirectionProvider` supplies `ltr` or `rtl` direction to Twenty UI controls. It does not render a DOM element or set an HTML `dir` attribute. Set both the provider direction and the matching document direction.\n\n<StoryEmbed\n storyId=\"ui-layout-directionprovider--display\"\n title=\"DirectionProvider example\"\n height={160}\n/>\n\n## Usage\n\n```tsx\nimport { SegmentedControl } from 'twenty-ui/components/input';\nimport { DirectionProvider } from 'twenty-ui/primitives/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype DirectionalChoicesProps = { direction: 'ltr' | 'rtl' };\n\nexport const DirectionalChoices = ({ direction }: DirectionalChoicesProps) => (\n <DirectionProvider direction={direction}>\n <Text dir={direction}>\n <SegmentedControl\n aria-label=\"Billing period\"\n defaultValue=\"annual\"\n options={[\n { label: 'Annual', value: 'annual' },\n { label: 'Monthly', value: 'monthly' },\n ]}\n />\n </Text>\n </DirectionProvider>\n);\n```\n\nThe host application supplies translated labels and chooses the direction. Direction context affects directional interactions; the HTML attribute handles text and layout. For example, [SegmentedControl](/ui/components/input/segmented-control) reverses horizontal arrow navigation, and [ResizeHandle](/ui/primitives/layout/resize-handle) reverses horizontal resizing.\n\n## Scope and state\n\nPlace one provider around the controls that share a direction. Nested providers can override the direction for a subtree; pair each override with a matching `dir` attribute. `direction` is application-owned and defaults to `ltr`, matching Base UI. Children are optional. Import `DirectionProviderProps` from the same entry point. The provider has no DOM target, native props, or ref. The provider does not translate content or choose direction from the locale automatically.\n\n## Portals and layout\n\nDropdown, Popover, Tooltip, Select, Dialog, and Toast portals carry the provider direction even when their container is outside the element with `dir`. Without a provider they inherit the direction of their container. Keep the provider direction and the trigger's HTML direction consistent. A scoped `ThemeProvider` continues to own the default portal container.\n\nSubmenus open toward `inline-end`. ArrowRight opens a submenu in LTR; ArrowLeft opens it in RTL. The opposite key returns to the parent. Explicit `left` and `right` popup placement still mean physical sides. Collision handling can move a popup when space is limited.\n\nText, indentation, attached button corners, and directional disclosure icons follow reading direction. Supplied icons retain their orientation. `AvatarGroup.overlap` still names a physical edge; the outer avatar does not extend beyond that edge in either direction.\n\n<StoryEmbed\n storyId=\"ui-layout-directionprovider--reading-directions\"\n title=\"Left-to-right and right-to-left layouts\"\n height={1260}\n/>\n\n## Props\n\n<DirectionProviderReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"DirectionProvider","entryPoint":"twenty-ui/primitives/layout","slug":"layout/direction-provider","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Controls that receive the direction context."},{"name":"direction","type":"\"ltr\" | \"rtl\"","required":false,"defaultValue":"ltr","description":"Reading direction used by directional interactions. Also set the matching HTML `dir` attribute on the content."}]}},{"name":"OverflowingTextWithTooltip","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: OverflowingTextWithTooltip\ndescription: Truncate long text and reveal its full value in a tooltip.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport OverflowingTextWithTooltipReference from '/snippets/ui/generated/typography/overflowing-text-with-tooltip.mdx';\n\n## Overview\n\n`OverflowingTextWithTooltip` truncates content within the available width. It checks for overflow on pointer entry and focus, then shows a tooltip only when needed. It manages tooltip visibility internally and exposes no controlled or uncontrolled open-state props. Use [OverflowingTextTooltipModeProvider](/ui/primitives/typography/overflowing-text-tooltip-mode-provider) to change when a subtree checks truncation or to turn the tooltip off.\n\n<StoryEmbed\n storyId=\"ui-surfaces-overflowingtextwithtooltip--display\"\n title=\"OverflowingTextWithTooltip example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport {\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const RecordTitle = () => (\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text=\"Quarterly account review and renewal preparation\"\n isFocusable\n />\n </Text>\n);\n```\n\nConstrain the width of the surrounding layout so truncation can occur. `isFocusable` gives the text a tab stop and opens the tooltip on focus or click. Keep essential information available to users who cannot hover.\n\n## Choose typography\n\n`size`, `weight` and `color` match [Text](/ui/primitives/typography/text). They are optional and inherit independently when omitted. Explicit typography applies to the displayed text; the tooltip retains its shared appearance.\n\n```tsx\nimport { OverflowingTextWithTooltip } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceCaption = () => (\n <OverflowingTextWithTooltip\n text=\"Quarterly account review and renewal preparation\"\n size=\"xs\"\n weight=\"semibold\"\n color=\"light\"\n style={{ maxWidth: 220 }}\n />\n);\n```\n\n## Multiline content\n\n```tsx\nimport {\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const RecordDescription = () => (\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text=\"Review the account history, confirm the renewal date, and prepare the next conversation with the customer.\"\n lineClamp={2}\n isTooltipMultiline\n isFocusable\n />\n </Text>\n);\n```\n\n`lineClamp` matches Text and limits the displayed lines; use a positive integer. `isTooltipMultiline` preserves whitespace and line breaks inside the tooltip. Without a row limit, text truncates on one line.\n\n## Custom content and timing\n\n```tsx\nimport {\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const ImportResult = () => (\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text={<strong>24 records imported successfully</strong>}\n tooltipContent=\"24 records imported successfully\"\n tooltipPlace=\"top\"\n tooltipDelay={300}\n isFocusable\n />\n </Text>\n);\n```\n\nReact content requires a plain-string `tooltipContent`. With string text, that prop can override the tooltip label; otherwise the text itself is used. An empty or missing label does not open a tooltip. String URLs remain plain text. Supply links explicitly in `text` or through `render`. Link content and navigation stay caller-owned.\n\n`alwaysShowTooltip` allows the tooltip even without truncation. `tooltipDelay` controls the hover delay and defaults to 500 milliseconds. `tooltipPlace` defaults to `bottom`.\n\nNative attributes, styles, class names, event handlers, and refs target the displayed Text element, a `div` by default. `render` can replace that element while retaining truncation and tooltip behavior. `OverflowingTextWithTooltipProps` is exported from `twenty-ui/primitives/typography`. Typography inherits from the surrounding layout unless an explicit typography prop is supplied. Set `truncate={false}` to wrap; choose either `truncate` or `lineClamp`. Focusable rendered elements and a caller-supplied `tabIndex` also reveal the tooltip on focus. Use [Text](/ui/primitives/typography/text) and [Tooltip](/ui/primitives/surfaces/tooltip) directly when you need custom composition. Interactive popup content belongs in [Popover](/ui/primitives/surfaces/popover).\n\n## Explicit links\n\n```tsx\nimport { OverflowingTextWithTooltip } from 'twenty-ui/primitives/typography';\n\nexport const DocumentationLink = () => (\n <OverflowingTextWithTooltip\n text=\"https://twenty.com/developers\"\n render={\n <a href=\"https://twenty.com/developers\" aria-label=\"Documentation\" />\n }\n style={{ maxWidth: 160, display: 'block' }}\n />\n);\n```\n\nUse a single anchor for the whole label, or supply individual anchors in React content with a plain `tooltipContent`. The component adds no anchors of its own. Keep tooltip content informational.\n\n## Migration\n\nReplace `displayedMaxRows` with `lineClamp`. The former `size=\"small\"` and `size=\"large\"` options controlled height, not font size. `large` set a 16px height. The new `size` selects theme font sizes and accepts no legacy aliases; use native `style` or `className` for height constraints. `color` now accepts semantic colors; move arbitrary CSS colors to `style={{ color: customColor }}`. Move intentional URL recognition into caller-owned content. No automatic linkification remains in this component.\n\n## Props\n\n<OverflowingTextWithTooltipReference />\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"OverflowingTextWithTooltip","entryPoint":"twenty-ui/primitives/typography","slug":"typography/overflowing-text-with-tooltip","props":[{"name":"alwaysShowTooltip","type":"boolean","required":false,"defaultValue":null,"description":"Allows the tooltip even when the text is not truncated."},{"name":"color","type":"\"light\" | \"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":null,"description":"Semantic text color. Omitted values inherit; native style supports runtime colors."},{"name":"isFocusable","type":"boolean","required":false,"defaultValue":null,"description":"Adds an optional tab stop. Native tabIndex and focusable render elements also open the tooltip on focus."},{"name":"isTooltipMultiline","type":"boolean","required":false,"defaultValue":null,"description":"Preserves whitespace and line breaks in the tooltip."},{"name":"lineClamp","type":"number","required":false,"defaultValue":null,"description":"Positive integer limiting visible lines, matching Text. Cannot be combined with `truncate`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default div. Native props, styles, handlers and ref target the displayed text, not the popup."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\" | \"xxs\"","required":false,"defaultValue":null,"description":"Font size from the theme scale. Omitted values inherit; this does not set height."},{"name":"text","type":"string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined","required":true,"defaultValue":null,"description":"Caller-owned text or React content. Non-string content requires `tooltipContent`. URLs stay plain text."},{"name":"tooltipContent","type":"string","required":false,"defaultValue":null,"description":"Plain text displayed in the tooltip. Defaults to nonempty string `text`."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":null,"description":"Hover delay in milliseconds."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Preferred side of the tooltip."},{"name":"truncate","type":"boolean","required":false,"defaultValue":null,"description":"Single-line ellipsis by default. Set false to wrap. Cannot be combined with `lineClamp`."},{"name":"weight","type":"\"medium\" | \"regular\" | \"semibold\"","required":false,"defaultValue":null,"description":"Theme font weight. Omitted values inherit."}]}},{"name":"OverflowingTextTooltipModeProvider","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: OverflowingTextTooltipModeProvider\ndescription: Choose when OverflowingTextWithTooltip checks truncation for a subtree.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport OverflowingTextTooltipModeProviderReference from '/snippets/ui/generated/typography/overflowing-text-tooltip-mode-provider.mdx';\n\n## Overview\n\n`OverflowingTextTooltipModeProvider` sets how every [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip) inside it handles its tooltip. It renders no DOM element.\n\n<StoryEmbed\n storyId=\"ui-typography-overflowingtexttooltipmodeprovider--display\"\n title=\"Overflowing text tooltip mode provider example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport {\n OverflowingTextTooltipModeProvider,\n OverflowingTextWithTooltip,\n Text,\n} from 'twenty-ui/primitives/typography';\n\nexport const RecordCell = () => (\n <OverflowingTextTooltipModeProvider mode=\"measure-on-hover\">\n <Text style={{ maxWidth: 220 }}>\n <OverflowingTextWithTooltip\n text=\"Quarterly account review and renewal preparation\"\n isFocusable\n />\n </Text>\n </OverflowingTextTooltipModeProvider>\n);\n```\n\nHover or focus the truncated label to read its full value. Change `mode` in the Storybook controls to compare when the tooltip is available.\n\n## Modes\n\n- `measure-on-hover`, the default without a provider, checks truncation on pointer entry and focus. A label that fits stays out of the way of a parent tooltip.\n- `measure-on-open` checks truncation when the tooltip tries to open. Use it for labels that mount under the pointer, such as a hover overlay, where no pointer entry happens.\n- `disabled` renders only the text, without any tooltip parts. Use it for many labels that a user cannot hover, such as content covered by an overlay.\n\n<StoryEmbed\n storyId=\"ui-typography-overflowingtexttooltipmodeprovider--disabled\"\n title=\"Tooltip disabled for a subtree\"\n height={90}\n/>\n\nNested providers override the mode for their subtree.\n\n## Props\n\n<OverflowingTextTooltipModeProviderReference />\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"OverflowingTextTooltipModeProvider","entryPoint":"twenty-ui/primitives/typography","slug":"typography/overflowing-text-tooltip-mode-provider","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Content whose OverflowingTextWithTooltip instances use the mode."},{"name":"mode","type":"\"disabled\" | \"measure-on-hover\" | \"measure-on-open\"","required":true,"defaultValue":null,"description":"`measure-on-hover` checks truncation on pointer entry and focus. `measure-on-open` checks it when the tooltip tries to open. `disabled` renders only the text."}]}},{"name":"LightIconButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: LightIconButton\ndescription: Present lightweight icon actions with standard or subtle emphasis.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport LightIconButtonReference from '/snippets/ui/generated/components/input/light-icon-button.mdx';\n\n## Overview\n\n`LightIconButton` composes [IconButton](/ui/components/input/icon-button) with a ghost surface and a small size. Supply an accessible name and decorative icon content.\n\n<StoryEmbed\n storyId=\"ui-input-button-lighticonbutton--display\"\n title=\"Light icon button\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\n\nexport const SearchAction = () => (\n <LightIconButton aria-label=\"Search\">\n <IconSearch />\n </LightIconButton>\n);\n```\n\nStandard emphasis uses secondary neutral text; subtle emphasis uses tertiary text. Explicit child appearance takes precedence over ButtonGroup values, followed by the component defaults. Semantic colors retain their own contrast treatment. Small controls are 24px with a 14px icon; medium controls are 32px with a 16px icon. Compact controls use `size=\"xs\"` and are 20px.\n\n## Visual options\n\nCompare emphasis at small and medium sizes, including selected, loading, and disabled states.\n\n<StoryEmbed\n storyId=\"ui-input-button-lighticonbutton--catalog\"\n title=\"Light icon button emphasis, sizes, and states\"\n height={410}\n/>\n\n## State and interaction\n\nButton owns keyboard activation, disabled and loading behavior, refs, native attributes, and render composition. The native default is `type=\"button\"`. Use `aria-pressed` for toggles and `aria-expanded` for disclosures. The application owns these states and can set `color=\"accent\"` to highlight a selected action. Keyboard focus uses the shared focus ring.\n\nTooltip text is optional and does not replace an accessible name from `aria-label` or `aria-labelledby`. Set `href` for a link. For application-owned routing, supply `render`, `nativeButton={false}`, and `role=\"link\"`.\n\n## Updating existing controls\n\nImport `LightIconButton` from `twenty-ui/components`. Replace `Icon={IconPlus}` with `<IconPlus />` children, `small`/`medium` with `sm`/`md`, `accent=\"tertiary\"` with `emphasis=\"subtle\"`, and `testId` with `data-testid`. Replace synthetic `active` and `focus` flags with semantic state and actual keyboard focus.\n\nReplace `LightIconButtonGroup` with [ButtonGroup](/ui/primitives/input/button-group) using `attached={false}` and explicit children. Set `disabled` on unavailable actions, including actions without a click handler. Wrappers and tooltip triggers can remain around each child.\n\n## Row actions\n\nUse a passive [ListItem](/ui/primitives/navigation/list-item) with an `actions` slot for independent controls. Pass one `LightIconButton` directly, or use `ButtonGroup` for multiple buttons. Each button owns its accessible name, click handler, and disabled state. Wrap dropdown triggers directly around the button.\n\n```tsx\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { IconEyeOff, IconTrash } from 'twenty-ui/icon';\nimport { ButtonGroup } from 'twenty-ui/primitives/input';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const RecordActions = () => (\n <ListItem\n actions={\n <ButtonGroup attached={false}>\n <LightIconButton aria-label=\"Hide record\">\n <IconEyeOff />\n </LightIconButton>\n <LightIconButton aria-label=\"Delete record\" disabled>\n <IconTrash />\n </LightIconButton>\n </ButtonGroup>\n }\n >\n Record\n </ListItem>\n);\n```\n\nA button without an `onClick` handler can remain enabled when a surrounding dropdown owns its interaction. Set `disabled` explicitly for unavailable buttons. Keep independent controls beside an actionable [ListItemButton](/ui/components/navigation/list-item-button) so each retains its own focus and activation.\n\n## Props\n\n<LightIconButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"LightIconButton","entryPoint":"twenty-ui/components/input","slug":"components/input/light-icon-button","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name describing the action. Required unless `aria-labelledby` supplies the name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element supplying the accessible name. Can be used instead of `aria-label`."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Icon content. Decorative and hidden from assistive technology."},{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"emphasis","type":"\"standard\" | \"subtle\"","required":false,"defaultValue":"standard","description":"Standard secondary text or subtle tertiary text. Semantic colors and solid surfaces keep their own colors."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":null,"description":"Square or round icon control."},{"name":"size","type":"\"md\" | \"sm\" | \"xs\"","required":false,"defaultValue":"sm","description":"Button size: `xs` (20px), `sm` (24px), or `md` (32px)."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"tooltip","type":"string","required":false,"defaultValue":null,"description":"Text displayed when hovering or focusing the button."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":null,"description":"Delay before showing the tooltip."},{"name":"tooltipOffset","type":"number","required":false,"defaultValue":null,"description":"Distance in pixels between the button and the tooltip."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Preferred placement of the tooltip relative to the button."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"ghost","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"IconButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: IconButton\ndescription: Trigger actions with accessible icon buttons.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport IconButtonReference from '/snippets/ui/generated/components/input/icon-button.mdx';\n\n## Overview\n\n`IconButton` composes [Button](/ui/primitives/input/button) with a square or round surface. Pass the icon as children and provide an accessible name with `aria-label` or `aria-labelledby`. Icon content is decorative and hidden from assistive technology.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--display\"\n title=\"Icon button with an accessible name\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\n\nexport const SearchButton = () => (\n <IconButton aria-label=\"Search\">\n <IconSearch />\n </IconButton>\n);\n```\n\nSizes are `xs` (20px), `sm` (24px), and `md` (32px). The defaults are `md`, `outline`, and `neutral`. Variants and colors match Button. Use `shape=\"round\"` for a circular button; the default shape is `square`.\n\n## Visual options\n\nCompare one visual choice at a time. Use the named tooltip, elevated, and grouped examples for composition.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--catalog\"\n title=\"Icon button variants, colors, sizes, shapes, elevation, and states\"\n height={810}\n/>\n\n## Accessible names\n\nUse `aria-label` for a name supplied directly on the control. When visible text already names the action, use `aria-labelledby` to reference it instead. At least one naming prop is required.\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const LabelledSearchButton = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>\n <Text render={<span />} id=\"records-search-label\">\n Search records\n </Text>\n <IconButton aria-labelledby=\"records-search-label\" tooltip=\"Find a record\">\n <IconSearch />\n </IconButton>\n </Text>\n);\n```\n\n<StoryEmbed\n title=\"Icon button named by visible text\"\n storyId=\"ui-components-iconbutton--labelled-by\"\n height={140}\n/>\n\n## Tooltip\n\nAdd `tooltip` to show text on hover and keyboard focus. Keep `aria-label` or `aria-labelledby` as the accessible name of the action. Disabled and loading buttons retain hover tooltips.\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconSearch } from 'twenty-ui/icon';\n\nexport const SearchRecordsButton = () => (\n <IconButton aria-label=\"Search\" tooltip=\"Search records\">\n <IconSearch />\n </IconButton>\n);\n```\n\n<StoryEmbed\n title=\"Icon button with tooltip\"\n storyId=\"ui-components-iconbutton--tooltip-documentation\"\n height={140}\n/>\n\nThe tooltip defaults to the bottom, with a 1000ms delay and a 5px offset. Use `tooltipPlace`, `tooltipDelay`, and `tooltipOffset` to adjust it. Omitting `tooltip` renders the button directly.\n\n## State ownership\n\nYour application supplies `loading` and `disabled`. Both prevent activation. Loading preserves the square dimensions and accessible label. The button does not track a selected value or set loading automatically after a click. Native keyboard focus follows the browser; use `aria-pressed` when your application owns a toggle state.\n\n## Elevated actions\n\nUse `elevated` to add a shadow and backdrop blur. The default neutral outline button also gains a bordered surface with matching icon and interaction colors. Other variants and semantic colors keep their existing palette.\n\n`elevated` defaults to `false`. It does not change positioning, visibility, or size. The size remains `md` (32px) by default; set `size=\"sm\"` for a 24px control.\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconPlus } from 'twenty-ui/icon';\n\nexport const AddWidgetButton = () => (\n <IconButton elevated size=\"sm\" aria-label=\"Add widget\">\n <IconPlus />\n </IconButton>\n);\n```\n\n<StoryEmbed\n title=\"Elevated icon action\"\n storyId=\"ui-components-iconbutton--elevated\"\n height={100}\n/>\n\nOmit `elevated` or set it to `false` to restore the standard appearance. Elevated buttons support the same tooltips, loading states, links, and keyboard interactions.\n\n<StoryEmbed\n title=\"Elevated icon action with tooltip\"\n storyId=\"ui-components-iconbutton--elevated-tooltip\"\n height={140}\n/>\n\nReplace existing `FloatingIconButton` controls with `IconButton elevated`. Pass the icon as children, use native `aria-label`, and map `small` to `sm` and `medium` to `md`. Supply `size=\"sm\"` when the previous control used its default size. Native focus and `aria-pressed` replace synthetic focus and active flags.\n\n`FloatingIconButtonGroup` is removed. Compose ButtonGroup with IconButton for grouped actions, and keep any shared floating surface in your layout.\n\n## Grouped actions\n\n```tsx\nimport { ButtonGroup } from 'twenty-ui/primitives/input';\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconPlus, IconSearch } from 'twenty-ui/icon';\n\nexport const RecordActions = () => (\n <ButtonGroup\n aria-label=\"Record actions\"\n size=\"sm\"\n variant=\"solid\"\n color=\"accent\"\n >\n <IconButton\n aria-label=\"Search records\"\n tooltip=\"Search records\"\n variant=\"outline\"\n color=\"neutral\"\n >\n <IconSearch />\n </IconButton>\n <IconButton aria-label=\"Create record\" tooltip=\"Create record\">\n <IconPlus />\n </IconButton>\n </ButtonGroup>\n);\n```\n\n[ButtonGroup](/ui/primitives/input/button-group) supplies defaults for size, variant, and color, plus adjoining corners. Explicit child props take precedence independently, including `size=\"xs\"`. Individual buttons do not need a position prop.\n\nKeep attached buttons the same size so their edges align. Set the size on the group and let each button inherit it.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--grouped-overrides\"\n title=\"Individual icon button appearance in a group\"\n height={140}\n/>\n\n## Links and forms\n\nWithout a custom `render`, `href` renders an anchor unless `nativeButton` is explicitly true. For a custom navigation anchor or router link, set `nativeButton={false}` and `role=\"link\"`. The renderer can own its destination without an IconButton `href`. Keep `nativeButton` true for a custom native button, and use false for a non-native action element. Explicit nativeButton and role props are preserved. Disabled and loading links cannot activate. Routing stays in the application.\n\nNative button and anchor attributes, event handlers, event details, refs, and render composition pass through to Button. The ref receives the actual root element. Tooltip composition preserves that root and its accessible name. The default is `type=\"button\"`; set `type=\"submit\"` explicitly for form submission.\n\n## Compact and round controls\n\nUse `size=\"xs\"` for a 20px control and `shape=\"round\"` for circular corners. Existing `RoundedIconButton` controls become `IconButton` with `shape=\"round\"`, `variant=\"solid\"`, and `color=\"accent\"`. Map their old `small` size to `xs` and `medium` size to `sm`. Supply icon children and an accessible name.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--round-documentation\"\n title=\"Round icon buttons in compact and regular sizes\"\n height={140}\n/>\n\n## Props\n\n<IconButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"IconButton","entryPoint":"twenty-ui/components/input","slug":"components/input/icon-button","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name describing the action. Required unless `aria-labelledby` supplies the name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element supplying the accessible name. Can be used instead of `aria-label`."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Icon content. Decorative and hidden from assistive technology."},{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":"neutral","description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true (false for the built-in href anchor)","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Square or round icon control."},{"name":"size","type":"\"md\" | \"sm\" | \"xs\"","required":false,"defaultValue":"md","description":"Button size: `xs` (20px), `sm` (24px), or `md` (32px)."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"tooltip","type":"string","required":false,"defaultValue":null,"description":"Text displayed when hovering or focusing the button."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":"1000","description":"Delay before showing the tooltip."},{"name":"tooltipOffset","type":"number","required":false,"defaultValue":"5","description":"Distance in pixels between the button and the tooltip."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Preferred placement of the tooltip relative to the button."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"outline","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"MainButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: MainButton\ndescription: Present prominent actions with shared design defaults.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport MainButtonReference from '/snippets/ui/generated/components/input/main-button.mdx';\n\n## Overview\n\nUse the shared `MainButton` component for a prominent action. It composes\n[Button](/ui/primitives/input/button) with a solid surface, elevation, semibold\ntext, and 12px horizontal padding. Its default color is neutral and size is `md`.\n\n<StoryEmbed\n storyId=\"ui-components-mainbutton--display\"\n title=\"MainButton example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { MainButton } from 'twenty-ui/components/input';\n\nexport const SaveAction = () => <MainButton>Save changes</MainButton>;\n```\n\n## Visual options\n\nCompare solid and outline appearances across default and small sizes, plus disabled and loading states.\n\n<StoryEmbed\n storyId=\"ui-components-mainbutton--catalog\"\n title=\"Main button variants and states\"\n height={230}\n/>\n\n## State ownership\n\n`MainButton` uses Button's state model and adds no state of its own. Your application supplies `loading` and `disabled`; there are no controlled and uncontrolled selection modes. See [Button's state ownership example](/ui/primitives/input/button#state-ownership) for managing an asynchronous action.\n\n## Forms and width\n\n```tsx\nimport { MainButton } from 'twenty-ui/components/input';\n\nexport const SaveProfile = () => (\n <MainButton type=\"submit\" fullWidth>\n Save profile\n </MainButton>\n);\n```\n\nWidth follows the content unless you set `fullWidth` or provide application\nlayout styling. Override `variant`, `color`, `size`, and `elevated` as needed;\nfor example, use `variant=\"outline\"` and `elevated={false}` for an outlined action.\n\nWith `color=\"inherit\"`, choose a non-solid variant explicitly or inherit one from ButtonGroup. The standalone solid default with inherited color throws a runtime error.\n\nKeep page layout in your application's styling.\n\n## Interaction\n\n`MainButton` accepts Button's native attributes, event handlers, refs, icon slots,\n`loading` and `disabled` props. Buttons default to `type=\"button\"`;\nset `type=\"submit\"` explicitly for form submission.\n\nUse `href` for a link. Supply `render` to choose a custom root, including an\napplication-owned router link. Set `nativeButton={false}` and `role=\"link\"` for\na navigation renderer. Custom native buttons keep `nativeButton` true.\n\n[ButtonGroup](/ui/primitives/input/button-group) can set a shared size, surface,\nand color. Explicit child appearance takes precedence over the group, followed by\nthe component defaults. Consumer classes, including state functions, pass through\nto the root.\n\n## Props\n\n<MainButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"MainButton","entryPoint":"twenty-ui/components/input","slug":"components/input/main-button","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":"true","description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Button height: `sm` (24px) or `md` (32px). The `link` variant uses its content height at either size."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"LightButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: LightButton\ndescription: Present lightweight actions with standard or subtle emphasis.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport LightButtonReference from '/snippets/ui/generated/components/input/light-button.mdx';\n\n## Overview\n\nUse the shared `LightButton` component for a lightweight action. It composes\n[Button](/ui/primitives/input/button) with a ghost surface, small size, regular\nfont weight, and no elevation.\n\n<StoryEmbed\n storyId=\"ui-components-lightbutton--display\"\n title=\"LightButton example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { LightButton } from 'twenty-ui/components/input';\n\nexport const FilterAction = () => <LightButton>Add filter</LightButton>;\n```\n\n## Visual options\n\nCompare standard and subtle emphasis across common action states.\n\n<StoryEmbed\n storyId=\"ui-components-lightbutton--catalog\"\n title=\"Light button emphasis and states\"\n height={230}\n/>\n\n## State ownership\n\n`LightButton` uses Button's state model and adds no state of its own. Your application supplies `loading` and `disabled`; `emphasis` only changes appearance. See [Button's state ownership example](/ui/primitives/input/button#state-ownership) for managing an asynchronous action. There are no controlled and uncontrolled selection modes.\n\n## Emphasis and icons\n\n```tsx\nimport { LightButton } from 'twenty-ui/components/input';\nimport { IconPlus } from 'twenty-ui/icon';\n\nexport const FilterActions = () => (\n <LightButton emphasis=\"subtle\" startIcon={<IconPlus />}>\n Add filter\n </LightButton>\n);\n```\n\nThe default `emphasis=\"standard\"` uses secondary neutral text.\n`emphasis=\"subtle\"` uses tertiary neutral text on ghost, outline, and soft\nsurfaces. Semantic colors and solid surfaces retain their contrast treatment.\n\nOverride `variant`, `color`, `size`, or `elevated` when needed.\n[ButtonGroup](/ui/primitives/input/button-group) can set a shared size, surface,\nand color. Explicit child appearance takes precedence over the group, followed by\nthe component defaults. Subtle emphasis does not replace the semantic color.\n\n## Interaction\n\n`LightButton` accepts Button's native attributes, refs, event handlers, icon\nslots, loading and disabled states, and render composition. Its native default\nis `type=\"button\"`. Set `type=\"submit\"` for submission or use `href` for a link.\nSupply `render` to choose a custom root, including an application-owned router\nlink. Set `nativeButton={false}` and `role=\"link\"` for a navigation renderer.\nCustom native buttons keep `nativeButton` true.\n\n## Props\n\n<LightButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"LightButton","entryPoint":"twenty-ui/components/input","slug":"components/input/light-button","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"emphasis","type":"\"standard\" | \"subtle\"","required":false,"defaultValue":"standard","description":"Uses secondary or tertiary text for neutral buttons. Semantic colors and solid surfaces retain their contrast treatment."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Button height: `sm` (24px) or `md` (32px). The `link` variant uses its content height at either size."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"ghost","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"EmojiPicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: EmojiPicker\ndescription: Search and select an emoji using caller-hosted Emojibase data.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport EmojiPickerReference from '/snippets/ui/generated/components/input/emoji-picker.mdx';\n\n## Overview\n\n`EmojiPicker` provides emoji search, category browsing, and keyboard selection. Your application supplies its labels, emoji data location, and selection handler.\n\n<StoryEmbed\n storyId=\"ui-input-emojipicker--display\"\n title=\"Search emojis and choose a reaction\"\n height={400}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { EmojiPicker } from 'twenty-ui/components/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { themeCssVariables } from 'twenty-ui/theme';\nimport { isDefined } from 'twenty-ui/utilities';\n\nexport const EmojiPickerExample = () => {\n const [emoji, setEmoji] = useState<string | undefined>();\n\n return (\n <Text\n style={{\n display: 'flex',\n flexDirection: 'column',\n gap: themeCssVariables.spacing[2],\n width: 296,\n }}\n >\n <EmojiPicker\n emojibaseUrl=\"/emojibase\"\n searchLabel=\"Search emojis\"\n loadingLabel=\"Loading emojis\"\n emptyLabel=\"No emoji found\"\n onEmojiSelect={setEmoji}\n />\n <Text role=\"status\">\n {isDefined(emoji) ? `Selected emoji: ${emoji}` : 'Choose an emoji'}\n </Text>\n </Text>\n );\n};\n```\n\nThe preview uses a small fixture catalogue. The usage example expects your application to serve Emojibase data at `/emojibase`.\n\n## Data and labels\n\n`emojibaseUrl` is required. The picker loads both `${emojibaseUrl}/${locale}/data.json` and `${emojibaseUrl}/${locale}/messages.json`. Host those files from the Emojibase data package for each supported locale. The default locale is `en`; supplying translated interface labels does not change the emoji catalogue locale.\n\nProvide localized `searchLabel`, `loadingLabel`, and `emptyLabel`. `searchLabel` names the search field and supplies its placeholder unless `searchPlaceholder` overrides it. Emoji names, categories, and search tags come from the selected Emojibase locale.\n\n## Selection and composition\n\n`onEmojiSelect` receives the selected Unicode emoji string. The picker keeps its search and active emoji internally. Your application owns any selected value, reaction counts, message identifiers, permissions, persistence, and popup visibility. Compose it inside [Dropdown](/ui/components/navigation/dropdown) when it needs a popup.\n\nThe picker uses eight columns and a 280px height. Set its container width to fit the grid. Native div attributes, handlers, styles, class names, and refs target its outer container.\n\n## Accessibility\n\nThe search input has the supplied accessible name. Focus it with Tab, or set `autoFocus` when opening a popup. Arrow keys navigate the emoji grid, and Enter selects the active emoji. Each emoji has an accessible name from the selected catalogue. `autoFocus` defaults to `false`.\n\n## Props\n\n<EmojiPickerReference />\n\n<PageBanner illustration=\"page-cover-emoji\" />\n","api":{"name":"EmojiPicker","entryPoint":"twenty-ui/components/input","slug":"components/input/emoji-picker","props":[{"name":"autoFocus","type":"boolean","required":false,"defaultValue":"false","description":"Focuses the search input when the picker mounts."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional class name applied to the picker root div."},{"name":"emojibaseUrl","type":"string","required":true,"defaultValue":null,"description":"Base URL for caller-hosted Emojibase data. The picker loads data.json and messages.json from the selected locale directory."},{"name":"emptyLabel","type":"string","required":true,"defaultValue":null,"description":"Caller-supplied message displayed when no emoji matches the search."},{"name":"loadingLabel","type":"string","required":true,"defaultValue":null,"description":"Caller-supplied message displayed while emoji data loads."},{"name":"locale","type":"string","required":false,"defaultValue":"en","description":"Emoji catalogue locale. The caller must host its data and message files. Interface labels are supplied separately."},{"name":"onEmojiSelect","type":"(emoji: string) => void","required":true,"defaultValue":null,"description":"Called with the selected Unicode emoji string. The application owns the selected value, persistence, and popup visibility."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref for the picker root div."},{"name":"searchLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name for the search input. Also supplies its placeholder unless searchPlaceholder is set."},{"name":"searchPlaceholder","type":"string","required":false,"defaultValue":"searchLabel","description":"Optional placeholder overriding the search label."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native inline styles applied to the picker root div."}]}},{"name":"ReactionButton","entryPoint":"twenty-ui/components/input","content":"---\ntitle: ReactionButton\ndescription: Toggle an emoji reaction with a count and controlled pressed state.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ReactionButtonReference from '/snippets/ui/generated/components/input/reaction-button.mdx';\n\n## Overview\n\n`ReactionButton` composes [Button](/ui/primitives/input/button) into a compact emoji reaction with a count. Your application supplies the pressed state, accessible name, and change handler.\n\n<StoryEmbed\n storyId=\"ui-components-reactionbutton--display\"\n title=\"Controlled helpful reaction with a tooltip and reset action\"\n height={160}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport {\n ReactionButton,\n type ReactionButtonProps,\n} from 'twenty-ui/components/input';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const ReactionButtonExample = ({\n emoji = '👍',\n disabled,\n loading,\n}: Partial<Pick<ReactionButtonProps, 'emoji' | 'disabled' | 'loading'>>) => {\n const [pressed, setPressed] = useState(false);\n const count = pressed ? 3 : 2;\n\n return (\n <Text\n style={{\n display: 'flex',\n flexDirection: 'column',\n gap: themeCssVariables.spacing[2],\n }}\n >\n <Text>Was this helpful?</Text>\n <Text\n render={<span />}\n style={{\n display: 'flex',\n alignItems: 'center',\n gap: themeCssVariables.spacing[1],\n }}\n >\n <Tooltip content={`${count} people found this helpful`}>\n <ReactionButton\n aria-label=\"Helpful\"\n emoji={emoji}\n count={count}\n pressed={pressed}\n onPressedChange={setPressed}\n disabled={disabled}\n loading={loading}\n />\n </Tooltip>\n <Button size=\"sm\" variant=\"ghost\" onClick={() => setPressed(false)}>\n Reset\n </Button>\n </Text>\n </Text>\n );\n};\n```\n\n## Appearance\n\nThe control is 24px tall, with rounded corners, a 16px emoji, and a small count. Pressed reactions use the theme's accent surface and text. Unpressed reactions use a transparent surface and secondary text.\n\n`count` accepts a number or a caller-formatted string. Your application owns number formatting, abbreviation, and whether to display a reaction with a zero count.\n\n<StoryEmbed\n storyId=\"ui-components-reactionbutton--catalog\"\n title=\"Reaction selection, counts, and unavailable states\"\n height={300}\n/>\n\n## State ownership\n\n`pressed` is required and controlled by your application. Activation calls `onPressedChange` with the requested next value. The component keeps showing the supplied `pressed` and `count` until your application updates them.\n\nSet `loading` while a mutation is pending to show Button's loading indicator and prevent repeated activation. It preserves the supplied `pressed` value and marks the control busy. Use `disabled` when the reaction is unavailable. Selection, counts, permissions, persistence, and any optimistic updates stay in the application.\n\nNative `onClick` runs before the change request. Calling `event.preventDefault()` in that handler cancels the request. Other native button attributes, handlers, styles, class names, and refs pass through to the button. The control always uses `type=\"button\"`.\n\n## Accessibility and tooltips\n\nProvide `aria-label` or `aria-labelledby` with a localized reaction name. Emoji and count are decorative and hidden from assistive technology, so include count or participant information in the supplied name or description when needed. Keep the reaction name stable as its state changes; `aria-pressed` communicates selection.\n\nThe native button supports Tab focus and activation with Enter or Space. Both `disabled` and `loading` prevent activation. The ref points to the native button.\n\nCompose [Tooltip](/ui/primitives/surfaces/tooltip) for participant details on hover and keyboard focus, as shown above, or pass a native `title`. Tooltip content belongs to the caller and does not replace the accessible name. Long accessible labels do not enlarge the visible control.\n\n## Props\n\n<ReactionButtonReference />\n\n<PageBanner illustration=\"page-cover-emoji\" />\n","api":{"name":"ReactionButton","entryPoint":"twenty-ui/components/input","slug":"components/input/reaction-button","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name describing the reaction. Required unless `aria-labelledby` supplies the name."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element supplying the accessible name. Can be used instead of `aria-label`."},{"name":"count","type":"string | number","required":true,"defaultValue":null,"description":"Displayed count. Pass a string for localized or abbreviated formatting. Hidden from assistive technology."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the native button and prevents activation."},{"name":"emoji","type":"string","required":true,"defaultValue":null,"description":"Emoji displayed beside the count. Hidden from assistive technology."},{"name":"loading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a loading indicator, sets `aria-busy`, and prevents activation without changing the supplied pressed state."},{"name":"onClick","type":"MouseEventHandler<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Native click handler called before `onPressedChange`. Calling `preventDefault()` cancels the change request."},{"name":"onPressedChange","type":"(pressed: boolean) => void","required":true,"defaultValue":null,"description":"Requests the next pressed state after activation. The caller updates `pressed` and `count`."},{"name":"pressed","type":"boolean","required":true,"defaultValue":null,"description":"Controlled selection state. Sets the selected appearance and `aria-pressed`."},{"name":"title","type":"string","required":false,"defaultValue":null,"description":"Optional native tooltip text supplied by the caller."}]}},{"name":"Button","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Button\ndescription: Trigger actions or navigate with styled buttons.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ButtonReference from '/snippets/ui/generated/input/button.mdx';\n\n## Overview\n\nUse `Button` for an action and supply its visible label as children. Use [IconButton](/ui/components/input/icon-button) for icon-only controls, with an accessible name from `aria-label` or `aria-labelledby`.\n\nFor recurring design defaults, use [MainButton](/ui/components/input/main-button)\nor [LightButton](/ui/components/input/light-button) from `twenty-ui/components`.\nBoth share Button's native props, refs, state, and rendering behavior.\n\n<StoryEmbed\n title=\"Button display\"\n storyId=\"ui-input-button-button--display\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveChanges = () => <Button>Save changes</Button>;\n```\n\n## Appearance\n\nCompare variants, semantic colors, sizes, and common states separately. Each group changes one choice while keeping the others fixed.\n\n<StoryEmbed\n storyId=\"ui-input-button-button--catalog\"\n title=\"Appearance for button\"\n height={630}\n/>\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { IconPlus } from 'twenty-ui/icon';\n\nexport const CreateRecord = () => (\n <Button variant=\"solid\" color=\"accent\" size=\"sm\" startIcon={<IconPlus />}>\n Create record\n </Button>\n);\n```\n\nChoose `solid`, `outline`, `soft`, `ghost`, or `link` independently of the `neutral`, `accent`, `danger`, or `success` color. Sizes are `sm` and `md`; the defaults are `outline`, `neutral`, and `md`. `fullWidth` fills the available width. `startIcon` and `endIcon` accept elements and are decorative. `elevated` adds a shadow and backdrop blur. Neutral outline buttons also gain a bordered surface with matching text and interaction colors. Other variants and semantic colors keep their existing palette. It defaults to `false` and does not change size or position. `shortcut` displays keyboard hints on larger screens; bind the shortcuts in your application.\n\nUse `color=\"inherit\"` for controls on a colored surface. The label, icons, loader, and outline border follow the surrounding text color. Interaction fills use translucent black. Outline buttons rest on a transparent surface with a 25% currentColor border and use 10% and 20% black fills on hover and press. Ghost uses transparent, 10%, and 20% black fills; soft uses 10%, 20%, and 30%. Link stays unfilled.\n\n`inherit` supports `outline`, `ghost`, `soft`, and `link`. A resolved `solid` and `inherit` combination throws a runtime error, including defaults supplied by ButtonGroup or a wrapper. `MainButton` defaults to solid, so supply a non-solid variant when inheriting color.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SurfaceActions = () => (\n <>\n <Button color=\"inherit\" variant=\"outline\">\n Save\n </Button>\n <Button color=\"inherit\" variant=\"ghost\">\n Cancel\n </Button>\n </>\n);\n```\n\n`link` uses compact text with no border or filled background. It follows its content height at either size, with a smaller font and narrower padding. Its neutral color uses stronger text on hover. The appearance does not determine semantics: use `onClick` for actions and `href` for navigation.\n\n`disabled` and `loading` prevent activation. Loading keeps the label accessible and communicates a busy state. By default, `loadingPosition=\"center\"` hides the content while preserving its layout space and centers the spinner. Set `loadingPosition` to `start` or `end` to keep children and the opposite icon visible while replacing the corresponding icon with the spinner.\n\nYour application owns progress formatting and the translated label. Pass the complete status phrase as children, for example `Installing (42%)`.\n\n<StoryEmbed\n title=\"Button loading at end\"\n storyId=\"ui-input-button-button--loading-at-end\"\n height={100}\n/>\n\n## State ownership\n\n`Button` triggers an action and does not manage a selected value, so it has no controlled or uncontrolled selection mode. Its native `value` prop supplies form data, not selection state.\n\nYour application owns `loading` and `disabled`, which default to `false`. Clicking a button does not change these props or automatically show loading while an asynchronous handler runs. Pass the current application state explicitly.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveRecordProps = { onSave: () => Promise<void> };\n\nexport const SaveRecord = ({ onSave }: SaveRecordProps) => {\n const [loading, setLoading] = useState(false);\n const [hasError, setHasError] = useState(false);\n\n const handleSave = async () => {\n setLoading(true);\n setHasError(false);\n\n try {\n await onSave();\n } catch {\n setHasError(true);\n } finally {\n setLoading(false);\n }\n };\n\n return (\n <>\n <Button loading={loading} onClick={handleSave}>\n Save record\n </Button>\n {hasError && <p role=\"alert\">Unable to save the record. Try again.</p>}\n </>\n );\n};\n```\n\nThe application starts and clears loading around the save operation. The button prevents activation while loading and becomes available again when the operation finishes, including after an error. `MainButton` and `LightButton` use the same state model.\n\n## Popup triggers\n\nCompose a popup trigger with `Button`, `LightButton`, or another Button wrapper through `render`. The trigger supplies `data-popup-open`, so the button keeps its hover background while the popup is open and uses its active background on hover or press. Each variant and color keeps its own palette. Link backgrounds remain transparent, and disabled or loading buttons keep their disabled appearance. Buttons with `aria-pressed=\"true\"` retain their existing toggle styling. Popup state does not set `aria-pressed` or represent a selected value.\n\n```tsx\nimport { LightButton } from 'twenty-ui/components/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const DetailsPopup = () => (\n <Popover.Root>\n <Popover.Trigger render={<LightButton>Show details</LightButton>} />\n <Popover.Portal>\n <Popover.Positioner>\n <Popover.Popup>\n <Popover.Title>Details</Popover.Title>\n <Popover.Description>\n More information about this record.\n </Popover.Description>\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n);\n```\n\n## Upcoming features\n\nYour application owns feature availability and its label. Compose a disabled button with `Badge` as children so the label remains part of the button's accessible name. Supply localized text from your application.\n\n```tsx\nimport { Badge } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const UpcomingAction = () => (\n <Button disabled>\n <Text\n render={<span />}\n style={{\n display: 'inline-flex',\n alignItems: 'center',\n gap: 'var(--t-spacing-1)',\n }}\n >\n Upcoming action\n <Badge>Coming soon</Badge>\n </Text>\n </Button>\n);\n```\n\nThis composition also works with `MainButton` and `LightButton`. It replaces the removed `soon` and `soonLabel` props.\n\n## Animated icons\n\nCompose `Button` with `AnimatedIconCrossfade` to change its icon when application state changes. Pass the animated element to `startIcon` and the label as children.\n\n```tsx\nimport { useState } from 'react';\nimport { IconPencil, IconX } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AnimatedIconCrossfade } from 'twenty-ui/components/layout';\n\nexport const EditActions = () => {\n const [isEditing, setIsEditing] = useState(false);\n\n return (\n <Button\n size=\"sm\"\n aria-expanded={isEditing}\n onClick={() => setIsEditing(!isEditing)}\n startIcon={\n <AnimatedIconCrossfade\n isActive={isEditing}\n activeIcon={<IconX size={14} />}\n inactiveIcon={<IconPencil size={14} />}\n />\n }\n >\n Edit actions\n </Button>\n );\n};\n```\n\nWhen an icon is itself an action, use `IconButton` or `LightIconButton` and animate its icon content. When a disclosure header owns expansion, keep its chevron decorative and expose `aria-expanded` on the header control. Keep animation styles with the feature and respect `prefers-reduced-motion`.\n\n<StoryEmbed\n title=\"Button with an animated icon\"\n storyId=\"ui-components-layout-animatediconcrossfade--display\"\n height={100}\n/>\n\n## Links and forms\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DocumentationLink = () => (\n <Button\n variant=\"link\"\n href=\"https://twenty.com\"\n target=\"_blank\"\n rel=\"noreferrer\"\n hrefLang=\"en\"\n referrerPolicy=\"no-referrer\"\n >\n Read documentation\n </Button>\n);\n```\n\nWithout a custom `render`, `href` renders an anchor with link semantics, unless you explicitly set `nativeButton` to `true`. Native anchor attributes such as `download`, `hrefLang`, `ping`, and `referrerPolicy` reach the anchor. Props shared with native buttons retain their Base UI types. To supply an anchor MIME type, put it on the renderer, for example `render={<a href=\"/records.csv\" type=\"text/csv\">Download records</a>}` with `nativeButton={false}` and `role=\"link\"`. Disabled and loading links cannot activate.\n\nUse `render` to compose another element or a router link. `nativeButton` describes the rendered element and defaults to `true` for custom renderers. Set `nativeButton={false}` and `role=\"link\"` for a navigation anchor. The anchor or router component can own its destination without a `Button` `href`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const RecordsLink = () => (\n <Button nativeButton={false} role=\"link\" render={<a href=\"/records\" />}>\n Open records\n </Button>\n);\n```\n\nFor a custom native `<button>`, keep `nativeButton` true. For a non-native action element such as a `<div>`, use `nativeButton={false}`; Base UI supplies button keyboard behavior. An explicit `nativeButton` or `role` is preserved even when `href` is also supplied.\n\nButtons default to `type=\"button\"`. Set `type=\"submit\"` or `type=\"reset\"` explicitly for forms. Native attributes, event handlers, event details, and refs reach the rendered root. A ref receives the actual button, anchor, or custom root element. Keyboard handlers retain Base UI event methods, including `preventBaseUIHandler()` to cancel its built-in keyboard action. Base UI's render callback receives both root props and the current disabled state; spread the props onto your root to retain composition behavior.\n\n## Group defaults\n\n[ButtonGroup](/ui/primitives/input/button-group) supplies a shared variant, color, and size. An explicit prop on a child takes precedence over the group default. When neither sets a prop, the component default applies.\n\n## Migration from ClickToActionLink\n\nImport `Button` from `twenty-ui/primitives/input` and replace `ClickToActionLink` with `Button variant=\"link\"`. Keep `href`, `target`, and `rel` for navigation. Actions without `href` now render a native button with keyboard activation. Native attributes, events, and refs pass through to the root.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype LogOutProps = { onLogOut: () => void };\n\nexport const LogOut = ({ onLogOut }: LogOutProps) => (\n <Button variant=\"link\" onClick={onLogOut}>\n Log out\n </Button>\n);\n```\n\n## Props\n\n<ButtonReference />\n\nPass `shortcut={['Mod', 'Enter']}` for simultaneous keys or `shortcut={[['G'], ['P']]}` for successive presses. See [Shortcut](/ui/primitives/typography/shortcut) for nested combinations and the shared string formatter.\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"Button","entryPoint":"twenty-ui/primitives/input","slug":"input/button","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":"neutral","description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":"false","description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true (false for the built-in href anchor)","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Button height: `sm` (24px) or `md` (32px). The `link` variant uses its content height at either size."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"outline","description":"Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics."}]}},{"name":"ButtonGroup","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: ButtonGroup\ndescription: Group related buttons with shared appearance and an optional frame.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ButtonGroupReference from '/snippets/ui/generated/input/button-group.mdx';\n\n## Overview\n\nGive a group an accessible name and place related buttons inside it. The group joins adjacent borders and can apply defaults for size, variant, and color. Buttons retain their own tab stops.\n\n<StoryEmbed\n storyId=\"ui-input-button-buttongroup--display\"\n title=\"Button group\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { IconCheckbox, IconNotes, IconTimelineEvent } from 'twenty-ui/icon';\nimport { Button, ButtonGroup } from 'twenty-ui/primitives/input';\n\nexport const ActivityActions = () => (\n <ButtonGroup aria-label=\"Create activity\" size=\"sm\">\n <Button startIcon={<IconNotes />}>Note</Button>\n <Button startIcon={<IconCheckbox />}>Task</Button>\n <Button startIcon={<IconTimelineEvent />}>Activity</Button>\n </ButtonGroup>\n);\n```\n\n## State ownership\n\n`ButtonGroup` coordinates appearance, not selection. It has no controlled or uncontrolled selection mode. Each button receives its own action handler and application state; see [Button's state ownership example](/ui/primitives/input/button#state-ownership) for loading behavior.\n\nFor a mutually exclusive choice, use [RadioGroup](/ui/primitives/input/radio-group), which owns selection for its radio controls.\n\n## Appearance precedence\n\nEach appearance prop resolves independently: the child's explicit prop, then the group default, then the component default. This applies to both Button and IconButton, including an explicit `IconButton size=\"xs\"`. Defaults reach children through fragments, wrappers, and tooltip anchors.\n\nA group can supply `color=\"inherit\"` on a colored surface. A child that resolves to inherited color must also resolve to a non-solid variant. Explicit child color and variant overrides take precedence, so a child may choose a non-solid variant or a semantic color when the group supplies solid and inherit together.\n\nKeep attached buttons at the same size so their edges align. This example overrides variant and color while inheriting the group size.\n\n```tsx\nimport { Button, ButtonGroup } from 'twenty-ui/primitives/input';\n\nexport const ActivityActions = () => (\n <ButtonGroup\n aria-label=\"Activity actions\"\n variant=\"solid\"\n color=\"accent\"\n size=\"sm\"\n >\n <Button variant=\"ghost\" color=\"danger\">\n Delete activity\n </Button>\n <Button color=\"neutral\">Duplicate activity</Button>\n <Button>New activity</Button>\n </ButtonGroup>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-input-button-buttongroup--appearance-overrides\"\n title=\"Individual appearance in a button group\"\n height={100}\n/>\n\n## Detached controls\n\nSet `attached={false}` to keep each control's rounded corners and a 2px gap. Group defaults still apply through wrappers and tooltip anchors; explicit child props take precedence.\n\n## Framed controls\n\nSet `framed` to add a translucent background, border, 2px padding, and concentric corners. The frame works with attached or detached controls and preserves explicit child appearance. Use `size=\"xs\"` on [IconButton](/ui/components/input/icon-button) for compact 20px actions.\n\n<StoryEmbed\n storyId=\"ui-components-iconbutton--framed-group-documentation\"\n title=\"Framed button group\"\n height={100}\n/>\n\n```tsx\nimport { IconButton } from 'twenty-ui/components/input';\nimport { IconPlus, IconTrash } from 'twenty-ui/icon';\nimport { ButtonGroup } from 'twenty-ui/primitives/input';\n\nexport const CompactRecordActions = () => (\n <ButtonGroup framed attached={false} aria-label=\"Record actions\">\n <IconButton size=\"xs\" aria-label=\"Add\" variant=\"ghost\">\n <IconPlus />\n </IconButton>\n <IconButton size=\"xs\" aria-label=\"Delete\" variant=\"ghost\" disabled>\n <IconTrash />\n </IconButton>\n </ButtonGroup>\n);\n```\n\n## Updating existing groups\n\nReplace `IconButtonGroup` and its `iconButtons` array with `ButtonGroup framed attached={false}` and explicit children. Replace `InsideButton` with `LightIconButton size=\"xs\"`. Each button owns its accessible name, action handler, disabled state, and optional tooltip.\n\n## Props\n\n<ButtonGroupReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"ButtonGroup","entryPoint":"twenty-ui/primitives/input","slug":"input/button-group","props":[{"name":"attached","type":"boolean","required":false,"defaultValue":"true","description":"Join adjacent controls. Set to false for independently rounded buttons with a 2px gap."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Default semantic color for children without an explicit color. Inherited color requires each child to resolve to a non-solid variant; explicit child overrides take precedence."},{"name":"framed","type":"boolean","required":false,"defaultValue":"false","description":"Add a translucent frame with padding and concentric corners. Button sizes and appearance remain independent unless set on the group."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Default button height for children without an explicit size."},{"name":"variant","type":"\"ghost\" | \"link\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":null,"description":"Default surface treatment for children without an explicit variant."}]}},{"name":"Field","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Field\ndescription: Connect a form control to its label, description, and validation feedback.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport FieldReference from '/snippets/ui/generated/input/field.mdx';\n\n## Overview\n\nUse `Field` to group one control with its accessible label and helper text. Components such as [Input](/ui/primitives/input/input) integrate with the field directly.\n\n<StoryEmbed\n storyId=\"ui-input-field--display\"\n title=\"Field example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => (\n <Field.Root name=\"email\" validationMode=\"onBlur\">\n <Field.Label>Work email</Field.Label>\n <Input type=\"email\" required placeholder=\"[email protected]\" />\n <Field.Description>\n We send account updates to this address.\n </Field.Description>\n <Field.Error match=\"valueMissing\">Enter your email address.</Field.Error>\n <Field.Error match=\"typeMismatch\">Enter a valid email address.</Field.Error>\n </Field.Root>\n);\n```\n\n`Field.Root` manages the control's name, disabled state, and validity. `Field.Label` and `Field.Description` connect their content to the control. Set validation timing with `validationMode`; use `validate` for custom validation.\n\n## Anatomy\n\nPlace one control and its supporting parts inside `Field.Root`. This tree shows a field built with the styled `Input` component.\n\n```text\nField.Root\n├── Field.Label\n├── Input\n├── Field.Description\n└── Field.Error\n```\n\n| Part | Requirement | Purpose |\n| ------------------------------------- | ------------------- | ---------------------------------------------------------------------------- |\n| `Root` | Required | Shares the name, disabled state, and validation with the control. |\n| `Item` | Optional for groups | Associates each radio or checkbox with its own label and description. |\n| `Label` | Recommended | Supplies a visible, associated label. An accessible name is always required. |\n| `Input` or another integrated control | Required | Receives user input and connects to the field. |\n| `Control` | Alternative control | Provides an unstyled input when you do not use an integrated control. |\n| `Description` | Optional | Adds persistent helper text associated with the control. |\n| `Error` | Optional | Shows feedback for a matching validation state. |\n| `Validity` | Optional | Exposes validity through a children render function. |\n\n`Input` and `Textarea` already integrate with the field. Place them directly inside `Root`; they supply the control behavior themselves. Compound controls such as [Select](/ui/primitives/input/select#compose-with-a-field) keep their own root and parts inside the field.\n\n## External errors\n\nUse `invalid` when your application owns the error state. An explicit `match` makes the error message visible.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\ntype UsernameFieldProps = { error?: string };\n\nexport const UsernameField = ({ error }: UsernameFieldProps) => (\n <Field.Root name=\"username\" invalid={Boolean(error)}>\n <Field.Label>Username</Field.Label>\n <Input autoComplete=\"username\" />\n <Field.Error match={Boolean(error)}>{error}</Field.Error>\n </Field.Root>\n);\n```\n\nKeep error messages actionable and provide a visible label even when the control has a placeholder.\n\n## Grouped controls\n\nUse `Field.Item` inside a radio or checkbox group to associate each choice with its own label and description. Keep the group's label outside the items. An item can be disabled independently; a disabled `Field.Root` disables every item.\n\n<StoryEmbed\n storyId=\"ui-input-field--grouped-items\"\n title=\"Field items\"\n height={220}\n/>\n\n```tsx\nimport { Field, Radio, RadioGroup } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const NotificationsField = () => (\n <Field.Root name=\"notifications\">\n <Field.Label>Notifications</Field.Label>\n <RadioGroup defaultValue=\"important\" style={{ gap: 16, marginTop: 12 }}>\n <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>\n <Radio value=\"important\" />\n <Text>\n <Field.Label>Important updates</Field.Label>\n <Field.Description>\n Only messages that need your attention\n </Field.Description>\n </Text>\n </Field.Item>\n <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>\n <Radio value=\"all\" />\n <Text>\n <Field.Label>All updates</Field.Label>\n <Field.Description>Every change to your records</Field.Description>\n </Text>\n </Field.Item>\n <Field.Item\n disabled\n style={{ display: 'flex', alignItems: 'start', gap: 12 }}\n >\n <Radio value=\"digest\" />\n <Text>\n <Field.Label>Daily digest</Field.Label>\n <Field.Description>Coming soon</Field.Description>\n </Text>\n </Field.Item>\n </RadioGroup>\n </Field.Root>\n);\n```\n\n## Native integration and types\n\nField preserves Base UI validation timing, custom validation, controlled and uncontrolled control values, and value-change event details. `Validity` exposes the validation result through its children function. Integrated controls retain their native form behavior.\n\n`Root`, `Item`, `Label`, `Control`, `Description`, and `Error` forward native props, refs, and `render` composition. Their default elements are a div, div, label, input, paragraph, and div respectively. `Validity` does not render its own element.\n\nImport `FieldRootProps`, `FieldItemProps`, `FieldLabelProps`, `FieldControlProps`, `FieldDescriptionProps`, `FieldErrorProps`, and `FieldValidityProps` from `twenty-ui/primitives/input` for the corresponding upstream part contracts.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<FieldReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Field","entryPoint":"twenty-ui/primitives/input","slug":"input/field","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<FieldRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `validate`: Validates the field when called."},{"name":"className","type":"string | ((state: FieldRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"dirty","type":"boolean","required":false,"defaultValue":null,"description":"Whether the field's value has been changed from its initial value.\nUseful when the field state is controlled by an external library."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction.\nTakes precedence over the `disabled` prop on the `<Field.Control>` component."},{"name":"invalid","type":"boolean","required":false,"defaultValue":null,"description":"Whether the field is invalid.\nUseful when the field state is controlled by an external library."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted.\nTakes precedence over the `name` prop on the `<Field.Control>` component."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"touched","type":"boolean","required":false,"defaultValue":null,"description":"Whether the field has been touched.\nUseful when the field state is controlled by an external library."},{"name":"validate","type":"((value: unknown, formValues: Record<string, any>) => string | void | string[] | Promise<string | void | string[] | null> | null)","required":false,"defaultValue":null,"description":"A function for custom validation. Return a string or an array of strings with\nthe error message(s) if the value is invalid. Returning nothing, `null`, an empty\nstring, or an empty array means the value is valid.\nAsynchronous functions are supported, but they do not prevent form submission\nwhen using `validationMode=\"onSubmit\"`."},{"name":"validationDebounceTime","type":"number","required":false,"defaultValue":"0","description":"How long to wait between `validate` callbacks if\n`validationMode=\"onChange\"` is used. Specified in milliseconds."},{"name":"validationMode","type":"\"onBlur\" | \"onChange\" | \"onSubmit\"","required":false,"defaultValue":"onSubmit","description":"Determines when the field should be validated.\nThis takes precedence over the `validationMode` prop on `<Form>`.\n\n- `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission.\n- `onBlur`: triggers validation when the control loses focus.\n- `onChange`: triggers validation on every change to the control value."}]},{"name":"Item","props":[{"name":"className","type":"string | ((state: FieldItemState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the wrapped control should ignore user interaction.\nThe `disabled` prop on `<Field.Root>` takes precedence over this."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldItemState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldItemState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Label","props":[{"name":"className","type":"string | ((state: FieldLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeLabel","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<label>` element when replacing it via the `render` prop.\nSet to `false` if the rendered element is not a label (for example, `<div>`).\n\nThis is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldLabelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Control","props":[{"name":"className","type":"string | ((state: FieldControlState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Callback fired when the `value` changes. Use when controlled."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldControlState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldControlState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: FieldDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Error","props":[{"name":"className","type":"string | ((state: FieldErrorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"match","type":"boolean | keyof ValidityState","required":false,"defaultValue":null,"description":"Determines whether to show the error message according to the field's\n[ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState).\nSpecifying `true` will always show the error message, and lets external libraries\ncontrol the visibility."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldErrorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldErrorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Validity","props":[{"name":"children","type":"(state: FieldValidityState) => ReactNode","required":true,"defaultValue":null,"description":"A function that accepts the field validity state as an argument.\n\n```jsx\n<Field.Validity>\n {(validity) => {\n return <div>...</div>\n }}\n</Field.Validity>\n```"}]}]}},{"name":"Input","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Input\ndescription: A text input with native attributes, field integration, and two sizes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport InputReference from '/snippets/ui/generated/input/input.mdx';\n\n## Overview\n\n`Input` renders a text input and accepts native input attributes such as `type`, `name`, `required`, `disabled`, and `autoComplete`.\n\n<StoryEmbed\n storyId=\"ui-input-input--display\"\n title=\"Input example\"\n height={140}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial email address. The input owns subsequent changes.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => (\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input\n name=\"email\"\n type=\"email\"\n autoComplete=\"email\"\n defaultValue=\"[email protected]\"\n />\n <Field.Description>Use your work email address.</Field.Description>\n </Field.Root>\n);\n```\n\n## Visual choices\n\nCompare small and medium inputs in their default, focused, invalid, and disabled states. Use validation feedback alongside invalid styling.\n\n<StoryEmbed\n storyId=\"ui-input-input--catalog\"\n title=\"Visual choices for input\"\n height={380}\n/>\n\n## Plain appearance\n\nUse `variant=\"plain\"` inside an existing row or surface. It removes the fill, border, rounded corners and padding and uses natural height. The parent supplies spacing and row dimensions. Text, placeholder and disabled styling remain shared. The blue outline follows the browser's native `:focus-visible` behavior. For text controls this can include pointer focus and autofocus as well as keyboard focus. Invalid state uses a danger outline without changing layout.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const InlineSubject = () => (\n <Field.Root>\n <Field.Label>Subject</Field.Label>\n <Input variant=\"plain\" placeholder=\"Add a subject\" />\n </Field.Root>\n);\n```\n\n`InputGroup` automatically gives its input the plain appearance and keeps the group as the only focus and validation frame. Its `sm` and `md` heights remain 24px and 32px. Standalone plain inputs do not use the fixed height associated with `size`.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same email address in React state. The callback receives the next string value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => {\n const [email, setEmail] = useState('[email protected]');\n\n return (\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input\n name=\"email\"\n type=\"email\"\n autoComplete=\"email\"\n value={email}\n onValueChange={setEmail}\n />\n <Field.Description>Use your work email address.</Field.Description>\n </Field.Root>\n );\n};\n```\n\n## Add an adornment\n\n`InputGroup` owns the surrounding border and layout height. Input size resolves from the explicit child `size`, then the group default, then `md`. The grouped input stretches within the shared border, so use the group's `size` to change the overall field height.\n\n```tsx\nimport { IconSearch } from 'twenty-ui/icon';\nimport { Input, InputGroup } from 'twenty-ui/primitives/input';\n\nexport const CompactSearch = () => (\n <InputGroup size=\"sm\" startElement={<IconSearch size={16} aria-hidden />}>\n <Input aria-label=\"Search contacts\" />\n </InputGroup>\n);\n```\n\n## Native control and wrapper customization\n\nNative attributes, handlers, `className`, `style`, and `ref` target the input. The ref receives an `HTMLInputElement`. Use `render` to compose another input component and forward the supplied props and ref to its native input.\n\n`onChange` receives a React change event for the native input. `onValueChange(value, details)` receives the next string and Base UI event details, including `event`, `reason`, `cancel`, and `allowPropagation`. The event targets the input. Canceling the details preserves Base UI's validation policy; it does not undo a native edit. Controlled callers decide which value to commit.\n\nPut layout styles, attributes, and refs on `InputGroup` when customizing the surrounding wrapper. The group owns no value. Native `name`, `form`, `required`, `readOnly`, `disabled`, submission, and reset behavior remain on the input, with Field naming and validation supplied through `Field.Root`.\n\n## Props\n\nThe reference includes component-specific and inherited Base UI props. Native input attributes are also accepted. A standalone input defaults to `md`; inside a group, an omitted input `size` inherits the group's size.\n\n<InputReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Input","entryPoint":"twenty-ui/primitives/input","slug":"input/input","props":[{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"true","description":"Set false to hide the focus border or outline while keeping errors visible. Defaults to true. InputGroup controls grouped focus styling."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Receives the next string value and Base UI details, including the native event, reason and cancellation methods."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the native input element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, InputState>","required":false,"defaultValue":null,"description":"Composes the native input with a custom element or render callback. Forward the supplied props and ref to an input."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Visual size. Explicit input size takes precedence over the InputGroup default, then md applies. Group layout still sets the surrounding height."},{"name":"style","type":"CSSProperties | ((state: InputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"textAlign","type":"\"end\" | \"start\"","required":false,"defaultValue":null,"description":"Aligns text to the logical start or end of the input. Follows the text direction."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The value of the input. Use when controlled."},{"name":"variant","type":"\"default\" | \"plain\"","required":false,"defaultValue":"default","description":"default keeps the field frame. plain removes fill, border, radius and padding and uses natural height. Its outline follows native :focus-visible, including pointer focus or autofocus on text inputs; invalid state uses a danger outline. InputGroup always owns the grouped frame."}]}},{"name":"InputGroup","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: InputGroup\ndescription: Add prefixes, suffixes, and actions around a text input.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport InputGroupReference from '/snippets/ui/generated/input/input-group.mdx';\n\n## Overview\n\n`InputGroup` gives an [Input](/ui/primitives/input/input) a shared border and optional leading or trailing content. Set `size` on the group to size the container and provide a default for its input. Explicit child size takes precedence over that default; the group still controls the shared layout height.\n\n<StoryEmbed\n storyId=\"ui-input-inputgroup--display\"\n title=\"InputGroup example\"\n height={140}\n/>\n\n## Usage\n\n```tsx\nimport { Field, Input, InputGroup } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const WebsiteField = () => (\n <Field.Root name=\"website\">\n <Field.Label>Website</Field.Label>\n <InputGroup\n startElement={\n <Text render={<span />} aria-hidden>\n https://\n </Text>\n }\n >\n <Input placeholder=\"example.com\" />\n </InputGroup>\n <Field.Description>Enter the domain without https://.</Field.Description>\n </Field.Root>\n);\n```\n\n`startElement` and `endElement` accept React nodes. Prefixes and suffixes are visual content; the input's submitted value contains only what the user enters.\n\n## Visual choices\n\nCompare prefix, suffix, and combined adornments at both input sizes. The group shares its size with the input.\n\n<StoryEmbed\n storyId=\"ui-input-inputgroup--catalog\"\n title=\"Visual choices for input group\"\n height={300}\n/>\n\n## Anatomy\n\nPlace the input inside `InputGroup` and keep field labels and messages outside the shared border.\n\n```text\nField.Root\n├── Field.Label\n├── InputGroup\n│ └── Input\n└── Field.Description\n```\n\n| Part or slot | Requirement | Purpose |\n| --------------------------------------------- | -------------------- | ------------------------------------------------------------------------ |\n| `InputGroup` | Required | Supplies the shared border, layout, and size. |\n| `Input` as `children` | Required | Owns the input value, native attributes, and editing behavior. |\n| `startElement` | Optional prop | Adds a prefix, icon, or other content before the input. |\n| `endElement` | Optional prop | Adds a suffix or action after the input. |\n| `Field.Root`, `Label`, `Description`, `Error` | Optional composition | Associates a label, helper text, and validation feedback with the input. |\n\n`startElement` and `endElement` are React node props, not separate components. `InputGroup` does not supply a label or manage validation. Give the input an accessible name, either through `Field.Label` or its own labeling attributes.\n\n## Trailing action\n\n```tsx\nimport { useState } from 'react';\nimport { Button, Field, Input, InputGroup } from 'twenty-ui/primitives/input';\n\nexport const PasswordField = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <Field.Root name=\"password\">\n <Field.Label>Password</Field.Label>\n <InputGroup\n endElement={\n <Button\n type=\"button\"\n aria-label={visible ? 'Hide password' : 'Show password'}\n variant=\"ghost\"\n size=\"sm\"\n onClick={() => setVisible(!visible)}\n >\n {visible ? 'Hide' : 'Show'}\n </Button>\n }\n >\n <Input\n type={visible ? 'text' : 'password'}\n autoComplete=\"current-password\"\n />\n </InputGroup>\n </Field.Root>\n );\n};\n```\n\nPut labels, validation, and value handling on the field or input. Give adornment buttons their own accessible names and use `type=\"button\"` when they should not submit the form. The group supports `sm` and `md` sizes and defaults to `md`.\n\n## Customize the layout\n\nNative props, `className`, `style`, `render`, and `ref` target the layout div. A custom `render` element receives the layout props and children. Keep the supplied ref on that layout element.\n\nPut `value`, `defaultValue`, `onValueChange`, `name`, `required`, `readOnly`, `disabled`, and the native control ref on `Input`. The group does not manage input state or replace Field label association.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<InputGroupReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"InputGroup","entryPoint":"twenty-ui/primitives/input","slug":"input/input-group","props":[{"name":"endElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered after the input, such as a suffix or a button."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"true","description":"Set false to keep the group border unchanged on focus. Defaults to true. Error styling remains visible."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the layout element, a div by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the layout element. Forward its props, children and ref. Native control props belong on the child input."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the layout and default size for inputs that omit size. Defaults to md."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered before the input, such as a prefix or an icon."}]}},{"name":"NumberField","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: NumberField\ndescription: Compose a numeric field with locale formatting, stepping, native forms, and scrubbing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport NumberFieldReference from '/snippets/ui/generated/input/number-field.mdx';\n\n## Overview\n\n`NumberField` exposes all seven parts of the installed Base UI Number Field: `Root`, `Group`, `Input`, `Decrement`, `Increment`, `ScrubArea`, and `ScrubAreaCursor`. Import it from `twenty-ui/primitives/input`. It retains Base UI's numeric state, formatting, stepping, event details, and native form integration with Twenty UI styling for the input, group, and adjustment controls.\n\nFor the compact preset with fixed formatting and modifier-step defaults, use [NumberStepper](/ui/components/input/number-stepper) from `twenty-ui/components/input`.\n\n<StoryEmbed\n storyId=\"ui-input-numberfield--display\"\n title=\"NumberField example\"\n height={140}\n/>\n\n## Usage\n\n`Root` owns numeric state. `Input` is the visible text input. Use `Group` to arrange optional decrement and increment controls around it. Supply content and accessible names for the controls; the primitive does not inject icons or labels.\n\n```tsx\nimport { IconMinus, IconPlus } from 'twenty-ui/icon';\nimport { Field, NumberField } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => (\n <Field.Root>\n <Field.Label>Quantity</Field.Label>\n <NumberField.Root name=\"quantity\" defaultValue={3} min={0} max={10}>\n <NumberField.Group>\n <NumberField.Decrement aria-label=\"Decrease quantity\">\n <IconMinus size={16} />\n </NumberField.Decrement>\n <NumberField.Input />\n <NumberField.Increment aria-label=\"Increase quantity\">\n <IconPlus size={16} />\n </NumberField.Increment>\n </NumberField.Group>\n </NumberField.Root>\n <Field.Description>Choose up to ten items.</Field.Description>\n </Field.Root>\n);\n```\n\n`Field.Label`, `Field.Description`, and `Field.Error` associate with the visible input. Alternatively, pass `aria-label` or `aria-labelledby` to `Input`. The default `aria-roledescription` is `Number field`; it does not provide an accessible name.\n\n## Values and callbacks\n\nOmit `value` for an uncontrolled field, and supply a numeric `defaultValue` when an initial value is needed. Omitting `defaultValue` starts empty. For a controlled field, pass a number or `null` through `value` and update it from `onValueChange`.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, NumberField } from 'twenty-ui/primitives/input';\n\nexport const PriceInput = () => {\n const [price, setPrice] = useState<number | null>(null);\n const [savedPrice, setSavedPrice] = useState<number | null>(null);\n\n return (\n <Field.Root>\n <Field.Label>Price</Field.Label>\n <NumberField.Root\n value={price}\n onValueChange={setPrice}\n onValueCommitted={setSavedPrice}\n >\n <NumberField.Input placeholder=\"Enter a price\" />\n </NumberField.Root>\n <Field.Description>\n Last committed price: {savedPrice ?? 'empty'}\n </Field.Description>\n </Field.Root>\n );\n};\n```\n\nClearing reports `null`, including when `min` is set. Incomplete drafts such as `-` remain editable without reporting an invalid number. Parseable typing updates the numeric value before the edit is committed. The first step from an empty value starts at zero clamped to the bounds; subsequent steps use the active step amount.\n\n`onValueChange(value, details)` retains the native `event`, `reason`, `cancel`, `allowPropagation`, `isCanceled`, `isPropagationAllowed`, `trigger`, and optional `direction`. Reasons distinguish typing (`input-change`), clearing (`input-clear`), blur normalization (`input-blur`), paste (`input-paste`), keyboard, increment or decrement presses, wheel, scrubbing, and native autofill (`none`). Calling `cancel()` prevents the numeric state update; controlled callers still choose their accepted value.\n\n`onValueCommitted(value, details)` runs on blur after editing, on pointer release after stepping or scrubbing, and immediately for keyboard and wheel adjustments. Clearing commits `null` on blur. Commit details contain `event` and `reason`; they are generic details without change cancellation methods. Focusing and blurring an untouched field does not itself commit a value when no numeric normalization is needed. Explicit rounding options can normalize and commit an untouched value.\n\n## Locale and formatting\n\nSet `locale` and `format` on `Root`. They retain the installed Base UI contract: `locale` accepts `Intl.LocalesArgument`, and `format` accepts `Intl.NumberFormatOptions`. Display formatting is separate from the raw numeric value submitted by the form. The primitive does not force Latin digits, grouping, precision, or modifier steps.\n\n<StoryEmbed\n storyId=\"ui-input-numberfield--locale-currency\"\n title=\"Locale and currency formatting\"\n height={140}\n/>\n\n```tsx\nimport { Field, NumberField } from 'twenty-ui/primitives/input';\n\nexport const AmountInput = () => (\n <Field.Root>\n <Field.Label>Amount in euros</Field.Label>\n <NumberField.Root\n name=\"amount\"\n defaultValue={1234.5}\n locale=\"de-DE\"\n format={{ style: 'currency', currency: 'EUR' }}\n step={0.5}\n smallStep={0.01}\n largeStep={10}\n >\n <NumberField.Input />\n </NumberField.Root>\n </Field.Root>\n);\n```\n\nTyping and paste use the configured locale and supported format symbols. Blur normalizes the displayed text. Explicit precision or rounding options can also normalize the committed number; without those options, formatting alone does not replace an untouched numeric value with rounded display text.\n\n## Stepping and bounds\n\n`step` defaults to `1`, `smallStep` to `0.1` while Alt is held, and `largeStep` to `10` while Shift is held. The active step applies to buttons, Arrow Up and Arrow Down, wheel, and scrub-area movement. `snapOnStep` defaults to `false`; enable it to snap adjustments to the active step. Home and End select the corresponding explicit bound. Native key handlers can call `event.preventBaseUIHandler()` when the owner needs to override Base UI's keyboard behavior.\n\n`min` and `max` are inclusive. Step interactions stay bounded. By default, typed and pasted values also clamp numerically, with the draft normalized on blur. Set `allowOutOfRange` to accept direct edits outside those bounds and let native range validation or application validation report the problem.\n\n`step=\"any\"` disables native step validation while interactive stepping uses `1` and the configured modifier steps. With a numeric step, provide `min` explicitly when native submission must validate step alignment. The numeric step does not round every typed value to a step.\n\n## Scrubbing\n\n`ScrubArea` changes the numeric value as the pointer moves. It supports horizontal or vertical movement, `pixelSensitivity`, and optional `teleportDistance`. The active step and bounds also apply to scrubbing. Use a visible label as the scrub target while keeping the input available for keyboard editing.\n\n<StoryEmbed\n storyId=\"ui-input-numberfield--with-scrubbing\"\n title=\"Scrub the width label\"\n height={150}\n/>\n\nCompose `ScrubAreaCursor` inside `ScrubArea` for a custom cursor during pointer-lock scrubbing. It portals to the document body while active. Base UI falls back to the normal cursor for touch input, denied pointer lock, and WebKit. Set `allowWheelScrub` on `Root` to allow wheel adjustment while the input is focused and hovered; it defaults to `false`.\n\n## Forms and disabled state\n\n`Root` renders a hidden native `input type=\"number\"` for raw numeric submission and native validation. Set `name`, `form`, `required`, `min`, `max`, and `step` on `Root`. `form` can associate the field with a form elsewhere in the document. The default adjustment controls use `type=\"button\"`, so stepping does not submit the form.\n\n`disabled` prevents interaction and excludes the value from submission. `readOnly` prevents changes while keeping the visible input focusable and its form value available. Use a controlled value when the application must reset numeric state; native form reset does not reset it.\n\n## DOM targets and customization\n\n| Part or prop | Default DOM and ref target |\n| ------------------------- | ------------------------------------------------------------------------------ |\n| `Root` / `Root.ref` | The outer `div` |\n| `Root.inputRef` | The hidden native number input |\n| `Root.id` | Associates the visible text input's ID |\n| `Group` / `Group.ref` | The group `div` |\n| `Input` / `Input.ref` | The visible `input type=\"text\"` |\n| `Decrement` / `Increment` | Native buttons |\n| `ScrubArea` | A `span` |\n| `ScrubAreaCursor` | A `span` portaled to the document body while active; its ref is otherwise null |\n\nNative attributes, `className`, `style`, and `render` target the part receiving them. Input customization applies to the visible control; wrapper customization belongs on `Root` or `Group`. To focus the control, use `Input.ref`, rather than `Root.inputRef`.\n\nEach part accepts an element or callback through `render`, with the corresponding public state type. Forward the supplied props and ref to the appropriate DOM element so editing, focus, labels, and validation keep working. When a stepping control renders a non-button element, set `nativeButton={false}`. `className` and `style` also accept state callbacks. State includes numeric `value`, formatted `inputValue`, `required`, `disabled`, `readOnly`, `scrubbing`, and inherited Field state.\n\nThe public entry points export the props and state type for every part, plus `NumberFieldRootChangeEventDetails`, `NumberFieldRootChangeEventReason`, `NumberFieldRootCommitEventDetails`, and `NumberFieldRootCommitEventReason`.\n\n## Front component renderer\n\nReact and Preact sandbox fixtures verify initial locale formatting, localized paste, raw numeric form values, accessible labels, refs, render composition, blur commits, keyboard change and commit details, and pointer change details.\n\nSequential typing after clearing a controlled localized field currently resets the caret in the renderer: typing `2` and then `3` can produce `32`. A formatted pointer adjustment can also race with blur and leave the visible input showing the previous value. Pointer adjustments report changes, but pointer release does not deliver the corresponding commit callback; later blur can commit with `input-blur` instead. Dragging the scrub area and using its custom cursor are also unavailable in the sandbox. These limitations do not affect ordinary React hosts.\n\n## Props\n\nThe reference is generated from the installed public component types. Native attributes and event handlers are also accepted on parts that render elements.\n\n<NumberFieldReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"NumberField","entryPoint":"twenty-ui/primitives/input","slug":"input/number-field","props":[],"parts":[{"name":"Root","props":[{"name":"allowOutOfRange","type":"boolean","required":false,"defaultValue":"false","description":"Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded."},{"name":"allowWheelScrub","type":"boolean","required":false,"defaultValue":"false","description":"Allows wheel adjustments while the visible input is focused and hovered. Defaults to false."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Composed NumberField parts and supporting content."},{"name":"className","type":"string | ((state: NumberFieldRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"defaultValue","type":"number","required":false,"defaultValue":"empty","description":"Initial uncontrolled number. Omit to start empty; the public type accepts a number."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Prevents interaction and excludes the value from form submission."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"ID of the form owning the hidden native number input."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Intl.NumberFormat options for display and parsing, including currency, units, percent, grouping, and precision. Explicit rounding options can normalize the committed value on blur."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID associated with the visible input. Generated when omitted."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the hidden native number input used for submission and validation. Use Input.ref to focus the visible text input."},{"name":"largeStep","type":"number","required":false,"defaultValue":"10","description":"Amount used while Shift is held. Defaults to 10."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"Locale or locale list used to format and parse numbers. Defaults to the runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":null,"description":"Inclusive maximum for stepping and native range validation."},{"name":"min","type":"number","required":false,"defaultValue":null,"description":"Inclusive minimum for stepping and native range validation."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name of the raw numeric value submitted by the hidden input."},{"name":"onValueChange","type":"((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the next number or null and change details with the native event, reason, cancellation and propagation methods, and optional stepping direction."},{"name":"onValueCommitted","type":"((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the committed number or null and generic details containing event and reason. Typing commits on blur; pointer steps and scrubbing commit on release; keyboard and wheel changes commit immediately."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Prevents changes while keeping the visible input focusable."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element composed through Root.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldRootState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Requires a numeric value for native form submission."},{"name":"smallStep","type":"number","required":false,"defaultValue":"0.1","description":"Amount used while Alt is held. Defaults to 0.1."},{"name":"snapOnStep","type":"boolean","required":false,"defaultValue":"false","description":"Snaps step interactions to multiples of the active step. Defaults to false."},{"name":"step","type":"number | \"any\"","required":false,"defaultValue":"1","description":"Base amount for buttons, arrow keys, wheel, and scrubbing. Use any to disable native step validation while stepping by 1."},{"name":"style","type":"CSSProperties | ((state: NumberFieldRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."},{"name":"value","type":"number | null","required":false,"defaultValue":null,"description":"Controlled raw numeric value. Use null for an empty field."}]},{"name":"Group","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The visible input and any increment or decrement controls."},{"name":"className","type":"string | ((state: NumberFieldGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the group div, or the element composed through Group.render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldGroupState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"Input","props":[{"name":"aria-roledescription","type":"string","required":false,"defaultValue":"Number field","description":"Describes the role to assistive technology. Defaults to Number field; use Field.Label, aria-label, or aria-labelledby for the accessible name."},{"name":"className","type":"string | ((state: NumberFieldInputState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the visible native text input."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState>","required":false,"defaultValue":null,"description":"Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Customize layout through Root or Group."},{"name":"size","type":"number","required":false,"defaultValue":null,"description":"Native input size attribute. Use styles to customize visual dimensions."},{"name":"style","type":"CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"Increment","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Visible content for the increment control. Supply its accessible name."},{"name":"className","type":"string | ((state: NumberFieldIncrementState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the increment button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldIncrementState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldIncrementState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"Decrement","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Visible content for the decrement control. Supply its accessible name."},{"name":"className","type":"string | ((state: NumberFieldDecrementState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the decrement button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldDecrementState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldDecrementState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]},{"name":"ScrubArea","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content the user can drag to adjust the number, plus an optional ScrubAreaCursor."},{"name":"className","type":"string | ((state: NumberFieldScrubAreaState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"direction","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"Pointer movement direction used for scrubbing."},{"name":"pixelSensitivity","type":"number","required":false,"defaultValue":"2","description":"Pixels of pointer movement needed for a step. Larger values reduce sensitivity."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the scrub area span, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldScrubAreaState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."},{"name":"teleportDistance","type":"number","required":false,"defaultValue":null,"description":"Optional distance from the scrub area center at which the pointer loops around."}]},{"name":"ScrubAreaCursor","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Custom cursor content shown during supported pointer-lock scrubbing."},{"name":"className","type":"string | ((state: NumberFieldScrubAreaCursorState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to this part, or a callback receiving its NumberField state."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the cursor span portaled to the document body while active. Null while absent."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaCursorState>","required":false,"defaultValue":null,"description":"Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."},{"name":"style","type":"CSSProperties | ((state: NumberFieldScrubAreaCursorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to this part, or a callback receiving its NumberField state."}]}]}},{"name":"NumberStepper","entryPoint":"twenty-ui/components/input","content":"---\ntitle: NumberStepper\ndescription: Edit a number with optional bounds and increment or decrement buttons.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport NumberStepperReference from '/snippets/ui/generated/components/input/number-stepper.mdx';\n\n## Overview\n\n`NumberStepper` is the compact convenience preset built from [NumberField](/ui/primitives/input/number-field). It combines a numeric text input with optional decrement and increment buttons. Import it from `twenty-ui/components/input`. Use `NumberField` when you need locale or formatting options, different modifier steps, scrubbing, or independent part composition.\n\n<StoryEmbed\n storyId=\"ui-input-numberstepper--display\"\n title=\"NumberStepper example\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { NumberStepper } from 'twenty-ui/components/input';\nimport { Field } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => (\n <Field.Root>\n <Field.Label style={{ color: 'var(--t-font-color-primary)' }}>\n Quantity\n </Field.Label>\n <NumberStepper defaultValue={3} min={0} max={10} />\n <Field.Description style={{ color: 'var(--t-font-color-secondary)' }}>\n Choose up to ten items.\n </Field.Description>\n </Field.Root>\n);\n```\n\n## Visual options\n\nCompare default, bound, disabled, read-only, and invalid states with or without step buttons.\n\n<StoryEmbed\n storyId=\"ui-input-numberstepper--catalog\"\n title=\"Number stepper bounds and states\"\n height={220}\n/>\n\n## Uncontrolled value\n\nUse `defaultValue` to set the initial quantity. The input owns subsequent changes.\n\n```tsx\nimport { NumberStepper } from 'twenty-ui/components/input';\nimport { Field } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => (\n <Field.Root>\n <Field.Label>Quantity</Field.Label>\n <NumberStepper name=\"quantity\" defaultValue={3} min={0} max={10} step={1} />\n <Field.Description>Choose up to ten items.</Field.Description>\n </Field.Root>\n);\n```\n\n## Controlled value\n\nPass a number or `null` through `value` and update it in `onValueChange` to own the same quantity in React state. The callback receives the next numeric value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { NumberStepper } from 'twenty-ui/components/input';\nimport { Field } from 'twenty-ui/primitives/input';\n\nexport const QuantityInput = () => {\n const [quantity, setQuantity] = useState<number | null>(3);\n\n return (\n <Field.Root>\n <Field.Label>Quantity</Field.Label>\n <NumberStepper\n name=\"quantity\"\n value={quantity}\n onValueChange={setQuantity}\n min={0}\n max={10}\n step={1}\n />\n <Field.Description>Choose up to ten items.</Field.Description>\n </Field.Root>\n );\n};\n```\n\nClearing the field reports `null`. Incomplete text such as `-` or `+` remains editable without reporting an invalid number until it is replaced or stepped. By default, parseable numeric edits report the bounded value; the displayed draft is normalized on blur. Values equal to the current value do not call `onValueChange` again.\n\n`onValueCommitted(value, details)` reports the value after an edit is committed: on blur after typing or clearing, on pointer release after a button adjustment, and immediately for keyboard adjustments. Its details contain the native `event` and `reason`. `onValueChange` retains change details, including cancellation methods and the optional stepping direction.\n\n## Application validation\n\nSet `allowOutOfRange` when the application needs the parsed value before applying its own limits or validation. `onValueChange` then receives typed and pasted numbers outside the range. Uncontrolled fields, or controlled fields that accept those values, preserve them on blur. Controlled fields that reject them return to their accepted value on blur. For example, replacing `60` with `45` reports `4` and then `45`, even when `min={30}`. The application can ignore the intermediate value without accidentally saving the minimum.\n\nButtons and keyboard adjustments still stop at `min` and `max`. Native form validation prevents submission while an accepted value is outside that range. `allowOutOfRange` defaults to `false`.\n\n## Bounds and interaction\n\n`min` and `max` are inclusive. Increment and decrement buttons stop at the matching bound. Arrow Up and Arrow Down adjust the focused input by `step`, which defaults to `1`. Home and End select the corresponding bound when provided; call `event.preventBaseUIHandler()` in `onKeyDown` to keep a key's text editing behavior instead. The same step applies when Shift or Alt is held. Displayed values support up to 15 fraction digits; use a positive step within that precision for decimal adjustments.\n\nValues use Latin digits and show grouping separators from five integer digits, such as `12,500`. Typed and pasted group separators of the browser's locale are accepted.\n\n`step` controls adjustments; it does not round typed values to a step. When `min` is set, native form validation also requires `min` plus a multiple of `step`: with the default `step` of `1`, a typed `2.5` blocks submission. Set `showButtons={false}` for text editing with the same keyboard behavior.\n\nEach button has a default accessible name. Use `decrementLabel` and `incrementLabel` to provide contextual or translated names. Give the input a visible `Field.Label`, `aria-label`, or `aria-labelledby`.\n\n## Forms and focus\n\nUse `name` to include the numeric value in a form. `form` associates it with a form elsewhere in the document. The adjustment buttons use `type=\"button\"`, so adjusting a value does not submit the form. `required` participates in native validation.\n\nUse a controlled `value` when your application needs to reset the field. A native form reset does not reset the numeric state.\n\n`disabled` prevents changes and excludes the value from form submission. `readOnly` prevents changes while keeping the input focusable and its value available to the form.\n\nNative input attributes and handlers, `className`, `style`, `ref`, and `render` apply to the visible text input. The ref receives an `HTMLInputElement`; call `ref.current?.focus()` to focus it. When composing through `render`, forward the supplied props and ref to a native input. Customize the surrounding layout with a separate element, or use the `NumberField.Root` and `NumberField.Group` parts when wrapper access is required. Combine the input with `Field.Description` and `Field.Error` for guidance and validation messages.\n\nThe preset deliberately uses compact styling, Latin digits, up to 15 fraction digits, grouping from five integer digits, and the same `step` for ordinary, Shift, and Alt adjustments. These choices apply only to `NumberStepper`. The full `NumberField` primitive retains Base UI's formatting and stepping options.\n\n## Front component renderer\n\nThe React and Preact renderer sandboxes support typing, keyboard adjustments, bounds, form values, pointer stepping, and pasting over selected text. The renderer gallery verifies these interactions in both runtimes. As with `NumberField`, pointer adjustments report changes, but the sandbox does not currently deliver the corresponding commit callback on pointer release. Ordinary React hosts retain the complete commit behavior.\n\n## Props\n\n<NumberStepperReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"NumberStepper","entryPoint":"twenty-ui/components/input","slug":"components/input/number-stepper","props":[{"name":"allowOutOfRange","type":"boolean","required":false,"defaultValue":"false","description":"Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded."},{"name":"aria-roledescription","type":"string","required":false,"defaultValue":"Number field","description":"A user-friendly description of the input's role for assistive tech. This is a role\ndescription, not an accessible name — use `Field.Label` or `aria-label` to name the control."},{"name":"className","type":"string | ((state: NumberFieldInputState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the visible input."},{"name":"decrementLabel","type":"string","required":false,"defaultValue":"Decrease value","description":"Accessible name for the decrement button."},{"name":"defaultValue","type":"number","required":false,"defaultValue":null,"description":"Initial number when the field owns its value."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the input and both buttons, and omits the form value."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"ID of the form that owns the submitted numeric value."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the visible input. Generated when omitted."},{"name":"incrementLabel","type":"string","required":false,"defaultValue":"Increase value","description":"Accessible name for the increment button."},{"name":"max","type":"number","required":false,"defaultValue":null,"description":"Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur."},{"name":"min","type":"number","required":false,"defaultValue":null,"description":"Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name of the numeric value submitted with a form."},{"name":"onValueChange","type":"((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number."},{"name":"onValueCommitted","type":"((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the committed number or null and generic event details after an edit is committed. Details contain the native event and reason, without change cancellation methods."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Prevents numeric changes while keeping the input focusable."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the visible input element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState>","required":false,"defaultValue":null,"description":"Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Use a separate element to customize the surrounding layout."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Requires a numeric value for native form submission."},{"name":"showButtons","type":"boolean","required":false,"defaultValue":"true","description":"Shows the decrement and increment buttons."},{"name":"step","type":"number","required":false,"defaultValue":"1","description":"Amount added or subtracted by the buttons and arrow keys."},{"name":"style","type":"CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles applied to the visible input."},{"name":"value","type":"number | null","required":false,"defaultValue":null,"description":"Controlled numeric value. Use null for an empty field."}]}},{"name":"Textarea","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Textarea\ndescription: Enter multiple lines of text with optional automatic resizing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TextareaReference from '/snippets/ui/generated/input/textarea.mdx';\n\n## Overview\n\nUse `Textarea` for notes, descriptions, and other multiline values. It integrates with [Field](/ui/primitives/input/field) for labels and validation.\n\n<StoryEmbed\n storyId=\"ui-input-textarea--display\"\n title=\"Textarea example\"\n height={190}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial notes. The textarea owns subsequent changes.\n\n```tsx\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const NotesField = () => (\n <Field.Root name=\"notes\">\n <Field.Label>Notes</Field.Label>\n <Textarea rows={4} defaultValue=\"Follow up next week.\" />\n <Field.Description>Add context for your team.</Field.Description>\n </Field.Root>\n);\n```\n\nNative textarea attributes such as `rows`, `maxLength`, `required`, and `readOnly` are available. `size` accepts `sm` or `md` and defaults to `md`.\n\n## Visual choices\n\nCompare the two sizes in default, focused, invalid, and disabled states. Automatic resizing is demonstrated separately below.\n\n<StoryEmbed\n storyId=\"ui-input-textarea--catalog\"\n title=\"Visual choices for textarea\"\n height={440}\n/>\n\n## Plain appearance\n\nUse `variant=\"plain\"` for multiline text inside an existing surface. It removes the fill, border, rounded corners and all padding while keeping the shared text, placeholder and disabled styling. The blue outline follows the browser's native `:focus-visible` behavior. For text controls this can include pointer focus and autofocus as well as keyboard focus. Invalid state uses a danger outline without changing layout.\n\n```tsx\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const InlineNotes = () => (\n <Field.Root>\n <Field.Label>Notes</Field.Label>\n <Textarea variant=\"plain\" autoResize rows={1} maxRows={6} />\n </Field.Root>\n);\n```\n\nThe parent supplies spacing. `rows`, `maxRows` and automatic sizing still control the content height. The row limit excludes padding and borders in the plain appearance. Changing `variant` while automatic sizing is enabled measures the new layout.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same notes in React state. The callback receives the next string value and event details; native `onChange` is also available.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const NotesField = () => {\n const [notes, setNotes] = useState('Follow up next week.');\n\n return (\n <Field.Root name=\"notes\">\n <Field.Label>Notes</Field.Label>\n <Textarea rows={4} value={notes} onValueChange={setNotes} />\n <Field.Description>Add context for your team.</Field.Description>\n </Field.Root>\n );\n};\n```\n\n## Automatic resizing\n\nAutomatic resizing works in either state mode. This example also uses the controlled value for a character count.\n\n```tsx\nimport { useState } from 'react';\nimport { Field, Textarea } from 'twenty-ui/primitives/input';\n\nexport const DescriptionField = () => {\n const [description, setDescription] = useState('');\n\n return (\n <Field.Root name=\"description\">\n <Field.Label>Description</Field.Label>\n <Textarea\n value={description}\n onValueChange={setDescription}\n autoResize\n rows={2}\n maxRows={6}\n maxLength={500}\n />\n <Field.Description>\n {description.length} of 500 characters\n </Field.Description>\n </Field.Root>\n );\n};\n```\n\n`autoResize` measures the committed value after controlled updates and measures uncontrolled edits directly. Rejected controlled edits do not change the height. It also updates after native form resets, `rows`, `size`, `variant`, `maxRows`, and available width changes. Use `maxRows` to cap growth and scroll longer content.\n\nAutomatic sizing owns inline `blockSize` while enabled. Turning it off restores the current `style.blockSize`, or clears the automatic size if none is supplied. With automatic sizing off, `rows` and native styles control height. Manual resizing is disabled by default; set `style={{ resize: 'vertical' }}` when callers should resize the control themselves.\n\n## Native control and render composition\n\nNative textarea attributes and handlers, `className`, `style`, and `ref` target the textarea. The ref receives an `HTMLTextAreaElement`. `render` accepts a textarea element or a callback receiving native textarea props and Field state. Forward the supplied props and ref to the native textarea so labels, validation, events, and automatic measurement keep working. Add a separate layout element when wrapper customization is needed.\n\n`onChange` receives a React change event for the native textarea. `onValueChange(value, details)` retains the Base UI signature, including the native `event`, `reason`, `cancel`, and `allowPropagation`. The native event targets the textarea. Canceling the details preserves Base UI's validation policy; it does not undo the native value. Controlled callers choose the committed value.\n\nNative `name`, `form`, `required`, `readOnly`, `disabled`, submission, and reset behavior remain available. Field supplies label, description, name, and validation association. Enter inserts a line break in the textarea.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<TextareaReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Textarea","entryPoint":"twenty-ui/primitives/input","slug":"input/textarea","props":[{"name":"autoResize","type":"boolean","required":false,"defaultValue":"false","description":"Measures committed controlled values or uncontrolled edits, form resets, row, size and variant changes, and width changes. Overrides blockSize while enabled."},{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the textarea, or a function that returns a class\nbased on the input state."},{"name":"maxRows","type":"number","required":false,"defaultValue":null,"description":"Caps automatic height growth. Content beyond this row limit scrolls."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Receives the next string value and Base UI details, including the native event, reason and cancellation methods."},{"name":"ref","type":"Ref<HTMLTextAreaElement>","required":false,"defaultValue":null,"description":"Ref to the native textarea element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, InputState>","required":false,"defaultValue":null,"description":"Composes the native textarea with a custom element or callback receiving textarea props and Field state. Forward the supplied props and ref to a textarea."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the textarea."},{"name":"variant","type":"\"default\" | \"plain\"","required":false,"defaultValue":"default","description":"default keeps the field frame. plain removes fill, border, radius and padding while retaining rows, automatic sizing and maximum rows. Its outline follows native :focus-visible, including pointer focus or autofocus on textareas; invalid state uses a danger outline."}]}},{"name":"Checkbox","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Checkbox\ndescription: Select independent options with checked and indeterminate states.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CheckboxReference from '/snippets/ui/generated/input/checkbox.mdx';\n\n## Overview\n\nUse `Checkbox` when each option can be selected independently. For a mutually exclusive choice, use [RadioGroup](/ui/primitives/input/radio-group).\n\n<StoryEmbed\n storyId=\"ui-input-checkbox-checkbox--display\"\n title=\"Checkbox example\"\n height={100}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultChecked` to set the initial checked state. The checkbox owns subsequent changes.\n\n```tsx\nimport { useId } from 'react';\nimport { Checkbox } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const EmailPreference = () => {\n const checkboxId = useId();\n\n return (\n <label\n htmlFor={checkboxId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Checkbox id={checkboxId} name=\"updates\" value=\"email\" defaultChecked />\n <Text render={<span />}>Receive product updates</Text>\n </label>\n );\n};\n```\n\nA checked, named checkbox contributes its value to a form. Set `uncheckedValue` if the form should also submit a value when it is unchecked.\n\n## Appearance and interaction\n\nCompare checked, indeterminate, and disabled states, then choose the color, size, shape, and variant independently. The enabled examples can be toggled.\n\n<StoryEmbed\n storyId=\"ui-input-checkbox-checkbox--catalog\"\n title=\"Appearance and interaction for checkbox\"\n height={400}\n/>\n\n| Prop | Values | Default |\n| --------- | ------------------------------ | -------- |\n| `size` | `sm`, `md` | `sm` |\n| `variant` | `solid`, `outline`, `soft` | `solid` |\n| `shape` | `square`, `round` | `square` |\n| `color` | `accent`, `success`, `warning` | `accent` |\n\nTab focuses the checkbox and Space toggles it. Clicking its label also toggles it. Use `disabled` to prevent interaction, or `readOnly` when the value should remain unchanged while the control stays focusable. Keep meaning in the label rather than communicating it through color alone.\n\n## Controlled state\n\nPass `checked` and update it with `onCheckedChange` to own the same preference in React state. The callback receives the next boolean and event details.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { Checkbox } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const EmailPreference = () => {\n const checkboxId = useId();\n const [checked, setChecked] = useState(true);\n\n return (\n <label\n htmlFor={checkboxId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Checkbox\n id={checkboxId}\n name=\"updates\"\n value=\"email\"\n checked={checked}\n onCheckedChange={setChecked}\n />\n <Text render={<span />}>Receive product updates</Text>\n </label>\n );\n};\n```\n\n## Indeterminate state\n\nAn indeterminate checkbox represents a partial selection. Derive it from the child options independently of the checkbox's checked state.\n\n```tsx\nimport { useState } from 'react';\nimport { Checkbox } from 'twenty-ui/primitives/input';\n\nexport const ColumnSelection = () => {\n const [showEmail, setShowEmail] = useState(true);\n const [showPhone, setShowPhone] = useState(false);\n\n return (\n <fieldset>\n <legend>Visible columns</legend>\n <label>\n <Checkbox\n checked={showEmail && showPhone}\n indeterminate={showEmail !== showPhone}\n onCheckedChange={(checked) => {\n setShowEmail(checked);\n setShowPhone(checked);\n }}\n />\n All columns\n </label>\n <label>\n <Checkbox checked={showEmail} onCheckedChange={setShowEmail} />\n Email\n </label>\n <label>\n <Checkbox checked={showPhone} onCheckedChange={setShowPhone} />\n Phone\n </label>\n </fieldset>\n );\n};\n```\n\n## Parts and custom content\n\n`Checkbox` assembles the styled root and its default check and indeterminate icons. Use `Checkbox.Root` with `Checkbox.Indicator` to own the indicator content. Root owns state and box appearance; Indicator renders the content you supply.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Checkbox } from 'twenty-ui/primitives/input';\n\nexport const CustomPreference = () => (\n <Checkbox.Root aria-label=\"Updates\" defaultChecked>\n <Checkbox.Indicator>\n <IconCheck aria-hidden />\n </Checkbox.Indicator>\n </Checkbox.Root>\n);\n```\n\n`CheckboxRootProps` and `CheckboxIndicatorProps` are public types exported from `twenty-ui/primitives/input`. Both parts accept native attributes, handlers, refs, `render`, and state-based `className` and `style` callbacks. Root's `ref` targets the visible control; `inputRef` targets the native input. The part ref targets its rendered element. Pass `nativeButton` with `render={<button />}` when replacing Root with a button. Appearance props belong on Root; explicit classes and styles are merged with the defaults.\n\nIndicator receives checked and indeterminate state, including transition state. Set `keepMounted` to retain an unchecked indicator in the DOM; the default styling hides it with opacity. Override its `style` or `className` for custom transitions.\n\n<StoryEmbed\n storyId=\"ui-input-checkbox-parts--composition\"\n title=\"Checkbox part composition\"\n height={100}\n/>\n\nThe callable assembly and its `CheckboxProps` type remain supported. Replace the assembly with Root and its part when supplying custom icons instead of appending another part to the assembly's children.\n\nFor controlled form reset, handle the form's `onReset` and restore `checked` to your initial value. Base UI 1.8 does not restore uncontrolled component state on native form reset. `required`, `form`, `value`, and `uncheckedValue` keep the upstream native input behavior.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<CheckboxReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Checkbox","entryPoint":"twenty-ui/primitives/input","slug":"input/checkbox","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the checkbox is currently ticked.\n\nTo render an uncontrolled checkbox, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: CheckboxRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"success\" | \"warning\"","required":false,"defaultValue":"accent","description":"Color used while the checkbox is checked or indeterminate."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is initially ticked.\n\nTo render a controlled checkbox, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the checkbox is rendered outside the form."},{"name":"hoverable","type":"boolean","required":false,"defaultValue":"true","description":"Adds padding and a hover background around the box."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the input element."},{"name":"indeterminate","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is in a mixed state: neither ticked, nor unticked."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the checkbox is ticked or unticked."},{"name":"parent","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox controls a group of child checkboxes.\n\nMust be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group)."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to tick or untick the checkbox."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must tick the checkbox before submitting a form."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Corner shape of the box."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the checkbox."},{"name":"style","type":"CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the checkbox is unchecked.\nBy default, unchecked checkboxes do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.\nWhen submitting a form, a checked box submits `value`; with no `value`, it submits the native \"on\"."},{"name":"variant","type":"\"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Visual style of the box: filled, outlined, or tinted."}],"parts":[{"name":"Root","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the checkbox is currently ticked.\n\nTo render an uncontrolled checkbox, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: CheckboxRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"success\" | \"warning\"","required":false,"defaultValue":"accent","description":"Color used while the checkbox is checked or indeterminate."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is initially ticked.\n\nTo render a controlled checkbox, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the checkbox is rendered outside the form."},{"name":"hoverable","type":"boolean","required":false,"defaultValue":"true","description":"Adds padding and a hover background around the box."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the input element."},{"name":"indeterminate","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox is in a mixed state: neither ticked, nor unticked."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the checkbox is ticked or unticked."},{"name":"parent","type":"boolean","required":false,"defaultValue":"false","description":"Whether the checkbox controls a group of child checkboxes.\n\nMust be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group)."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to tick or untick the checkbox."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must tick the checkbox before submitting a form."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Corner shape of the box."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the checkbox."},{"name":"style","type":"CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the checkbox is unchecked.\nBy default, unchecked checkboxes do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.\nWhen submitting a form, a checked box submits `value`; with no `value`, it submits the native \"on\"."},{"name":"variant","type":"\"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"solid","description":"Visual style of the box: filled, outlined, or tinted."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: CheckboxIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the element in the DOM when the checkbox is not checked."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: CheckboxIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Radio","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Radio\ndescription: Render one option in a mutually exclusive radio group.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport RadioReference from '/snippets/ui/generated/input/radio.mdx';\n\n## Overview\n\n`Radio` represents one option inside [RadioGroup](/ui/primitives/input/radio-group). Give each option a distinct `value` and a visible label. The group owns the selected value.\n\n<StoryEmbed\n storyId=\"ui-input-radio--display\"\n title=\"Radio example\"\n height={140}\n/>\n\n## Usage\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const ContactMethod = () => (\n <RadioGroup\n name=\"contactMethod\"\n defaultValue=\"email\"\n aria-label=\"Preferred contact method\"\n >\n <Radio value=\"email\">Email</Radio>\n <Radio value=\"phone\">Phone</Radio>\n <Radio value=\"post\" disabled>\n Postal mail (unavailable)\n </Radio>\n </RadioGroup>\n);\n```\n\nThe `size` prop accepts `sm` or `md` and defaults to `sm`. Use the same size for options in a group.\n\n## Visual choices\n\nCompare selected and disabled states, sizes, and the default and card appearances. Use a labeled group of options for an actual choice.\n\n<StoryEmbed\n storyId=\"ui-input-radio--catalog\"\n title=\"Visual choices for radio\"\n height={380}\n/>\n\n## Complete parts\n\n`Radio.Root` and `Radio.Indicator` expose the installed Base UI parts without the styled assembly. Compose them when you need custom content or indicator placement. The callable `Radio` supplies Twenty's radio appearance and indicator for common options.\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const StorageChoice = () => (\n <RadioGroup aria-label=\"Storage\" defaultValue=\"ssd\">\n <Radio.Root value=\"ssd\">\n <Radio.Indicator keepMounted render={<span />}>\n ✓\n </Radio.Indicator>\n SSD\n </Radio.Root>\n <Radio.Root value=\"hdd\">HDD</Radio.Root>\n </RadioGroup>\n);\n```\n\nStandard radios and `Radio.Root` render a span with radio semantics and an adjacent hidden native input. Card radios render a div. `ref` targets the rendered root; `inputRef` targets the input. `Radio.Indicator` renders a span and its ref targets that element. `render`, state-based `className` and `style`, native attributes and event handlers retain their upstream contracts. The public types include `RadioProps`, `RadioRootProps`, `RadioRootState`, `RadioIndicatorProps` and `RadioIndicatorState`.\n\n## Card options\n\nUse `variant=\"card\"` for full-width options with an inset radio indicator. Card radios keep their div root by default. Use `render` to choose another element explicitly. When that element is a native button, also set `nativeButton`. Keep interactive controls outside the card content.\n\nGive the group enough width for its content and leave space for the indicator at the top right. A title, icon, and short description help explain each choice.\n\n<StoryEmbed\n storyId=\"ui-input-radio--cards-documentation\"\n title=\"Radio card options\"\n height={290}\n/>\n\n```tsx\nimport { IconLayoutKanban, IconTable } from 'twenty-ui/icon';\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nconst VIEWS = [\n {\n value: 'table',\n title: 'Table view',\n description: 'Browse records in rows.',\n Icon: IconTable,\n },\n {\n value: 'board',\n title: 'Board view',\n description: 'Track progress across columns.',\n Icon: IconLayoutKanban,\n },\n];\n\nexport const ViewChoice = () => (\n <RadioGroup\n aria-label=\"Default view\"\n defaultValue=\"table\"\n style={{ width: 280 }}\n >\n {VIEWS.map(({ value, title, description, Icon }) => (\n <Radio key={value} variant=\"card\" value={value}>\n <span style={{ display: 'grid', gap: 8, paddingInlineEnd: 24 }}>\n <Icon size={20} aria-hidden />\n <Text\n render={<span />}\n style={{ fontWeight: 'var(--t-font-weight-medium)' }}\n >\n {title}\n </Text>\n <Text\n render={<span />}\n style={{ color: 'var(--t-font-color-secondary)', lineHeight: 1.5 }}\n >\n {description}\n </Text>\n </span>\n </Radio>\n ))}\n </RadioGroup>\n);\n```\n\n## Explicit native composition\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const BillingChoice = () => (\n <RadioGroup aria-label=\"Billing interval\" defaultValue=\"monthly\">\n <Radio\n variant=\"card\"\n value=\"monthly\"\n nativeButton\n render={<button type=\"button\" />}\n >\n Monthly\n </Radio>\n <Radio\n variant=\"card\"\n value=\"yearly\"\n nativeButton\n render={<button type=\"button\" />}\n >\n Yearly\n </Radio>\n </RadioGroup>\n);\n```\n\nThe ref targets the composed button. For custom non-button roots, leave `nativeButton` false and forward the supplied render props and ref to the actual element.\n\n## Keyboard and selection\n\nTab enters or leaves the group. Arrow keys move between enabled options and select the focused option. Space selects the focused radio. The installed Base UI radio suppresses Enter selection for both default roots and composed native buttons. Selection and change handlers belong on `RadioGroup`; see its [uncontrolled example](/ui/primitives/input/radio-group#uncontrolled-state) and [controlled example](/ui/primitives/input/radio-group#controlled-state).\n\nRadio arrows change selection as they move focus. [Dropdown.SelectionGroup](/ui/components/navigation/dropdown) moves focus with arrows and commits a choice with Enter or Space.\n\n`Radio` and `Radio.Root` are generic over the value type. Keep that type consistent with its group. Native attributes such as `aria-describedby` can associate an option with additional help text.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<RadioReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"Radio","entryPoint":"twenty-ui/primitives/input","slug":"input/radio","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Option content. Card options wrap it in a padded full-width content area."},{"name":"className","type":"string | ((state: RadioRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the component should ignore user interaction."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user should be unable to select the radio button."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user must choose a value before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the radio."},{"name":"style","type":"CSSProperties | ((state: RadioRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"TValue","required":true,"defaultValue":null,"description":"The unique identifying value of the radio in a group."},{"name":"variant","type":"\"card\" | \"default\"","required":false,"defaultValue":"default","description":"Appearance of the styled assembly: a standard radio or a full-width card. Standard radios use a span and card radios use a div unless render replaces the root."}],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: RadioRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the component should ignore user interaction."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user should be unable to select the radio button."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":null,"description":"Whether the user must choose a value before submitting a form."},{"name":"style","type":"CSSProperties | ((state: RadioRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"Value","required":true,"defaultValue":null,"description":"The unique identifying value of the radio in a group."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: RadioIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM when the radio button is inactive."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: RadioIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"RadioGroup","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: RadioGroup\ndescription: Manage a single selection across a set of radio options.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport RadioGroupReference from '/snippets/ui/generated/input/radio-group.mdx';\n\n## Overview\n\n`RadioGroup` coordinates the value, keyboard navigation, and form submission of its [Radio](/ui/primitives/input/radio) children.\n\n<StoryEmbed\n storyId=\"ui-input-radiogroup--display\"\n title=\"RadioGroup example\"\n height={110}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial billing frequency. The group owns subsequent changes.\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const BillingFrequency = () => (\n <RadioGroup\n name=\"billingFrequency\"\n defaultValue=\"monthly\"\n aria-label=\"Billing frequency\"\n >\n <Radio value=\"monthly\">Monthly</Radio>\n <Radio value=\"yearly\">Yearly</Radio>\n </RadioGroup>\n);\n```\n\nThe group's `name` identifies the selected value in form submission. Give the group an accessible name as well as labeling each radio.\n\n### Horizontal layout\n\nGroups use a vertical column by default. Set `orientation=\"horizontal\"` for a row. The prop controls visual layout through `data-orientation`; it does not set `aria-orientation` or change keyboard navigation. Both horizontal and vertical arrow keys retain the existing Base UI behavior, including right-to-left navigation through [DirectionProvider](/ui/primitives/layout/direction-provider).\n\n```tsx\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const HorizontalBillingFrequency = () => (\n <RadioGroup\n orientation=\"horizontal\"\n name=\"billingFrequency\"\n defaultValue=\"monthly\"\n aria-label=\"Billing frequency\"\n >\n <Radio value=\"monthly\">Monthly</Radio>\n <Radio value=\"yearly\">Yearly</Radio>\n </RadioGroup>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-input-radiogroup--horizontal\"\n title=\"Horizontal RadioGroup\"\n height={80}\n/>\n\nThe default gap stays the same in either direction.\n\n## Anatomy\n\nPut each `Radio` or `Radio.Root` inside the group and associate it with a label. Use `Radio.Indicator` to compose a custom indicator. `RadioGroup` and `Radio` are separate exports.\n\n```text\nfieldset\n├── legend\n└── RadioGroup\n ├── label\n │ └── Radio\n └── label\n └── Radio\n```\n\n| Part | Requirement | Purpose |\n| -------------------- | --------------------------- | ---------------------------------------------------------- |\n| `RadioGroup` | Required | Owns selection, keyboard navigation, and form integration. |\n| `Radio` | One per option | Supplies an option with a distinct `value`. |\n| `label` | Recommended for each option | Provides a visible, clickable name for its radio. |\n| `fieldset`, `legend` | Optional grouping | Groups related controls under a visible heading. |\n\nGive the group its own accessible name using `aria-label` or `aria-labelledby`. In the examples below, `aria-labelledby` connects the group to the legend. Each radio also needs its own name. Put selection props on `RadioGroup` and option values on `Radio`.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same billing frequency in React state. Selection belongs to the group, not to individual radio controls.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { Radio, RadioGroup } from 'twenty-ui/primitives/input';\n\nexport const BillingFrequency = () => {\n const labelId = useId();\n const [billingFrequency, setBillingFrequency] = useState('monthly');\n\n return (\n <fieldset>\n <legend id={labelId}>Billing frequency</legend>\n <RadioGroup\n name=\"billingFrequency\"\n value={billingFrequency}\n onValueChange={setBillingFrequency}\n aria-labelledby={labelId}\n >\n <label>\n <Radio value=\"monthly\" />\n Monthly\n </label>\n <label>\n <Radio value=\"yearly\" />\n Yearly\n </label>\n </RadioGroup>\n </fieldset>\n );\n};\n```\n\n`onValueChange` receives the next value and event details. The generic value type is inferred from the props. Use `disabled` on the group to disable every option, or on an individual radio to disable one choice. Arrow keys navigate and select enabled options; Tab moves out of the group. The installed Base UI version supports both horizontal and vertical arrow keys. RadioGroup adds the visual-only `orientation` prop without changing that keyboard contract.\n\n## Native integration and event details\n\n`RadioGroup` renders a div by default. Native props and `ref` target that element; `render` composes another element and changes the actual ref target. `inputRef` targets the representative hidden input of a child radio, using the selected enabled option or an enabled fallback. The public types include generic `RadioGroupProps`, `RadioGroupState`, `RadioGroupChangeEventReason` and `RadioGroupChangeEventDetails`.\n\nThe callback receives the original event details, including the native `event`, `reason`, `cancel()` and `allowPropagation()`. Cancel a proposed change before updating controlled state when the choice should be rejected.\n\nKeep `name`, `form`, `required`, `disabled` and `readOnly` on the group for the existing Base UI form contract. The selected value is submitted under `name`; disabled groups are excluded and read-only groups keep their selection. `form` supports a group outside its owning form. The installed version does not restore group state automatically on native form reset. Reset controlled state from the form's `onReset` handler when your workflow requires it.\n\nIn sandboxed front components, put the group inside its owning form. The renderer forwards `required` validation and blocks explicit `form` references, which otherwise resolve across the host document.\n\n[SegmentedControl](/ui/components/input/segmented-control) is a convenience preset assembled from these primitives for a short exclusive choice. It uses radio semantics and requires an accessible group name. Tabs and tab-panel navigation are separate controls.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<RadioGroupReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"RadioGroup","entryPoint":"twenty-ui/primitives/input","slug":"input/radio-group","props":[{"name":"className","type":"string | ((state: RadioGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"TValue","required":false,"defaultValue":null,"description":"The uncontrolled value of the radio button that should be initially selected.\n\nTo render a controlled radio group, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the radio inputs.\nUseful when the radio group is rendered outside the form."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden input element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onValueChange","type":"((value: TValue, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Callback fired when the value changes."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"vertical","description":"Visual layout direction, reflected in data-orientation. Does not change arrow-key navigation or set aria-orientation."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to select a different radio button in the group."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"style","type":"CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"TValue","required":false,"defaultValue":null,"description":"The controlled value of the radio item that should be currently selected.\n\nTo render an uncontrolled radio group, use the `defaultValue` prop instead."}]}},{"name":"Autocomplete","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Autocomplete\ndescription: Suggest values while the user types and keeps focus in the input.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AutocompleteReference from '/snippets/ui/generated/input/autocomplete.mdx';\n\n## Overview\n\nUse `Autocomplete` for suggestions attached to a text input. The input keeps its caret and keyboard focus while arrow keys highlight suggestions. Use [Select](/ui/primitives/input/select) when the user must choose a value from a fixed list. [Dropdown](/ui/components/navigation/dropdown) remains the higher-level component for menus and pickers.\n\n<StoryEmbed\n storyId=\"ui-input-autocomplete--display\"\n title=\"Autocomplete example\"\n height={360}\n/>\n\n## Usage\n\nPass `items` to `Root` and render them through `List` so filtering updates the visible suggestions. `autoHighlight=\"always\"` highlights the first result whenever the list opens.\n\n```tsx\nimport { Autocomplete } from 'twenty-ui/primitives/input';\n\nconst FRUITS = ['Apple', 'Banana', 'Cherry'];\n\nexport const FruitInput = () => (\n <Autocomplete.Root items={FRUITS} autoHighlight=\"always\">\n <Autocomplete.InputGroup>\n <Autocomplete.Input aria-label=\"Fruit\" placeholder=\"Search fruits\" />\n </Autocomplete.InputGroup>\n <Autocomplete.Portal>\n <Autocomplete.Positioner>\n <Autocomplete.Popup>\n <Autocomplete.Empty>No fruits found</Autocomplete.Empty>\n <Autocomplete.List>\n {(fruit: string) => (\n <Autocomplete.Item key={fruit} value={fruit}>\n {fruit}\n </Autocomplete.Item>\n )}\n </Autocomplete.List>\n </Autocomplete.Popup>\n </Autocomplete.Positioner>\n </Autocomplete.Portal>\n </Autocomplete.Root>\n);\n```\n\n`value` and `onValueChange` control the input text. Use `defaultValue` for an uncontrolled initial value. Open state is independent: use `open` and `onOpenChange`, or `defaultOpen`. `Item.onClick` handles both pointer selection and Enter from the input.\n\n`mode=\"list\"` filters without changing input text on highlight. `mode=\"both\"` also supplies inline completion. `mode=\"inline\"` keeps all items and supplies inline completion; `mode=\"none\"` keeps all items without inline completion. `readOnly` prevents inline completion from changing the input.\n\n## Anatomy\n\nKeep related parts inside a mounted `Autocomplete.Root`. Compose the portal destination, positioning wrapper, and content separately. `InputGroup` optionally groups the input with adjacent controls and anchors the popup to that group.\n\n```text\nAutocomplete.Root\n├── Autocomplete.InputGroup (optional)\n│ ├── Autocomplete.Input\n│ ├── Autocomplete.Clear (optional)\n│ └── Autocomplete.Trigger (optional)\n│ └── Autocomplete.Icon (optional)\n├── Autocomplete.Portal\n│ ├── Autocomplete.Backdrop (optional)\n│ └── Autocomplete.Positioner\n│ └── Autocomplete.Popup\n│ ├── Autocomplete.Arrow (optional)\n│ ├── Autocomplete.Empty\n│ └── Autocomplete.List\n│ ├── Autocomplete.Item\n│ ├── Autocomplete.Group (optional)\n│ │ ├── Autocomplete.GroupLabel\n│ │ └── Autocomplete.Collection\n│ │ └── Autocomplete.Item\n│ ├── Autocomplete.Row (optional, with Root.grid)\n│ │ └── Autocomplete.Item\n│ └── Autocomplete.Separator (optional)\n├── Autocomplete.Status (optional)\n└── Autocomplete.Value (optional)\n```\n\n| Part | Purpose and native target |\n| ------------ | ------------------------------------------------------------------------------- |\n| `Root` | Owns input value, filtering, highlights, and open state. Renders no element. |\n| `Value` | Reads the input text through children or a render function. Renders no element. |\n| `InputGroup` | Groups the input and adjacent controls. Targets a div. |\n| `Input` | Renders the combobox input and retains keyboard focus. Targets an input. |\n| `Trigger` | Opens or closes suggestions. Targets a button. |\n| `Icon` | Contains a trigger indicator. Targets a span. |\n| `Clear` | Clears the input value. Targets a button. |\n| `Portal` | Chooses the destination and mounting policy. Targets its portal div. |\n| `Backdrop` | Supplies an optional overlay beneath the popup. Targets a div. |\n| `Positioner` | Owns anchor, alignment, offsets, and collision handling. Targets its div. |\n| `Popup` | Renders the suggestion content and optional focus behavior. Targets its div. |\n| `Arrow` | Supplies an optional positioned arrow inside Popup. Targets a div. |\n| `List` | Renders filtered items. Targets a div with the listbox or grid role. |\n| `Item` | Renders a suggestion and handles pointer or keyboard selection. Targets a div. |\n| `Group` | Groups related items. Targets a div. |\n| `GroupLabel` | Labels its parent group. Targets a div. |\n| `Row` | Groups a row of items when `Root.grid` is enabled. Targets a div. |\n| `Collection` | Renders filtered items through a function child. Renders no element. |\n| `Separator` | Separates items or groups visually. Targets a div. |\n| `Empty` | Announces when no matching items are available. Targets a div. |\n| `Status` | Announces changes such as asynchronous loading status. Targets a div. |\n\nRendered parts retain native attributes, handlers, refs, state-based `className` and `style`, and element/function `render` composition from the installed Base UI API. Native props and refs target the part's own element. Custom components must forward supplied props and refs. Public part props and state types are exported from `twenty-ui/primitives/input`, together with Root actions and change/highlight event detail types.\n\n`Autocomplete.useFilter()` supplies locale-aware `contains`, `startsWith`, and `endsWith` matching. `Autocomplete.useFilteredItems<TItem>()` reads the internally filtered collection under Root. Treat that result as read-only.\n\n## Object and grouped items\n\nItems can be strings or arbitrary objects. Use `itemToStringValue` to supply the text used for filtering, completion, and form submission. Objects shaped as `{ value, label }` use their label automatically. Render the same item value supplied through Root; no Twenty-specific item shape or selection equality prop is required. Autocomplete owns text input rather than a separate selected object value.\n\nFor grouped data, pass groups with an `items` array. Root preserves the item type for `itemToStringValue` and `onItemHighlighted`. Render each group's filtered children through `Group` and `Collection`:\n\n```tsx\nimport { Autocomplete } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype City = { id: number; name: string; country: string };\ntype CityGroup = { label: string; items: City[] };\n\nconst CITY_GROUPS: CityGroup[] = [\n {\n label: 'Europe',\n items: [\n { id: 1, name: 'Paris', country: 'France' },\n { id: 2, name: 'Lisbon', country: 'Portugal' },\n ],\n },\n];\n\nexport const GroupedCityInput = () => (\n <Text\n style={{ display: 'grid', alignContent: 'start', gap: 8, width: '100%' }}\n >\n <label htmlFor=\"grouped-city\">\n <Text render={<span />}>City</Text>\n </label>\n <Autocomplete.Root\n items={CITY_GROUPS}\n itemToStringValue={(city) => city.name}\n autoHighlight=\"always\"\n >\n <Autocomplete.Input id=\"grouped-city\" placeholder=\"Search cities\" />\n <Autocomplete.Portal>\n <Autocomplete.Positioner>\n <Autocomplete.Popup>\n <Autocomplete.Empty>No matching cities</Autocomplete.Empty>\n <Autocomplete.List>\n {(group: CityGroup) => (\n <Autocomplete.Group key={group.label} items={group.items}>\n <Autocomplete.GroupLabel>\n {group.label}\n </Autocomplete.GroupLabel>\n <Autocomplete.Collection>\n {(city: City) => (\n <Autocomplete.Item\n key={city.id}\n value={city}\n description={city.country}\n >\n {city.name}\n </Autocomplete.Item>\n )}\n </Autocomplete.Collection>\n </Autocomplete.Group>\n )}\n </Autocomplete.List>\n </Autocomplete.Popup>\n </Autocomplete.Positioner>\n </Autocomplete.Portal>\n </Autocomplete.Root>\n </Text>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-input-autocomplete-collections--grouped-objects\"\n title=\"Grouped object suggestions\"\n height={440}\n/>\n\n`Item.startIcon`, `Item.endIcon`, and `Item.description` provide supporting content. Compose `Trigger` and `Clear` with Twenty UI [Button](/ui/primitives/input/button) through `render`. `Icon` can contain an icon from `twenty-ui/icon`. Keep `Status` and `Empty` mounted while updating their children so screen readers can announce changes.\n\n## External filtering and server suggestions\n\nUse `filteredItems` when your application owns filtering. It must preserve the flat or grouped structure of `items`. `filter` accepts a custom matching function; `filter={null}` disables internal filtering for results already filtered by a server.\n\n```tsx\nimport { useState } from 'react';\nimport { Autocomplete } from 'twenty-ui/primitives/input';\n\nconst CITIES = ['Paris', 'London', 'Lisbon'];\n\nexport const CityPrefixInput = () => {\n const [value, setValue] = useState('');\n const { startsWith } = Autocomplete.useFilter();\n const filteredItems = CITIES.filter((city) => startsWith(city, value));\n\n return (\n <Autocomplete.Root\n items={CITIES}\n filteredItems={filteredItems}\n value={value}\n onValueChange={setValue}\n autoHighlight=\"always\"\n >\n <Autocomplete.Input aria-label=\"City prefix\" />\n <Autocomplete.Portal>\n <Autocomplete.Positioner>\n <Autocomplete.Popup>\n <Autocomplete.Empty>No matching cities</Autocomplete.Empty>\n <Autocomplete.List>\n {(city: string) => (\n <Autocomplete.Item key={city} value={city}>\n {city}\n </Autocomplete.Item>\n )}\n </Autocomplete.List>\n </Autocomplete.Popup>\n </Autocomplete.Positioner>\n </Autocomplete.Portal>\n </Autocomplete.Root>\n );\n};\n```\n\nKeep Root mounted when results arrive asynchronously. Control `open` independently so a response can open suggestions while the input remains focused. A mounted `Status` can announce loading; update `Empty` when the completed response has no results. The parent owns debounce, request cancellation, and stale response protection.\n\n`onValueChange` and `onOpenChange` receive the upstream event details, including `reason`, native `event`, `trigger`, `cancel()`, and `allowPropagation()`. Controlled callers decide which requested updates to commit. For example, ignore the `escape-key` value change to keep a server query, or ignore `input-change` opening until results arrive. `onItemHighlighted` receives the original typed item and its highlight reason. Cancellation keeps the installed Base UI semantics; it does not replace the application's controlled-state policy.\n\n## Input composition and native forms\n\n`Input` accepts `size=\"sm\"` or `size=\"md\"` and uses the same styles as [Input](/ui/primitives/input/input). Compose it with an existing input using `render`. The composed control then owns its look: `Input` adds no Input styles and ignores `size`, but still passes your `className`, native attributes, handlers, ref, and state attributes. Forward them to the actual input element. Render Twenty UI `Input` to keep the standard look.\n\n`InputGroup` provides layout and an anchor without adding input borders. It can contain chips or render an existing wrapper. Use [InputGroup](/ui/primitives/input/input-group) through its `render` prop when the whole group needs input styling, as the grouped object suggestions story does. An `Input` without `render` inside it drops its own border. Give the input an accessible label or compose it with [Field](/ui/primitives/input/field).\n\nRoot preserves the upstream `name`, `form`, `disabled`, `readOnly`, and native form behavior. Input's native attributes and ref target its input. `submitOnItemClick` opts into form submission when selecting a suggestion; the default does not submit.\n\nInput preserves Base UI's native IME handling, including composition events and its keyboard confirmation guard.\n\nThe installed Base UI version retains an uncontrolled query on native form reset. For a controlled query, handle the form's `onReset` and restore the application's initial value.\n\n## Placement, portal destination, and dismissal\n\n`Positioner` defaults to `side=\"bottom\"`, `align=\"start\"`, and `sideOffset={8}`. It retains the installed Base UI anchor and positioning contract, including element/ref/function/virtual anchors, functional offsets, `positionMethod`, `collisionBoundary`, `collisionPadding`, `collisionAvoidance`, `arrowPadding`, `sticky`, and `disableAnchorTracking`. Configure these on Positioner. DirectionProvider controls logical placement and DOM direction.\n\n`Popup` uses the anchor width as its minimum width. Set its `width` to supply a fixed content width. Its native props, styles, render composition, and ref target the content element independently of Positioner and Portal. Popup's `initialFocus` and `finalFocus` retain upstream focus options. By default, suggestions keep focus in the input.\n\nConfigure `container` and `keepMounted` on `Portal`. Omitting the container uses the nearest scoped ThemeProvider destination, then Base UI's parent portal or document body. An explicit `null` waits without rendering until a container is supplied. Element, ShadowRoot, and ref destinations pass through to Base UI. An unresolved ref retains Base UI's parent-portal/body fallback.\n\nThe default scoped destination preserves its CSS tokens and color scheme. An explicit destination inherits CSS from its actual DOM scope, so place it inside the intended theme scope or supply those styles there. React context and direction remain available across portals. ShadowRoot targets need the library's CSS and theme styles in that shadow tree.\n\nArrow keys change the highlighted item while the input keeps focus. Enter selects it; Escape and outside interaction request dismissal using upstream semantics. An outside press can activate the destination control. Higher-level pickers can own a different activation policy in their adapter. Call `event.preventBaseUIHandler()` in Input's `onKeyDown` to skip the built-in handler for a key you handle yourself. Use `event.preventDefault()` as well when suppressing the browser's native action.\n\n`Root.inline` with `open` renders suggestions without the popup assembly. Inline items retain their `onClick` selection callbacks, but the installed upstream component fills the input automatically only when its Popup is present. Handle `Item.onClick` when inline selection should update your controlled text. `Root.grid` and `Row` support grid navigation. These modes retain the upstream collection and rendering APIs.\n\n## Migration\n\nWrap Popup with `Autocomplete.Positioner` and `Autocomplete.Portal`. Positioner requires the Portal context; inline suggestions omit the whole popup assembly. Move placement, anchor, and collision props from Popup to Positioner. Move `container` and mounting configuration to Portal. Keep width, content styles, native props, handlers, and refs on Popup. Use an explicit `Arrow` child for an arrow.\n\nInside front components, keep the existing scoped portal policy. This API does not expand renderer portal destinations or geometry, scrolling, and dismissal capabilities; those renderer capabilities have separate ownership. Production picker adapters retain their deliberate activation workflows.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, accessible names, and event handlers are also accepted on rendered parts.\n\n<AutocompleteReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Autocomplete","entryPoint":"twenty-ui/primitives/input","slug":"input/autocomplete","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<AutocompleteRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the autocomplete after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the autocomplete completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the autocomplete imperatively when called."},{"name":"autoHighlight","type":"boolean | \"always\"","required":false,"defaultValue":"false","description":"Whether the first matching item is highlighted automatically.\n- `true`: highlight after the user types and keep the highlight while the query changes.\n- `'always'`: always highlight the first item."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popup is initially open.\n\nTo render a controlled popup, use the `open` prop instead."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The uncontrolled input value of the autocomplete when it's initially rendered.\n\nTo render a controlled autocomplete, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"filter","type":"AutocompleteRootProps<TItem>[\"filter\"]","required":false,"defaultValue":null,"description":"Filter function used to match items against the input query."},{"name":"filteredItems","type":"readonly TItem[] | readonly { items: readonly TItem[] }[]","required":false,"defaultValue":null,"description":"Filtered items to display in the list.\nWhen provided, the list uses these items instead of filtering the `items` prop internally.\nWhen `items` is also provided, this array must preserve its flat or grouped structure.\nNullish entries are not supported, as in `items`.\nUse when you want to control filtering logic externally with the `useFilter()` hook."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the internal input.\nUseful when the autocomplete is rendered outside the form."},{"name":"grid","type":"boolean","required":false,"defaultValue":"false","description":"Whether list items are presented in a grid layout.\nWhen enabled, arrow keys navigate across rows and columns inferred from DOM rows."},{"name":"highlightItemOnHover","type":"boolean","required":false,"defaultValue":"true","description":"Whether moving the pointer over items should highlight them.\nDisabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the component."},{"name":"inline","type":"boolean","required":false,"defaultValue":"false","description":"Whether the list is rendered inline without using the component's own popup.\n\nSpecify `open` unconditionally in conjunction with this prop so the list is considered\nvisible: `<Autocomplete.Root inline open>`"},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to the hidden input element."},{"name":"items","type":"readonly TItem[] | readonly { items: readonly TItem[] }[]","required":false,"defaultValue":null,"description":"Flat items or groups with an items array. Preserves the upstream item type; nullish entries are not supported."},{"name":"itemToStringValue","type":"(itemValue: TItem) => string","required":false,"defaultValue":null,"description":"When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission.\nIf the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop."},{"name":"keepHighlight","type":"boolean","required":false,"defaultValue":"false","description":"Whether the highlighted item should be preserved when the pointer leaves the list."},{"name":"limit","type":"number","required":false,"defaultValue":"-1","description":"The maximum number of items to display in the list."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"The locale to use for string comparison.\nDefaults to the user's runtime locale."},{"name":"loopFocus","type":"boolean","required":false,"defaultValue":"true","description":"Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input.\nThe input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).\nWhen disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>."},{"name":"modal","type":"boolean","required":false,"defaultValue":"false","description":"Determines if the popup enters a modal state when open.\n- `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n\nOn touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior."},{"name":"mode","type":"\"both\" | \"inline\" | \"list\" | \"none\"","required":false,"defaultValue":"list","description":"Controls how the autocomplete behaves with respect to list filtering and inline autocompletion.\n- `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.\n- `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion).\n- `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion).\n- `none`: items are static (not filtered), and the input value will not change based on the active item."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onItemHighlighted","type":"(highlightedValue: TItem | undefined, eventDetails: AutocompleteRootHighlightEventDetails) => void","required":false,"defaultValue":null,"description":"Callback fired when an item is highlighted or unhighlighted.\nReceives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.\nThe `reason` can be:\n- `'keyboard'`: the highlight changed due to keyboard navigation.\n- `'pointer'`: the highlight changed due to pointer hovering. The event may be a `MouseEvent`\n rather than a `PointerEvent`.\n- `'none'`: the highlight changed for another reason, such as typing, `autoHighlight`, the\n item list changing, or the popup opening or closing."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: AutocompleteRootOpenChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Event handler called when the popup is opened or closed."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the popup is opened or closed."},{"name":"onValueChange","type":"((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Event handler called when the input value of the autocomplete changes."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is currently open. Use when controlled."},{"name":"openOnInputClick","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popup opens when clicking the input."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to choose a different option from the popup."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"submitOnItemClick","type":"boolean","required":false,"defaultValue":"false","description":"Whether clicking an item should submit the autocomplete's owning form.\nBy default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form.\nUseful when the autocomplete is used as a single-field form search input."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The input value of the autocomplete. Use when controlled."},{"name":"virtualized","type":"boolean","required":false,"defaultValue":"false","description":"Whether the items are being externally virtualized."}]},{"name":"Value","props":[{"name":"children","type":"ReactNode | ((value: string) => ReactNode)","required":false,"defaultValue":null,"description":"Content or render function receiving the current input text."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: AutocompleteTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: AutocompleteTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"InputGroup","props":[{"name":"className","type":"string | ((state: AutocompleteInputGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteInputGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: AutocompleteInputGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Input","props":[{"name":"className","type":"string | ((state: ComboboxInputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxInputState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":null,"description":"Visual size of the input. Inside an InputGroup, the group size applies. Not accepted with render."},{"name":"style","type":"CSSProperties | ((state: ComboboxInputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Icon","props":[{"name":"className","type":"string | ((state: ComboboxIconState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxIconState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxIconState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Clear","props":[{"name":"className","type":"string | ((state: ComboboxClearState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should remain mounted in the DOM when not visible."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxClearState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxClearState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: ComboboxPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Omitted uses the scoped theme container; explicit null waits without rendering. Element, ShadowRoot and ref targets pass through to Base UI."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the portal mounted in the DOM while the popup is hidden."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: ComboboxBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"start","description":"Alignment relative to the anchor. Defaults to start."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: ComboboxPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div, separate from Popup and Portal."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"8","description":"Distance from the anchor. Defaults to 8; supports functional offsets."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: ComboboxPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"className","type":"string | ((state: ComboboxPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popup is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popup is opened.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"width","type":"string | number","required":false,"defaultValue":null,"description":"Width of the popup. Overrides its default minimum anchor width."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: ComboboxArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"List","props":[{"name":"className","type":"string | ((state: ComboboxListState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxListState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxListState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Status","props":[{"name":"className","type":"string | ((state: ComboboxStatusState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxStatusState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxStatusState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Group","props":[{"name":"className","type":"string | ((state: ComboboxGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"items","type":"readonly any[]","required":false,"defaultValue":null,"description":"Items to be rendered within this group.\nWhen provided, child `Collection` components will use these items."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"GroupLabel","props":[{"name":"className","type":"string | ((state: ComboboxGroupLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxGroupLabelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxGroupLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Item","props":[{"name":"className","type":"string | ((state: AutocompleteItemState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"end\" | \"inline\"","required":false,"defaultValue":"inline","description":"Where the description renders: inline after the content or at the end of the row."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"index","type":"number","required":false,"defaultValue":null,"description":"The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onClick","type":"((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)","required":false,"defaultValue":null,"description":"An optional click handler for the item when selected.\nIt fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteItemState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties | ((state: AutocompleteItemState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":false,"defaultValue":"null","description":"A unique value that identifies this item."}]},{"name":"Row","props":[{"name":"className","type":"string | ((state: ComboboxRowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxRowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxRowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Collection","props":[{"name":"children","type":"(item: any, index: number) => ReactNode","required":true,"defaultValue":null,"description":"Render function receiving each filtered item and its index."}]},{"name":"Empty","props":[{"name":"className","type":"string | ((state: ComboboxEmptyState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxEmptyState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: ComboboxEmptyState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Separator","props":[{"name":"className","type":"string | ((state: AutocompleteSeparatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The orientation of the separator."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AutocompleteSeparatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: AutocompleteSeparatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Select","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Select\ndescription: Choose one or more values from a popup list of options.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SelectReference from '/snippets/ui/generated/input/select.mdx';\n\n## Overview\n\nUse `Select` for a form value chosen from a list. [Dropdown](/ui/components/navigation/dropdown) remains the main higher-level API for menus, pickers, panels, and pages that combine those workflows.\n\n<StoryEmbed\n storyId=\"ui-input-select--display\"\n title=\"Select example\"\n height={240}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial priority. The select owns subsequent selection changes.\n\n```tsx\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PrioritySelect = () => (\n <Select.Root name=\"priority\" defaultValue=\"normal\" items={PRIORITIES}>\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value placeholder=\"Choose a priority\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n);\n```\n\nSupply `items` on `Root` so `Value` renders the selected item's label; without it, the trigger shows the raw value. The selected value can be `null` when nothing is selected.\n\n## Anatomy\n\nCompose the public parts inside `Select.Root`. `Trigger` and `Item` render only their children. Add `Icon`, `ItemText`, and `ItemIndicator` explicitly when you want the default chevron, label, and checkmark.\n\n```text\nSelect.Root\n├── Select.Label\n├── Select.Trigger\n│ ├── Select.Value\n│ └── Select.Icon\n└── Select.Portal\n ├── Select.Backdrop\n └── Select.Positioner\n └── Select.Popup\n ├── Select.Arrow\n ├── Select.ScrollUpArrow\n ├── Select.List\n │ ├── Select.Group\n │ │ ├── Select.GroupLabel\n │ │ └── Select.Item\n │ │ ├── Select.ItemText\n │ │ └── Select.ItemIndicator\n │ └── Select.Separator\n └── Select.ScrollDownArrow\n```\n\n| Part | Purpose |\n| ---------------------------------- | ----------------------------------------------------------------------------- |\n| `Root` | Owns selection, open state, generic values, and native form integration. |\n| `Label` | Associates a visible label with the trigger. |\n| `Trigger` | Opens the list and contains the displayed value. |\n| `Value` | Renders the selected label or a placeholder. |\n| `Icon` | Renders a default chevron or custom children in the trigger. |\n| `Portal` | Moves popup content to the theme's portal container or an explicit container. |\n| `Backdrop` | Provides an optional backdrop while the popup is open. |\n| `Positioner` | Owns anchor geometry, placement, offsets, and collision behavior. |\n| `Popup` | Renders the popup surface without adding a portal or positioner. |\n| `List` | Provides a separate scrolling container for options. |\n| `Item` | Provides selection behavior for one option. |\n| `ItemText` | Identifies the option label used for typeahead and selected-value alignment. |\n| `ItemIndicator` | Renders the selected option's default checkmark or custom children. |\n| `Arrow` | Positions an optional arrow against the popup anchor. |\n| `ScrollUpArrow`, `ScrollDownArrow` | Scroll a long list when hovered. |\n| `Group`, `GroupLabel` | Group related options under a label. |\n| `Separator` | Separates groups visually. |\n\n`Portal`, `List`, `Backdrop`, arrows, and indicators are optional. Use `Positioner` around `Popup` for positioning, including when you render the popup inline without a portal.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same priority in React state. The callback receives the next value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PrioritySelect = () => {\n const [priority, setPriority] = useState<string | null>('normal');\n\n return (\n <Select.Root\n name=\"priority\"\n value={priority}\n onValueChange={setPriority}\n items={PRIORITIES}\n >\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value placeholder=\"Choose a priority\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\n## Multiple selection\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst LANGUAGES = [\n { value: 'en', label: 'English' },\n { value: 'fr', label: 'French' },\n { value: 'es', label: 'Spanish' },\n];\n\nexport const LanguageSelect = () => {\n const [languages, setLanguages] = useState<string[]>(['en']);\n\n return (\n <Select.Root\n multiple\n value={languages}\n onValueChange={setLanguages}\n items={LANGUAGES}\n >\n <Select.Trigger aria-label=\"Languages\">\n <Select.Value placeholder=\"Choose languages\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {LANGUAGES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\nWith `multiple`, the value is an array. Use `defaultValue={['en']}` instead of `value` and `onValueChange` for an uncontrolled multiple selection. The generic root types represent the option value and whether multiple selection is enabled.\n\n## Open state\n\nSelection and popup visibility are independent. The examples above leave popup visibility uncontrolled. Selecting a single value closes the popup; multiple selection keeps it open. Use `defaultOpen` to set its initial visibility; it defaults to `false`.\n\nPass `open` and update it with `onOpenChange` to control visibility. This example controls the popup while leaving the selected priority uncontrolled.\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PrioritySelect = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Select.Root\n name=\"priority\"\n defaultValue=\"normal\"\n items={PRIORITIES}\n open={open}\n onOpenChange={setOpen}\n >\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value placeholder=\"Choose a priority\" />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\n## Compose with a field\n\nWrap the select in `Field.Root` to associate its trigger with a visible label and helper text. The field handles labeling and validation; the select keeps its own selection and popup state.\n\n```tsx\nimport { Field, Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PriorityField = () => (\n <Field.Root name=\"priority\">\n <Field.Label>Priority</Field.Label>\n <Select.Root name=\"priority\" defaultValue=\"normal\" items={PRIORITIES}>\n <Select.Trigger>\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n <Field.Description>\n Choose how soon this record needs attention.\n </Field.Description>\n </Field.Root>\n);\n```\n\n## Item composition\n\nCompose arbitrary content inside `Item`. Put the searchable label in `ItemText`; additional content does not become its typeahead label. Provide children to `Icon` or `ItemIndicator` to replace their default icons, or omit those parts altogether.\n\n```tsx\nimport { Select } from 'twenty-ui/primitives/input';\n\nexport const PrioritySelect = () => (\n <Select.Root defaultValue=\"high\" items={{ high: 'High' }}>\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n <Select.Item value=\"high\">\n <Select.ItemText>High</Select.ItemText>\n <span>Needs attention today</span>\n <Select.ItemIndicator />\n </Select.Item>\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n);\n```\n\nAll parts that render elements accept native attributes, refs, and Base UI's `render`, `className`, and `style` composition APIs. For example, use `render={<Button />}` on `Trigger` to compose it with a Twenty UI button. For a non-button render element, also set `nativeButton={false}`.\n\n## Placement\n\nSet `size=\"sm\"` or `size=\"md\"` on `Trigger`. Placement belongs on `Positioner`; portal destination belongs on `Portal`.\n\n`Positioner` preserves Base UI's defaults: `side=\"bottom\"`, `align=\"center\"`, `sideOffset={0}`, and `alignItemWithTrigger={true}`. Selected-item alignment applies to pointer input when there is enough space. Set `alignItemWithTrigger={false}` to use anchored positioning consistently. The examples above choose `align=\"start\"` and `sideOffset={8}` explicitly.\n\n```tsx\nimport { useRef, useState } from 'react';\nimport { Button, Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'low', label: 'Low' },\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\nexport const PositionedPrioritySelect = () => {\n const anchorRef = useRef<HTMLButtonElement>(null);\n const boundaryRef = useRef<HTMLDivElement>(null);\n const [portalContainer, setPortalContainer] = useState<HTMLDivElement | null>(\n null,\n );\n\n return (\n <div ref={boundaryRef}>\n <Button ref={anchorRef}>Position anchor</Button>\n <Select.Root defaultValue=\"normal\" items={PRIORITIES}>\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal container={portalContainer}>\n <Select.Positioner\n anchor={anchorRef}\n positionMethod=\"fixed\"\n side=\"inline-end\"\n align=\"start\"\n alignItemWithTrigger={false}\n sideOffset={({ anchor }) => anchor.width / 4}\n alignOffset={4}\n collisionBoundary={boundaryRef.current ?? undefined}\n collisionPadding={12}\n collisionAvoidance={{ side: 'flip', align: 'shift' }}\n sticky\n >\n <Select.Popup>\n <Select.Arrow />\n <Select.List>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.List>\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n <div ref={setPortalContainer} />\n </div>\n );\n};\n```\n\n`Positioner` also supports virtual anchors, offset functions, `arrowPadding`, and `disableAnchorTracking`. `Portal` uses the [theme's portal container](/ui/theming#scope-an-override) unless you provide `container`. An explicit `container={null}` waits until that container is available.\n\n<StoryEmbed\n storyId=\"ui-input-select-portals--positioning-documentation\"\n title=\"Select with a custom anchor and scrollable list\"\n height={480}\n/>\n\n## Native forms and callback details\n\nSet `name` on `Root` to include the selected value in `FormData`. Multiple selection submits one entry per selected value. `form` associates the hidden input with an external form, and `inputRef` gives access to that input. `required`, `disabled`, and `autoComplete` retain Base UI's native form behavior.\n\n`onValueChange` and `onOpenChange` receive the next state and upstream event details, including `reason`, the native `event`, `cancel()`, and `allowPropagation()`. Calling `cancel()` prevents the corresponding internal state change. Controlled roots still require you to update `value` or `open`.\n\n```tsx\nimport { useState } from 'react';\nimport { Select } from 'twenty-ui/primitives/input';\n\nconst PRIORITIES = [\n { value: 'normal', label: 'Normal' },\n { value: 'high', label: 'High' },\n];\n\ntype PrioritySelectProps = { canSetHighPriority: boolean };\n\nexport const PrioritySelect = ({ canSetHighPriority }: PrioritySelectProps) => {\n const [priority, setPriority] = useState<string | null>('normal');\n\n return (\n <Select.Root\n items={PRIORITIES}\n value={priority}\n onValueChange={(nextPriority, details) => {\n if (nextPriority === 'high' && !canSetHighPriority) {\n details.cancel();\n return;\n }\n setPriority(nextPriority);\n }}\n >\n <Select.Trigger aria-label=\"Priority\">\n <Select.Value />\n <Select.Icon />\n </Select.Trigger>\n <Select.Portal>\n <Select.Positioner\n align=\"start\"\n sideOffset={8}\n alignItemWithTrigger={false}\n >\n <Select.Popup>\n {PRIORITIES.map(({ value, label }) => (\n <Select.Item key={value} value={value}>\n <Select.ItemText>{label}</Select.ItemText>\n <Select.ItemIndicator />\n </Select.Item>\n ))}\n </Select.Popup>\n </Select.Positioner>\n </Select.Portal>\n </Select.Root>\n );\n};\n```\n\nThe generic root types represent the option value and whether multiple selection is enabled. Object values support `itemToStringLabel`, `itemToStringValue`, and `isItemEqualToValue`. Use `null` for an empty single selection and an empty array for an empty multiple selection.\n\n## Keyboard\n\nKeyboard users can open the list from the trigger, navigate options with arrow keys, and type to find an option. Home and End jump to the first and last options. Enter selects an option; Escape dismisses the popup and restores trigger focus. Multiple selection keeps the popup open while options are toggled.\n\nLabel the trigger with `Select.Label`, an accessible name, or [Field](/ui/primitives/input/field). A placeholder alone does not name the control.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<SelectReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Select","entryPoint":"twenty-ui/primitives/input","slug":"input/select","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<SelectRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the select after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the select completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the select imperatively when called."},{"name":"autoComplete","type":"string","required":false,"defaultValue":null,"description":"Provides a hint to the browser for autofill."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Select parts sharing selection, open state and accessible relationships. Root renders no DOM node."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the select popup is initially open.\n\nTo render a controlled select popup, use the `open` prop instead."},{"name":"defaultValue","type":"SelectInputValue<Value, Multiple> | null","required":false,"defaultValue":null,"description":"The uncontrolled value of the select when it's initially rendered.\n\nTo render a controlled select, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the select is rendered outside the form."},{"name":"highlightItemOnHover","type":"boolean","required":false,"defaultValue":"true","description":"Whether moving the pointer over items should highlight them.\nDisabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the Select."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the native hidden input used for form submission."},{"name":"isItemEqualToValue","type":"((itemValue: Value, value: Value) => boolean)","required":false,"defaultValue":null,"description":"Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially.\nDefaults to `Object.is` comparison."},{"name":"items","type":"Record<string, ReactNode> | readonly { label: ReactNode; value: any; }[] | readonly Group<any>[]","required":false,"defaultValue":null,"description":"Data structure of the items rendered in the select popup.\nWhen specified, `<Select.Value>` renders the label of the selected item instead of the raw value."},{"name":"itemToStringLabel","type":"((itemValue: Value) => string)","required":false,"defaultValue":null,"description":"When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for display in the trigger.\nIf the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop."},{"name":"itemToStringValue","type":"((itemValue: Value) => string)","required":false,"defaultValue":null,"description":"When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for form submission.\nIf the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop."},{"name":"modal","type":"boolean","required":false,"defaultValue":"true","description":"Determines if the select enters a modal state when open.\n- `true`: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n\nOn touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior."},{"name":"multiple","type":"boolean","required":false,"defaultValue":"false","description":"Whether multiple items can be selected."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the select popup is opened or closed."},{"name":"onValueChange","type":"((value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested generic value and unchanged Base UI event details, including reason, event and cancel(). Multiple selection receives an array; a cleared single value is null."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the select popup is currently open."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to choose a different option from the select popup."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must choose a value before submitting a form."},{"name":"value","type":"SelectInputValue<Value, Multiple> | null","required":false,"defaultValue":null,"description":"The value of the select. Use when controlled."}]},{"name":"Label","props":[{"name":"className","type":"string | ((state: FieldRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Trigger","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Trigger content rendered as supplied. Compose Value and Icon explicitly."},{"name":"className","type":"string | ((state: SelectTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the component should ignore user interaction."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the rendered trigger element, a button by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the trigger. Defaults to md."},{"name":"style","type":"CSSProperties | ((state: SelectTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Value","props":[{"name":"children","type":"ReactNode | ((value: any) => ReactNode)","required":false,"defaultValue":null,"description":"Accepts a function that returns a `ReactNode` to format the selected value.\nTreat the value as read-only: in `multiple` mode it may be a shared frozen array\nwhen nothing is selected."},{"name":"className","type":"string | ((state: SelectValueState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"placeholder","type":"ReactNode","required":false,"defaultValue":null,"description":"The placeholder value to display when no value is selected.\nThis is overridden by `children` if specified, or by a null item's label in `items`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectValueState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectValueState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Icon","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":"<IconChevronDown />","description":"Trigger icon content. Defaults to the Twenty chevron; explicit children replace it."},{"name":"className","type":"string | ((state: SelectIconState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectIconState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectIconState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: SelectPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Defaults to the current theme container, then the document body. Explicit null waits for a container before mounting."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div. Native props and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: SelectBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"How to align the popup relative to the specified side."},{"name":"alignItemWithTrigger","type":"boolean","required":false,"defaultValue":"true","description":"Uses the upstream selected-item alignment by default. Set false to use side, align and offsets without overlapping the trigger."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: SelectPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div. Native props, styles and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Distance between the anchor and the popup in pixels.\nAlso accepts a function that returns the distance to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: SelectPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Popup content rendered as supplied. Compose inside Positioner and choose Portal separately."},{"name":"className","type":"string | ((state: SelectPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the select popup is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div. Native props, styles and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"List","props":[{"name":"className","type":"string | ((state: SelectListState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectListState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectListState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Item","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Option content rendered as supplied. Compose ItemText and an optional ItemIndicator explicitly."},{"name":"className","type":"string | ((state: SelectItemState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Specifies the text label to use when the item is matched during keyboard text navigation.\n\nDefaults to the item text content if not provided."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"ref","type":"Ref<HTMLElement>","required":false,"defaultValue":null,"description":"Ref to the rendered option element. Native props and render apply to this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectItemState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":false,"defaultValue":"null","description":"A unique value that identifies this select item."}]},{"name":"ItemIndicator","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":"<IconCheck className={listItemStyles.checkIndicator} />","description":"Selected indicator content. Defaults to the Twenty check icon; explicit children replace it."},{"name":"className","type":"string | ((state: SelectItemIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":null,"description":"Whether to keep the HTML element in the DOM when the item is not selected."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectItemIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"ItemText","props":[{"name":"className","type":"string | ((state: SelectItemTextState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemTextState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectItemTextState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: SelectArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"ScrollDownArrow","props":[{"name":"className","type":"string | ((state: SelectScrollDownArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM while the select popup is not scrollable."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollDownArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectScrollDownArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"ScrollUpArrow","props":[{"name":"className","type":"string | ((state: SelectScrollUpArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM while the select popup is not scrollable."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollUpArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectScrollUpArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Group","props":[{"name":"className","type":"string | ((state: SelectGroupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectGroupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"GroupLabel","props":[{"name":"className","type":"string | ((state: SelectGroupLabelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupLabelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectGroupLabelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Separator","props":[{"name":"className","type":"string | ((state: SelectSeparatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The orientation of the separator."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectSeparatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SelectSeparatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Slider","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Slider\ndescription: Choose a numeric value or range with draggable, keyboard-accessible thumbs.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SliderReference from '/snippets/ui/generated/input/slider.mdx';\n\n## Overview\n\n`Slider` supports a single number or an array of numbers for a range. Compose its label, track, indicator, and thumbs inside `Root`.\n\n<StoryEmbed\n storyId=\"ui-input-slider--display\"\n title=\"Slider example\"\n height={120}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultValue` to set the initial volume. The slider owns subsequent changes.\n\n```tsx\nimport { Slider } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const VolumeSlider = () => (\n <Slider.Root name=\"volume\" defaultValue={40} min={0} max={100} step={1}>\n <Text\n render={<div />}\n style={{ display: 'flex', justifyContent: 'space-between' }}\n >\n <Slider.Label>Volume</Slider.Label>\n <Slider.Value />\n </Text>\n <Slider.Control>\n <Slider.Track>\n <Slider.Indicator />\n <Slider.Thumb />\n </Slider.Track>\n </Slider.Control>\n </Slider.Root>\n);\n```\n\n## Visual choices\n\nCompare the accent and success colors at minimum, middle, maximum, and disabled values. The enabled sliders remain interactive.\n\n<StoryEmbed\n storyId=\"ui-input-slider--catalog\"\n title=\"Visual choices for slider\"\n height={340}\n/>\n\n## Anatomy\n\nPut the track and thumbs inside `Slider.Control`, which handles pointer interaction. This tree shows a single-thumb slider.\n\n```text\nSlider.Root\n├── Slider.Label\n├── Slider.Value\n└── Slider.Control\n └── Slider.Track\n ├── Slider.Indicator\n └── Slider.Thumb\n```\n\n| Part | Requirement | Purpose |\n| ----------- | ----------------------------- | --------------------------------------------------------------- |\n| `Root` | Required | Owns the value, bounds, step, and orientation. |\n| `Control` | Required | Handles pointer interaction and positions the thumbs. |\n| `Track` | Required for the styled track | Shows the full value range. |\n| `Thumb` | One per adjustable value | Provides a focusable handle with keyboard interaction. |\n| `Label` | Recommended | Supplies a visible label; every thumb needs an accessible name. |\n| `Value` | Optional | Displays the current numeric value. |\n| `Indicator` | Optional | Shows the selected portion of the track. |\n\nFor a range, add a thumb for each value with its matching `index` and a distinct accessible name. Labels and numeric output stay outside `Control`, so they do not become part of the draggable area.\n\n## Controlled state\n\nPass `value` and update it with `onValueChange` to own the same volume in React state. The callback receives the next value and event details.\n\n```tsx\nimport { useState } from 'react';\nimport { Slider } from 'twenty-ui/primitives/input';\n\nexport const VolumeSlider = () => {\n const [volume, setVolume] = useState(40);\n\n return (\n <Slider.Root\n name=\"volume\"\n value={volume}\n onValueChange={setVolume}\n min={0}\n max={100}\n step={1}\n >\n <Slider.Label>Volume</Slider.Label>\n <Slider.Value />\n <Slider.Control>\n <Slider.Track>\n <Slider.Indicator />\n <Slider.Thumb />\n </Slider.Track>\n </Slider.Control>\n </Slider.Root>\n );\n};\n```\n\nUse `onValueChange` to keep the controlled value current during an interaction. `onValueCommitted` handles the final value when the interaction finishes, for example to save it. Both callbacks are also available in uncontrolled mode without taking ownership of the value.\n\nChange details include the originating `event`, the interaction `reason`, the `activeThumbIndex`, and `cancel()`. Commit details use Base UI's generic event contract and do not include change cancellation. A canceled change does not commit.\n\n## Range\n\n```tsx\nimport { Slider } from 'twenty-ui/primitives/input';\n\nexport const PriceRange = () => (\n <Slider.Root\n defaultValue={[25, 75]}\n min={0}\n max={100}\n minStepsBetweenValues={10}\n >\n <Slider.Label>Price range</Slider.Label>\n <Slider.Value />\n <Slider.Control>\n <Slider.Track>\n <Slider.Indicator />\n <Slider.Thumb index={0} aria-label=\"Minimum price\" />\n <Slider.Thumb index={1} aria-label=\"Maximum price\" />\n </Slider.Track>\n </Slider.Control>\n </Slider.Root>\n);\n```\n\nGive range thumbs distinct accessible names and an `index` corresponding to their value. `minStepsBetweenValues` sets the minimum gap in steps. The root's generic value type is a number or a readonly array of numbers.\n\nTo control a range, store the array in React state and pass it through `value` and `onValueChange`, just as for a single value.\n\n## Keyboard and appearance\n\nArrow keys adjust a focused thumb by a step. Home and End move it toward the bounds while respecting range constraints. `orientation=\"vertical\"` changes the layout and keyboard direction. Use `disabled` on `Root` to prevent changes.\n\nSet `color=\"success\"` for the alternative palette; the default is `accent`.\n\nThe default `thumbAlignment` is `edge`. Pass `center` or `edge-client-only` to override it. Native `className`, `style`, and `render` composition remain available on each part, including state functions.\n\n<Note>\n With `edge` and `edge-client-only` alignment, Base UI 1.8 and 1.9 never\n re-measure a thumb after its `Slider.Control` resizes, and a slider mounted\n while hidden keeps its thumbs hidden once shown\n ([mui/base-ui#5995](https://github.com/mui/base-ui/issues/5995)). React front\n components hit the same issue on their first render. Use\n `thumbAlignment=\"center\"` until a Base UI release includes the fix\n ([mui/base-ui#6000](https://github.com/mui/base-ui/pull/6000)).\n</Note>\n\n## Native integration and types\n\n`Slider.Root` infers a number or a readonly numeric array from `value` or `defaultValue`, retaining that type in both callbacks. `SliderRootProps` accepts both by default; use `SliderRootProps<number>` for single-value helpers or `SliderRootProps<readonly number[]>` for range helpers.\n\nEvery part has an exported props type in `twenty-ui/primitives/input`: `SliderRootProps`, `SliderControlProps`, `SliderTrackProps`, `SliderIndicatorProps`, `SliderThumbProps`, `SliderLabelProps`, and `SliderValueProps`.\n\nRefs target div elements for Root, Control, Track, Indicator, Thumb, and Label, and an output element for Value. A Thumb's ref targets its visible handle; its accessible name and native form value belong to the nested range input. Use `name` and `form` on Root for native submission, with one input per range value.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<SliderReference />\n\n<PageBanner illustration=\"section-apps-config\" />\n","api":{"name":"Slider","entryPoint":"twenty-ui/primitives/input","slug":"input/slider","props":[],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: SliderRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"success\"","required":false,"defaultValue":"accent","description":"Color of the indicator and thumbs."},{"name":"defaultValue","type":"number | readonly number[]","required":false,"defaultValue":null,"description":"The uncontrolled value of the slider when it's initially rendered.\n\nTo render a controlled slider, use the `value` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the slider should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the slider inputs.\nUseful when the slider is rendered outside the form."},{"name":"format","type":"NumberFormatOptions","required":false,"defaultValue":null,"description":"Options to format the value."},{"name":"largeStep","type":"number","required":false,"defaultValue":"10","description":"The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down."},{"name":"locale","type":"LocalesArgument","required":false,"defaultValue":null,"description":"The locale used by `Intl.NumberFormat` when formatting the value.\nDefaults to the user's runtime locale."},{"name":"max","type":"number","required":false,"defaultValue":"100","description":"The maximum allowed value of the slider.\nShould not be equal to min."},{"name":"min","type":"number","required":false,"defaultValue":"0","description":"The minimum allowed value of the slider.\nShould not be equal to max."},{"name":"minStepsBetweenValues","type":"number","required":false,"defaultValue":"0","description":"The minimum steps between values in a range slider."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"onValueChange","type":"((value: TValue extends number ? number : TValue, eventDetails: SliderRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Callback function that is fired when the slider's value changed.\nReceives the new value as the first argument; the originating event is\navailable as `eventDetails.event`. The value is also reflected on\n`eventDetails.event.target.value` for form integration.\n\nThe `eventDetails.reason` indicates what triggered the change:\n\n- `'input-change'` when the hidden range input emits a change event (for example, via form integration)\n- `'track-press'` when the control track is pressed\n- `'drag'` while dragging a thumb\n- `'keyboard'` for keyboard input\n- `'none'` when the change is triggered without a specific interaction"},{"name":"onValueCommitted","type":"((value: TValue extends number ? number : TValue, eventDetails: SliderRootCommitEventDetails) => void)","required":false,"defaultValue":null,"description":"Callback function that is fired when a value change is committed.\nDoes not fire if the value did not change, or if the change was canceled.\n**Warning**: This is a generic event, not a change event.\n\nThe `eventDetails.reason` indicates what triggered the commit:\n\n- `'drag'` while dragging a thumb\n- `'track-press'` when the control track is pressed\n- `'keyboard'` for keyboard input\n- `'input-change'` when the hidden range input emits a change event (for example, via form integration)\n- `'none'` when the commit occurs without a specific interaction"},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The component orientation."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"step","type":"number","required":false,"defaultValue":"1","description":"The granularity with which the slider can step through values. (A \"discrete\" slider.)\nThe `min` prop serves as the origin for the valid values.\nWe recommend (max - min) to be evenly divisible by the step."},{"name":"style","type":"CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"thumbAlignment","type":"\"center\" | \"edge-client-only\" | \"edge\"","required":false,"defaultValue":"edge","description":"How the thumb(s) are aligned relative to `Slider.Control` when the value is at `min` or `max`:\n- `center`: The center of the thumb is aligned with the control edge\n- `edge`: The thumb is inset within the control such that its edge is aligned with the control edge\n- `edge-client-only`: Same as `edge` but renders after React hydration on the client, reducing bundle size in return"},{"name":"thumbCollisionBehavior","type":"\"none\" | \"push\" | \"swap\"","required":false,"defaultValue":"push","description":"Controls how thumbs behave when they collide during pointer interactions.\n\n- `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back.\n- `'swap'`: Thumbs swap places when dragged past each other.\n- `'none'`: Thumbs cannot move past each other; excess movement is ignored."},{"name":"value","type":"number | readonly number[]","required":false,"defaultValue":null,"description":"The value of the slider.\nFor range sliders, provide an array with one value per thumb."}]},{"name":"Control","props":[{"name":"className","type":"string | ((state: SliderControlState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderControlState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderControlState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Track","props":[{"name":"className","type":"string | ((state: SliderTrackState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderTrackState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderTrackState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: SliderIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Thumb","props":[{"name":"aria-valuetext","type":"string","required":false,"defaultValue":null,"description":"A string value forwarded to the [`aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute of the `input`.\nIgnored when `getAriaValueText` is provided."},{"name":"className","type":"string | ((state: SliderThumbState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the thumb should ignore user interaction."},{"name":"getAriaLabel","type":"((index: number) => string) | null","required":false,"defaultValue":null,"description":"A function which returns a string value for the [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute of the `input`."},{"name":"getAriaValueText","type":"((formattedValue: string, value: number, index: number) => string) | null","required":false,"defaultValue":null,"description":"A function which returns a string value for the [`aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute of the `input`.\nThis is important for screen reader users."},{"name":"index","type":"number","required":false,"defaultValue":null,"description":"The index of the thumb which corresponds to the index of its value in the\n`value` or `defaultValue` array.\nThis prop is required to support server-side rendering for range sliders\nwith multiple thumbs."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the nested input element."},{"name":"onBlur","type":"FocusEventHandler<HTMLInputElement>","required":false,"defaultValue":null,"description":"A blur handler forwarded to the `input`."},{"name":"onFocus","type":"FocusEventHandler<HTMLInputElement>","required":false,"defaultValue":null,"description":"A focus handler forwarded to the `input`."},{"name":"onKeyDown","type":"KeyboardEventHandler<HTMLInputElement>","required":false,"defaultValue":null,"description":"A keydown handler forwarded to the `input`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderThumbState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderThumbState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"tabIndex","type":"number","required":false,"defaultValue":null,"description":"Optional tab index attribute forwarded to the `input`."}]},{"name":"Label","props":[{"name":"className","type":"string | ((state: SliderRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Value","props":[{"name":"className","type":"string | ((state: SliderValueState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderValueState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SliderValueState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Switch","entryPoint":"twenty-ui/primitives/input","content":"---\ntitle: Switch\ndescription: A labeled on or off control with controlled and uncontrolled state.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SwitchReference from '/snippets/ui/generated/input/switch.mdx';\n\n## Overview\n\nUse `Switch` for an on or off preference. Give the control a visible label or an accessible name.\n\n<StoryEmbed\n storyId=\"ui-input-switch-switch--display\"\n title=\"Switch example\"\n height={90}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultChecked` to set the initial checked state. The switch owns subsequent changes.\n\n```tsx\nimport { useId } from 'react';\nimport { Switch } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const NotificationsPreference = () => {\n const switchId = useId();\n\n return (\n <label\n htmlFor={switchId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Switch id={switchId} name=\"notifications\" />\n <Text render={<span />}>Email notifications</Text>\n </label>\n );\n};\n```\n\n## Visual choices\n\nCompare the two sizes in on, off, disabled, read-only, and focus states. Use the enabled examples to try toggling.\n\n<StoryEmbed\n storyId=\"ui-input-switch-switch--catalog\"\n title=\"Visual choices for switch\"\n height={440}\n/>\n\n## Controlled state\n\nPass `checked` and update it with `onCheckedChange` to own the same preference in React state.\n\n```tsx\nimport { useId, useState } from 'react';\nimport { Switch } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const NotificationsPreference = () => {\n const switchId = useId();\n const [checked, setChecked] = useState(false);\n\n return (\n <label\n htmlFor={switchId}\n style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}\n >\n <Switch\n id={switchId}\n name=\"notifications\"\n checked={checked}\n onCheckedChange={setChecked}\n />\n <Text render={<span />}>Email notifications</Text>\n </label>\n );\n};\n```\n\n`onCheckedChange` receives the next boolean and event details. The `size` prop accepts `sm` or `md` and defaults to `md`.\n\nFor a consistent full-width row with an icon, description, and switch, use [SettingsRow](/ui/components/settings/settings-row).\n\n## Keyboard and forms\n\nTab moves focus to the switch; Space toggles it. Clicking its associated label also toggles it. Use `disabled` to prevent interaction or `readOnly` to retain a focusable control whose value cannot be changed.\n\nA named switch submits its value when checked. Use `value` to customize that value, and `uncheckedValue` if the form should also submit a value when it is off.\n\n## Parts and custom content\n\n`Switch` assembles the styled root and its default thumb. Use `Switch.Root` with `Switch.Thumb` to own the thumb content. Root owns state and track appearance; Thumb renders the content you supply.\n\n```tsx\nimport { Switch } from 'twenty-ui/primitives/input';\n\nexport const CustomPreference = () => (\n <Switch.Root aria-label=\"Updates\" defaultChecked>\n <Switch.Thumb></Switch.Thumb>\n </Switch.Root>\n);\n```\n\n`SwitchRootProps` and `SwitchThumbProps` are public types exported from `twenty-ui/primitives/input`. Both parts accept native attributes, handlers, refs, `render`, and state-based `className` and `style` callbacks. Root's `ref` targets the visible control; `inputRef` targets the native input. The part ref targets its rendered element. Pass `nativeButton` with `render={<button />}` when replacing Root with a button. Appearance props belong on Root; explicit classes and styles are merged with the defaults.\n\nThumb receives the current checked, disabled, readOnly, required, and Field state. Its position follows the reading direction.\n\n<StoryEmbed\n storyId=\"ui-input-switch-parts--composition\"\n title=\"Switch part composition\"\n height={90}\n/>\n\nThe callable assembly and its `SwitchProps` type remain supported. Replace the assembly with Root and its part when supplying custom thumb content instead of appending another part to the assembly's children.\n\nFor controlled form reset, handle the form's `onReset` and restore `checked` to your initial value. Base UI 1.8 does not restore uncontrolled component state on native form reset. `required`, `form`, `value`, and `uncheckedValue` keep the upstream native input behavior.\n\n## Props\n\nThe reference includes component-specific and inherited Base UI props. Native attributes such as `aria-label` and `data-*` are also accepted.\n\n<SwitchReference />\n\n<PageBanner illustration=\"page-cover-switch\" />\n","api":{"name":"Switch","entryPoint":"twenty-ui/primitives/input","slug":"input/switch","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the switch is currently active.\n\nTo render an uncontrolled switch, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: SwitchRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the switch is initially active.\n\nTo render a controlled switch, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the switch is rendered outside the form."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the hidden input element.\n\nWhen `nativeButton` is `true`, the id is applied to the root element."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the switch is activated or deactivated."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to activate or deactivate the switch."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must activate the switch before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the switch."},{"name":"style","type":"CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is off.\nBy default, unchecked switches do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is on.\nBy default, switch submits the \"on\" value, matching native checkbox behavior."}],"parts":[{"name":"Root","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the switch is currently active.\n\nTo render an uncontrolled switch, use the `defaultChecked` prop instead."},{"name":"className","type":"string | ((state: SwitchRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the switch is initially active.\n\nTo render a controlled switch, use the `checked` prop instead."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the switch is rendered outside the form."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"The id of the hidden input element.\n\nWhen `nativeButton` is `true`, the id is applied to the root element."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"A ref to access the hidden `<input>` element."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Event handler called when the switch is activated or deactivated."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to activate or deactivate the switch."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must activate the switch before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the switch."},{"name":"style","type":"CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is off.\nBy default, unchecked switches do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is on.\nBy default, switch submits the \"on\" value, matching native checkbox behavior."}]},{"name":"Thumb","props":[{"name":"className","type":"string | ((state: SwitchThumbState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchThumbState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: SwitchThumbState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Breadcrumb","entryPoint":"twenty-ui/primitives/navigation","content":"---\ntitle: Breadcrumb\ndescription: Show a page's location with a trail of ancestor links.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport BreadcrumbReference from '/snippets/ui/generated/navigation/breadcrumb.mdx';\n\n## Overview\n\n`Breadcrumb` renders an ordered navigation trail. It includes decorative separators, link focus styles, and truncation of the final item's label. Items preserve native anchor behavior and support custom routing through `render`. The trail uses medium font weight consistently, including inside headers with a different weight.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--display\"\n title=\"Breadcrumb example\"\n height={100}\n/>\n\n## Usage\n\nPass items in ancestor-to-current order. The navigation landmark defaults to the accessible name `Breadcrumb`; use `aria-label` to localize it or distinguish multiple trails. The final item defaults to `aria-current=\"page\"`, whether it has a destination or displays plain text.\n\n```tsx\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const CompanyBreadcrumb = () => (\n <Breadcrumb\n aria-label=\"Breadcrumb\"\n links={[\n { children: 'Home', href: '/' },\n { children: 'Companies', href: '/companies' },\n { children: 'Acme' },\n ]}\n />\n);\n```\n\nItems with `href` use native anchors. Items without a destination default to text. The `/` separators are decorative, hidden from assistive technology, and outside the links' accessible names. Links follow the browser's normal Tab and Enter behavior, including modifier clicks and opening in a new tab.\n\n## Native item props\n\nEach item accepts native anchor attributes, event handlers, `className`, `style`, and `ref`. For example, pass `target` and `rel` for a new tab, `download` for a file, or `referrerPolicy` to control the request. The item's ref reaches the rendered DOM element.\n\n```tsx\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const ReferenceBreadcrumb = () => (\n <Breadcrumb\n aria-label=\"Reference location\"\n links={[\n {\n children: 'Documentation',\n href: 'https://docs.twenty.com',\n target: '_blank',\n rel: 'noopener noreferrer',\n referrerPolicy: 'no-referrer',\n },\n { children: 'Companies' },\n ]}\n />\n);\n```\n\n## Current page\n\nAn explicit `aria-current` value on an item takes precedence over its position. Use `aria-current=\"page\"` on another item and `aria-current={false}` on the final item when the current page is earlier in the trail. Other native current-item values, such as `step`, are also preserved. Ensure only the intended item is current.\n\n```tsx\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const CompanyContextBreadcrumb = () => (\n <Breadcrumb\n links={[\n { children: 'Home', href: '/' },\n {\n children: 'Companies',\n href: '/companies',\n 'aria-current': 'page',\n },\n { children: 'Acme', 'aria-current': false },\n ]}\n />\n);\n```\n\n## Router links\n\nUse an item's `render` prop to supply your router's link component, alongside `href`. Pass router-specific destinations, state, and history options directly to that component. `render` accepts either an element or a function receiving the supplied props, including native anchor attributes and its ref.\n\nThe rendered link must forward the supplied props and ref to its anchor. Preserve native link behavior when handling navigation, including modifier clicks and new tabs. See [custom components](/ui/primitives/overview#custom-components) for composition requirements.\n\nThe application chooses destinations and decides when to show a mobile back action. `Breadcrumb` does not infer routes or collapse ancestors into a menu.\n\n## Long labels\n\nThe final item shrinks and truncates with an ellipsis when the container has limited space. Ancestor items retain their width. Plain string labels become the native browser tooltip automatically. Use `title` to override that text or provide a tooltip for rich content. Set `title=\"\"` to suppress the automatic tooltip.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--truncation\"\n title=\"Breadcrumb with a long current page label\"\n height={100}\n/>\n\n## Rich content\n\nAn item's `children` can include text and supporting visual content. Keep the label readable and avoid nesting interactive controls inside a link.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--rich-content\"\n title=\"Breadcrumb with supporting content\"\n height={100}\n/>\n\n## Text direction\n\nThe trail follows the surrounding text direction. Set `dir=\"rtl\"` on `Breadcrumb` or an ancestor for right-to-left content. When other controls need matching directional keyboard or pointer behavior, also set [DirectionProvider](/ui/primitives/layout/direction-provider) to the same direction.\n\n<StoryEmbed\n storyId=\"primitives-navigation-breadcrumb--rtl\"\n title=\"Breadcrumb in right-to-left content\"\n height={100}\n/>\n\n## Root customization\n\nNative navigation attributes, including accessible names, `className`, `style`, and event handlers, reach the root landmark. The root ref reaches its `nav` element. Root `render` also accepts an element or function; keep the navigation landmark and forward its supplied props and ref.\n\n```tsx\nimport { useRef } from 'react';\nimport { Breadcrumb } from 'twenty-ui/primitives/navigation';\n\nexport const HeaderBreadcrumb = () => {\n const navigationRef = useRef<HTMLElement>(null);\n const companiesRef = useRef<HTMLAnchorElement>(null);\n\n return (\n <Breadcrumb\n aria-label=\"Company location\"\n ref={navigationRef}\n render={<nav data-location=\"header\" />}\n links={[\n {\n children: 'Companies',\n href: '/companies',\n ref: companiesRef,\n render: (props) => (\n <a {...props} data-route={props.href}>\n {props.children}\n </a>\n ),\n },\n { children: 'Acme' },\n ]}\n />\n );\n};\n```\n\n## Props\n\n<BreadcrumbReference />\n\n<PageBanner illustration=\"card-page-navigation\" />\n","api":{"name":"Breadcrumb","entryPoint":"twenty-ui/primitives/navigation","slug":"navigation/breadcrumb","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible navigation name. Defaults to Breadcrumb; supply a localized name or use aria-labelledby."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged onto the root navigation element."},{"name":"links","type":"BreadcrumbItem[]","required":true,"defaultValue":null,"description":"Ordered trail items with native anchor attributes, event handlers, ref, children and element or callback render composition. Items with href default to anchors; other items default to text. The final item defaults to aria-current=\"page\". An explicit aria-current value is preserved, including false."},{"name":"ref","type":"Ref<HTMLElement>","required":false,"defaultValue":null,"description":"Ref to the root nav, or the DOM element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Preserve the navigation landmark and forward the supplied props and ref."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root navigation element."}]}},{"name":"ListItem","entryPoint":"twenty-ui/primitives/navigation","content":"---\ntitle: ListItem\ndescription: Compose consistent rows with icons, descriptions, indicators, and actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ListItemReference from '/snippets/ui/generated/navigation/list-item.mdx';\n\n## Overview\n\n`ListItem` supplies the visual layout shared by list and menu rows. It renders a `div` by default for passive content. Use [ListItemButton](/ui/components/navigation/list-item-button) for ordinary action rows. Compose `ListItem` with an anchor for navigation or with a custom semantic owner when needed. Use [Dropdown](/ui/components/navigation/dropdown) or [Select](/ui/primitives/input/select) when you need a complete popup or selection owner.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem--display\"\n title=\"ListItem example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { IconBell } from 'twenty-ui/icon';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const NotificationRow = () => (\n <ListItem startIcon={<IconBell />}>Notifications</ListItem>\n);\n```\n\n## Anatomy\n\n`ListItem` exposes content slots through props. These slots arrange content inside one row; they are not separately exported components.\n\n```text\nListItem\n├── startIcon\n├── children\n├── description\n├── actions\n└── endIcon\n```\n\n| Slot | Requirement | Purpose |\n| ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------ |\n| `children` | Required for a visible row label | Supplies the main text. |\n| `startIcon`, `endIcon` | Optional | Add icons, avatars, metadata, or independent controls at either end. |\n| `description` | Optional | Adds supporting content inline, below the label, or at the end. |\n| `actions` | Optional | Adds trailing content, such as a separately focusable action. |\n| `indicator`, `shortcut`, `hasSubmenu` | Optional | Configure built-in selection marks, shortcut hints, and the submenu indicator. |\n\nThe row supplies layout. `render` accepts an element or a callback that receives native props and visual state. Spread those props onto the actual root when using a callback. Native attributes, event handlers, `className`, `style`, and `ref` reach that root. For a row with independent action buttons, keep the row itself non-interactive so those buttons remain separate controls.\n\n## Multiline rows\n\nSet `descriptionPlacement=\"below\"` to place supporting content beneath the label. The title keeps its existing truncation behavior, and supporting content wraps with the available width. The default `inline` placement and the `end` placement retain their existing appearance.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem-multiline--display\"\n title=\"Multiline ListItem example\"\n height={150}\n/>\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const PlanningRow = () => (\n <ListItem\n descriptionPlacement=\"below\"\n startIcon={<Avatar name=\"Alex Morgan\" size=\"md\" imageProps={{ alt: '' }} />}\n description=\"Review the proposed timeline and confirm the next steps with the team.\"\n endIcon={\n <Text render={<span />} size=\"sm\" color=\"secondary\">\n 09:48\n </Text>\n }\n >\n Quarterly planning\n </ListItem>\n);\n```\n\nFor shorter previews, pass a [Text](/ui/primitives/typography/text) component with `truncate` or `lineClamp` as `description`. Custom content controls its own layout and accessible labels.\n\n### Independent visual states\n\nAll visual state belongs to the caller. `active` identifies the open or current row without selecting it. `selected` represents selection, and `focused` represents a keyboard navigation highlight without moving DOM focus. `active` applies the current-row background. Set `selectionAppearance=\"accent\"` for an accent fill on selected rows, independently of description placement. The default appearance preserves the existing indicator-based selection styling. `focused` applies the shared highlighted background, including when an owner uses it for pointer highlighting. The focus-visible outline follows actual keyboard focus on the root or its controls.\n\nThese props do not add accessible states. Supply `aria-current`, `aria-selected`, or a control's `checked` state on the appropriate semantic owner. Actual keyboard focus also retains the native focus-visible outline.\n\n### Independent controls\n\nKeep the default `div` root when a row contains a real checkbox or independent action buttons. Use `startIcon` for the checkbox and `actions` for buttons. The decorative `indicator` is unnecessary when a real checkbox already displays selection.\n\n```tsx\nimport { useState } from 'react';\nimport { Button, Checkbox } from 'twenty-ui/primitives/input';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\ntype SelectablePlanningRowProps = {\n active?: boolean;\n disabled?: boolean;\n onOpen: () => void;\n};\n\nexport const SelectablePlanningRow = ({\n active = false,\n disabled = false,\n onOpen,\n}: SelectablePlanningRowProps) => {\n const [selected, setSelected] = useState(false);\n\n return (\n <ListItem\n active={active}\n selected={selected}\n selectionAppearance=\"accent\"\n disabled={disabled}\n descriptionPlacement=\"below\"\n description=\"Review the proposed timeline and confirm the next steps with the team.\"\n startIcon={\n <Checkbox\n aria-label=\"Select quarterly planning\"\n checked={selected}\n onCheckedChange={setSelected}\n disabled={disabled}\n />\n }\n actions={\n <Button variant=\"ghost\" size=\"sm\" onClick={onOpen} disabled={disabled}>\n Open\n </Button>\n }\n >\n Quarterly planning\n </ListItem>\n );\n};\n```\n\nSelection and opening are separate interactions. The application owns event propagation and any row activation or keyboard policy. `ListItem.disabled` changes appearance only; pass `disabled` to each real control to prevent its activation.\n\nThe existing action visibility behavior applies to multiline rows: `actionsVisibility=\"hover\"` reveals actions on hover or focus within the row and keeps them visible on touch devices. Set it to `always` for persistent actions, including while a caller-owned popup is open. At row widths of 480px or less, multiline actions move to their own line and wrap as needed.\n\n## Action row\n\nUse [ListItemButton](/ui/components/navigation/list-item-button) to pair row styling with native button interaction. Pass `disabled` once to control both appearance and activation.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\n\ntype DuplicateActionProps = {\n onDuplicate: () => void;\n disabled?: boolean;\n};\n\nexport const DuplicateAction = ({\n onDuplicate,\n disabled = false,\n}: DuplicateActionProps) => (\n <ListItemButton\n disabled={disabled}\n startIcon={<IconCopy />}\n description=\"Create a copy\"\n onClick={onDuplicate}\n >\n Duplicate\n </ListItemButton>\n);\n```\n\nA custom button owner can still compose `ListItem` through `render`. That owner supplies native focus, Enter and Space activation, and disabled behavior. `ListItem.disabled` supplies only the matching visual style. `shortcut` displays hints; your application registers the shortcuts.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem--button-owner\"\n title=\"Custom button composition\"\n height={100}\n/>\n\n## Navigation and explicit links\n\nPass an anchor through `render` when the entire row navigates. Put anchor attributes, including `href`, `target`, and `rel`, on that element.\n\n```tsx\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const DocumentationLink = () => (\n <ListItem render={<a href=\"https://twenty.com/developers\" />}>\n Typography documentation\n </ListItem>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem--link-owner\"\n title=\"Link row\"\n height={100}\n/>\n\nString labels stay text, including URL-shaped strings. ListItem does not create links. To link part of a non-interactive row, supply an anchor as caller-owned content. Keep that row as a `div` to avoid nested links or buttons. String labels retain their truncation and overflow tooltip; custom content can use [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip) with an explicit rendered anchor.\n\nLinks do not have a native `disabled` attribute. If a destination is unavailable, the link owner must supply the appropriate semantics, tab order, and navigation policy. Styling it with `ListItem.disabled` alone does not prevent navigation.\n\n## Popup item owner\n\nUse `Dropdown.ActionItem` or `Dropdown.OptionItem` inside their popup owner. These parts already compose the ListItem layout and expose its visual slots. The popup owner supplies roles, focus, keyboard navigation, activation, and disabled behavior.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\ntype RecordActionsProps = { onDuplicate: () => void };\n\nexport const RecordActions = ({ onDuplicate }: RecordActionsProps) => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Record actions</Button>} />\n <Dropdown.Content>\n <Dropdown.ActionItem onClick={onDuplicate}>\n Duplicate record\n </Dropdown.ActionItem>\n <Dropdown.ActionItem disabled>Unavailable action</Dropdown.ActionItem>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--display\"\n title=\"Dropdown item owner\"\n height={420}\n/>\n\n## Native event policy\n\nListItem forwards native event objects and handlers. Clicks bubble normally, including clicks on trailing action controls. Put any intentional boundary on the interactive owner or caller's handler.\n\n```tsx\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\ntype OpenRecordProps = { onOpen: () => void };\n\nexport const OpenRecord = ({ onOpen }: OpenRecordProps) => (\n <ListItem\n render={<button type=\"button\" />}\n onClick={(event) => {\n event.stopPropagation();\n onOpen();\n }}\n >\n Open record\n </ListItem>\n);\n```\n\nThe caller also owns any `preventDefault()` policy, such as preventing a link's navigation. Passing `onClick` does not add a role, make a `div` keyboard-operable, or change propagation.\n\n## Application-owned drag and editor navigation\n\nCompose reorderable rows with `ListItem` inside your application's drag host. Put the host's drag attributes and listeners on its handle, and pass the handle or grip through `startIcon`. Keep independent visibility, edit and delete controls in `actions`. The drag host owns pointer and keyboard reordering, disabled dragging and accessible handle labels.\n\nFor editor suggestions, keep the editor's existing listbox and active option owner. Render each `ListItem` with `role=\"option\"` and `aria-selected`, and use `focused` for the active row's appearance. The editor owns arrow navigation and Enter activation while focus stays in the editing surface. Prevent pointer-down focus changes when the editor requires them, and handle pointer selection in the application's row handler.\n\nFor suggestions in a Dropdown page, use `Dropdown.OptionItem` or `Dropdown.ActionItem` so that page owns navigation and activation. Do not add a second Enter or Space handler to an owner that already activates from the keyboard.\n\n## Settings row\n\nUse [SettingsRow](/ui/components/settings/settings-row) for a labeled switch row. It composes `ListItem` and `Switch`, manages their accessible association, and uses the switch’s disabled state for the row’s appearance.\n\n## Selection indicator\n\n```tsx\nimport { useState } from 'react';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const ShowArchivedToggle = () => {\n const [selected, setSelected] = useState(false);\n\n return (\n <ListItem\n render={<button type=\"button\" aria-pressed={selected} />}\n selected={selected}\n indicator=\"check\"\n onClick={() => setSelected(!selected)}\n >\n Show archived records\n </ListItem>\n );\n};\n```\n\n`active`, `selected`, `focused`, and `disabled` independently control row styling. They do not register actions, move DOM focus, add accessible roles or states, or suppress events. The `check` and `checkbox` indicators are decorative; use a real [Checkbox](/ui/primitives/input/checkbox) for a form control. Set `aria-pressed`, `aria-selected`, or other state semantics on the owner that needs them.\n\n## Picker rows\n\nSelection belongs to the parent. `ListItem` has no uncontrolled selection state: pass `selected` and update it from `onClick`. Use `indicator=\"check\"` for a single choice and `indicator=\"checkbox\"` for multiple choices. Both indicators are decorative; the interactive owner handles activation.\n\nIn an existing listbox, pass `role=\"option\"` and `aria-selected`, and keep focus and arrow-key handling in the listbox. For a complete selection widget, use [Select](/ui/primitives/input/select). Standalone selection buttons can use `aria-pressed`, as in these examples.\n\n### Single selection\n\nPlace an [Avatar](/ui/primitives/data-display/avatar) in `startIcon` to identify a record. Use `description` for supporting text, and `descriptionPlacement=\"end\"` for a trailing value.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem-picker--single-selection\"\n title=\"Single selection rows\"\n height={170}\n/>\n\n```tsx\nimport { useState } from 'react';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const AssigneeButtons = () => {\n const [assignee, setAssignee] = useState<string | null>(null);\n\n return (\n <div role=\"group\" aria-label=\"Assignee\">\n {['Alex Morgan', 'Sam Taylor'].map((name) => (\n <ListItem\n key={name}\n render={<button type=\"button\" />}\n aria-pressed={assignee === name}\n selected={assignee === name}\n indicator=\"check\"\n startIcon={<Avatar name={name} size=\"md\" imageProps={{ alt: '' }} />}\n onClick={() => setAssignee(name)}\n >\n {name}\n </ListItem>\n ))}\n </div>\n );\n};\n```\n\n### Multiple selection\n\nCompose [Tag](/ui/primitives/data-display/tag) as the row content for tagged values, or put [ColorSample](/ui/primitives/data-display/color-sample) in `startIcon` for a color choice. A row can also contain plain text or an avatar.\n\n<StoryEmbed\n storyId=\"ui-navigation-listitem-picker--multiple-selection\"\n title=\"Multiple selection rows\"\n height={170}\n/>\n\n```tsx\nimport { useState } from 'react';\nimport { Tag } from 'twenty-ui/primitives/data-display';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\nexport const TeammateButtons = () => {\n const [teammates, setTeammates] = useState<string[]>([]);\n\n const toggleTeammate = (name: string) => {\n setTeammates((current) =>\n current.includes(name)\n ? current.filter((teammate) => teammate !== name)\n : [...current, name],\n );\n };\n\n return (\n <div role=\"group\" aria-label=\"Teammates\">\n {['Alex Morgan', 'Sam Taylor'].map((name) => (\n <ListItem\n key={name}\n render={<button type=\"button\" />}\n aria-pressed={teammates.includes(name)}\n selected={teammates.includes(name)}\n indicator=\"checkbox\"\n onClick={() => toggleTeammate(name)}\n >\n <Tag color=\"blue\">{name}</Tag>\n </ListItem>\n ))}\n </div>\n );\n};\n```\n\nThe checkbox indicator is not a form control and does not submit a value. Use [Checkbox](/ui/primitives/input/checkbox) when you need form participation. Set native `disabled` on the rendered button to prevent activation and remove it from the tab order. Also pass `ListItem.disabled` for its visual appearance.\n\n## Slots\n\nUse `startIcon` and `endIcon` for icons or caller-owned content, `description` for supporting text, `actions` for trailing content, and `hasSubmenu` for a submenu indicator. `descriptionPlacement` accepts `inline`, `end`, or `below`. `color=\"danger\"` styles a destructive action. Avoid nesting interactive controls inside a row rendered as a button.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ListItem } from 'twenty-ui/primitives/navigation';\n\ntype ContactRowProps = { onOpen: () => void };\n\nexport const ContactRow = ({ onOpen }: ContactRowProps) => (\n <ListItem\n description=\"Account owner\"\n actions={\n <Button\n type=\"button\"\n aria-label=\"Open Alex Morgan's profile\"\n variant=\"ghost\"\n size=\"sm\"\n onClick={onOpen}\n >\n Open\n </Button>\n }\n >\n Alex Morgan\n </ListItem>\n);\n```\n\n## Labels\n\nUse `shortcutJoinLabel` to customize the text between sequential shortcut steps. It defaults to `then`; an empty string removes the join text. The same prop is available on `Dropdown` item parts.\n\n## Props\n\nThe reference is generated from the public component types. Native `div` attributes and handlers are accepted, including accessible names and native events. Put button- or anchor-specific attributes on the element supplied through `render`. Both `ref` and the rendered element's ref target the actual DOM root.\n\n<ListItemReference />\n\nPass `shortcut={['Mod', 'Enter']}` for simultaneous keys or `shortcut={[['G'], ['P']]}` for successive presses. See [Shortcut](/ui/primitives/typography/shortcut) for nested combinations and the shared string formatter.\n\n<PageBanner illustration=\"section-apps-data\" />\n","api":{"name":"ListItem","entryPoint":"twenty-ui/primitives/navigation","slug":"navigation/list-item","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Trailing content, such as buttons, rendered after the content."},{"name":"actionsPlacement","type":"\"auto\" | \"end\"","required":false,"defaultValue":"auto","description":"Keeps actions beside the content at every width when set to `end`. The default `auto` preserves responsive wrapping. Hidden end actions do not reserve width on devices without touch."},{"name":"actionsVisibility","type":"\"always\" | \"hover\"","required":false,"defaultValue":"hover","description":"When trailing actions are visible: on hover and focus, or always."},{"name":"active","type":"boolean","required":false,"defaultValue":"false","description":"Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":"neutral","description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":"inline","description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Applies disabled styling only. Set native disabled behavior and accessible semantics on the button, link, or popup item owner."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focused","type":"boolean","required":false,"defaultValue":"false","description":"Applies highlighted styling without moving DOM focus or handling keyboard navigation."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":"false","description":"Shows a chevron indicating that the item opens a submenu."},{"name":"indicator","type":"\"check\" | \"checkbox\" | \"none\"","required":false,"defaultValue":"none","description":"Selection indicator: a check icon after the content or a checkbox before\nit."},{"name":"ref","type":"Ref<HTMLElement>","required":false,"defaultValue":null,"description":"Ref to the actual DOM root, including a composed native button or link."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ListItemState>","required":false,"defaultValue":null,"description":"Composes the row with an element or render callback. The owner supplies interaction semantics, native attributes, and behavior."},{"name":"selected","type":"boolean","required":false,"defaultValue":"false","description":"Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner."},{"name":"selectionAppearance","type":"\"accent\" | \"default\"","required":false,"defaultValue":"default","description":"Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`; pass an empty string to omit it."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."}]}},{"name":"Tabs","entryPoint":"twenty-ui/primitives/navigation","content":"---\ntitle: Tabs\ndescription: Switch between related panels with accessible tab navigation.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TabsReference from '/snippets/ui/generated/navigation/tabs.mdx';\n\n## Overview\n\n`Tabs` connects each tab to a related content panel using a shared `value`. Keep values unique within a root. Use [TabButton](/ui/components/navigation/tab-button) for route links and adjacent actions.\n\n<StoryEmbed\n storyId=\"ui-navigation-tabs--display\"\n title=\"Tabs example\"\n height={160}\n/>\n\n## Usage\n\nUse `defaultValue` to set the initial selection. The root owns subsequent changes.\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const RecordTabs = () => (\n <Tabs.Root defaultValue=\"overview\">\n <Tabs.List aria-label=\"Record details\">\n <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n <Tabs.Tab value=\"activity\">Activity</Tabs.Tab>\n <Tabs.Tab value=\"settings\">Settings</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"overview\">Record overview</Tabs.Panel>\n <Tabs.Panel value=\"activity\">Recent activity</Tabs.Panel>\n <Tabs.Panel value=\"settings\">Record settings</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\n`Tabs.Tab` accepts `startIcon`, `endIcon`, `badge`, and a `size` of `compact`, `sm`, or `md` (default `sm`). The remaining props retain the installed Base UI contract. Values are not restricted to strings or numbers. Reference values must use the same identity on their tab, panel, and root. A root value of `null` selects no panel.\n\n### Compact tabs\n\nUse `size=\"compact\"` on each tab for short Input/Output controls inside a card. Compact tabs have a 24px minimum row height, small text, and 4px content padding on each side. The existing `sm` and `md` sizes keep their 40px minimum height. Compact tabs use the same indicator, focus ring, and keyboard activation as the other sizes.\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const ToolCallTabs = () => (\n <Tabs.Root defaultValue=\"output\">\n <Tabs.List aria-label=\"Tool call details\">\n <Tabs.Tab value=\"output\" size=\"compact\">Output</Tabs.Tab>\n <Tabs.Tab value=\"input\" size=\"compact\">Input</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"output\">Tool output</Tabs.Panel>\n <Tabs.Panel value=\"input\">Tool input</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-navigation-tabs--compact\"\n title=\"Compact Input and Output tabs\"\n height={110}\n/>\n\n## Anatomy\n\nPlace tabs and an optional indicator inside `Tabs.List`. Place their panels alongside the list, all within the same `Tabs.Root`.\n\n```text\nTabs.Root\n├── Tabs.List\n│ ├── Tabs.Tab\n│ ├── Tabs.Tab\n│ └── Tabs.Indicator\n├── Tabs.Panel\n└── Tabs.Panel\n```\n\n| Part | Requirement | Purpose |\n| ----------- | -------------------- | --------------------------------------------------------- |\n| `Root` | Required | Owns the selected value and orientation. |\n| `List` | Required | Groups tabs and supplies keyboard focus navigation. |\n| `Tab` | One per panel | Activates the panel with the same `value`. |\n| `Panel` | One per content view | Displays its content when its `value` is active. |\n| `Indicator` | Optional | Shows the position of the active tab with themed styling. |\n\nGive the list an accessible name and match each tab's `value` to its panel's `value`. Base UI supplies the tab and panel IDs, `aria-controls`, and `aria-labelledby` relationships.\n\nWhen you provide a custom `id` on `Tabs.Panel`, set `aria-controls` on the matching `Tabs.Tab` to that same ID. The installed Base UI 1.8.0 implementation requires this explicit relationship. Custom tab IDs are registered correctly for the panel's `aria-labelledby`.\n\nAdd one `Tabs.Indicator` when you want the active underline. `List` does not insert an indicator.\n\n## Controlled state and event details\n\nPass `value` and update it with `onValueChange` to own selection. The callback receives the next value and Base UI event details, including the originating `event`, `reason`, `activationDirection`, and `cancel()`.\n\n```tsx\nimport { useState } from 'react';\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const RecordTabs = () => {\n const [tab, setTab] = useState('overview');\n\n return (\n <Tabs.Root value={tab} onValueChange={setTab}>\n <Tabs.List aria-label=\"Record details\">\n <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n <Tabs.Tab value=\"activity\" badge={3}>\n Activity\n </Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"overview\">Company and contact details.</Tabs.Panel>\n <Tabs.Panel value=\"activity\">Recent calls and emails.</Tabs.Panel>\n </Tabs.Root>\n );\n};\n```\n\nUser activation has reason `none`. In uncontrolled roots, automatic fallback can have reason `initial`, `disabled`, or `missing`. Automatic fallback may select `null` when no enabled tab remains. These automatic changes cannot be canceled. Controlled roots keep selection under the application's ownership.\n\nCancel a user change before updating controlled state, or use the same callback with an uncontrolled root:\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const ProtectedTabs = () => (\n <Tabs.Root\n defaultValue=\"overview\"\n onValueChange={(value, details) => {\n if (value === 'restricted') {\n details.cancel();\n }\n }}\n >\n <Tabs.List aria-label=\"Account sections\">\n <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n <Tabs.Tab value=\"restricted\">Restricted</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"overview\">Account details.</Tabs.Panel>\n <Tabs.Panel value=\"restricted\">Restricted content.</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\n## Keyboard activation, orientation, and direction\n\n`Tabs.List` uses manual activation by default (`activateOnFocus={false}`). Arrow keys move focus; Enter or Space activates the focused tab. Set `activateOnFocus` to select a tab when keyboard focus reaches it. Both policies work with controlled and uncontrolled state.\n\n```tsx\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const SettingsTabs = () => (\n <Tabs.Root defaultValue=\"profile\" orientation=\"vertical\">\n <Tabs.List aria-label=\"Settings\" activateOnFocus loopFocus={false}>\n <Tabs.Tab value=\"profile\">Profile</Tabs.Tab>\n <Tabs.Tab value=\"billing\" disabled>\n Billing\n </Tabs.Tab>\n <Tabs.Tab value=\"notifications\">Notifications</Tabs.Tab>\n <Tabs.Indicator />\n </Tabs.List>\n <Tabs.Panel value=\"profile\">Profile settings.</Tabs.Panel>\n <Tabs.Panel value=\"billing\">Billing settings.</Tabs.Panel>\n <Tabs.Panel value=\"notifications\">Notification settings.</Tabs.Panel>\n </Tabs.Root>\n);\n```\n\nHorizontal lists use Left and Right; vertical lists use Up and Down. Home and End focus the first and last enabled tabs. Disabled tabs are skipped. `loopFocus` defaults to `true`; set it to `false` to stop at either boundary.\n\nUse [DirectionProvider](/ui/primitives/layout/direction-provider) for RTL keyboard direction and `dir=\"rtl\"` on the root for layout. Set `orientation=\"vertical\"` on `Root` for a vertical list and indicator.\n\n## Panel lifetime\n\nUse `keepMounted` when panel contents must retain their state while inactive. Inactive mounted panels remain hidden and do not occupy layout space.\n\n## Panel layout\n\n`Panel` fills the space left by the list and can shrink below its content on both axes, so it stays within a root of fixed height. To scroll its content, set `overflow: auto` on the panel, or on a child that fills it, such as a `flex: 1` child of a column flex panel.\n\n## Native props, render composition, and refs\n\nAll five parts preserve native props, event handlers, refs, and Base UI `render` composition. Their `className` and `style` can also be functions of the part's state. The default elements are a `div` for Root, List, and Panel, a `button` for Tab, and a `span` for Indicator. Refs point to the actual rendered elements.\n\n```tsx\nimport { useRef } from 'react';\nimport { Tabs } from 'twenty-ui/primitives/navigation';\n\nexport const ComposedTabs = () => {\n const panelRef = useRef<HTMLElement>(null);\n\n return (\n <Tabs.Root defaultValue=\"overview\" render={<section />}>\n <Tabs.List aria-label=\"Account details\">\n <Tabs.Tab value=\"overview\" nativeButton render={<button />}>\n Overview\n </Tabs.Tab>\n <Tabs.Indicator render={<span data-testid=\"active-indicator\" />} />\n </Tabs.List>\n <Tabs.Panel\n value=\"overview\"\n render={<article />}\n ref={(element) => {\n panelRef.current = element;\n }}\n >\n Account details.\n </Tabs.Panel>\n </Tabs.Root>\n );\n};\n```\n\nKeep `nativeButton` consistent with the element composed for a tab. Use `nativeButton={false}` for a custom interactive element that is not a native button and forwards the supplied props and ref. A route anchor belongs in `TabButton`, where the route owns navigation and `aria-current`.\n\n## Visual emphasis\n\nUse `highlighted` on `Tabs.Tab` to outline its content independently of selection, such as when its settings are open. Selection remains owned by `Tabs.Root`.\n\n## Props\n\nThe generated reference includes the public props for every part. Public part state types and Root change detail/reason types are available from `twenty-ui/primitives/navigation`.\n\n<TabsReference />\n\n## Migration\n\nAdd an explicit `Tabs.Indicator` to lists that should retain the active underline. Remove duplicate indicators from compositions that previously relied on `List` inserting one. Keep route links, create controls, and overflow controls outside `Tabs.List`, whose children select related panels.\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Tabs","entryPoint":"twenty-ui/primitives/navigation","slug":"navigation/tabs","props":[],"parts":[{"name":"Root","props":[{"name":"className","type":"string | ((state: TabsRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"any","required":false,"defaultValue":"0","description":"The default value. Use when the component is not controlled.\nWhen the value is `null`, no Tab will be active."},{"name":"onValueChange","type":"((value: any, eventDetails: TabsRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Callback invoked when new value is being set.\n\nThe event `reason` is `'none'` for user-initiated changes, such as a click\nor keyboard navigation; `'initial'` for the first automatic selection or\nfallback in uncontrolled roots when `defaultValue` is omitted or\n`undefined`, including when the implicit initial value is disabled or\nmissing; `'disabled'` for automatic fallback when the selected tab becomes\ndisabled in uncontrolled roots; or `'missing'` for automatic fallback when\nthe selected tab is removed, or when an explicit `defaultValue` never\nmatches a mounted tab in uncontrolled roots.\n\nFor automatic changes, the selected value can be `null` when no enabled Tab\nis available as a fallback.\n\nAutomatic changes cannot be canceled; calling `eventDetails.cancel()` for\n`'initial'`, `'disabled'`, or `'missing'` has no effect."},{"name":"orientation","type":"\"horizontal\" | \"vertical\"","required":false,"defaultValue":"horizontal","description":"The component orientation (layout flow direction)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsRootState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TabsRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":false,"defaultValue":null,"description":"The value of the currently active `Tab`. Use when the component is controlled.\nWhen the value is `null`, no Tab will be active."}]},{"name":"List","props":[{"name":"activateOnFocus","type":"boolean","required":false,"defaultValue":"false","description":"Whether to automatically change the active tab on arrow key focus.\nOtherwise, tabs will be activated using <kbd>Enter</kbd> or <kbd>Space</kbd> key press."},{"name":"className","type":"string | ((state: TabsListState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"loopFocus","type":"boolean","required":false,"defaultValue":"true","description":"Whether to loop keyboard focus back to the first item\nwhen the end of the list is reached while using the arrow keys."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsListState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TabsListState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Tab","props":[{"name":"badge","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered after the label, such as a count."},{"name":"className","type":"string | ((state: TabsTabState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Whether the Tab is disabled.\n\nIf a first Tab on a `<Tabs.List>` is disabled, it won't initially be selected.\nInstead, the next enabled Tab will be selected.\nHowever, it does not work like this during server-side rendering, as it is not known\nduring pre-rendering which Tabs are disabled.\nTo work around it, ensure that `defaultValue` or `value` on `<Tabs.Root>` is set to an enabled Tab's value."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content after the label and before the badge."},{"name":"highlighted","type":"boolean","required":false,"defaultValue":"false","description":"Emphasizes the tab content without changing selection."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsTabState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"compact\" | \"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual tab size. Compact uses a 24px minimum height, small text, and 4px content padding; sm and md keep a 40px minimum height."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the label."},{"name":"style","type":"CSSProperties | ((state: TabsTabState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":true,"defaultValue":null,"description":"The value of the Tab."}]},{"name":"Indicator","props":[{"name":"className","type":"string | ((state: TabsIndicatorState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsIndicatorState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"renderBeforeHydration","type":"boolean","required":false,"defaultValue":"false","description":"Whether to render itself before React hydrates.\nThis minimizes the time that the indicator isn't visible after server-side rendering."},{"name":"style","type":"CSSProperties | ((state: TabsIndicatorState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Panel","props":[{"name":"className","type":"string | ((state: TabsPanelState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the HTML element in the DOM while the panel is hidden."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsPanelState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TabsPanelState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"any","required":true,"defaultValue":null,"description":"The value of the TabPanel. It will be shown when the Tab with the corresponding value is active."}]}]}},{"name":"Card","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Card\ndescription: Group related information inside a bordered surface.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CardReference from '/snippets/ui/generated/surfaces/card.mdx';\n\n## Overview\n\n`Card` groups related information and actions under one named export. Compose `Card.Root`, `Card.Header`, `Card.Content`, and `Card.Footer` to separate a title, body, and supporting actions. The parts do not manage selection, focus, or application state. The application owns the behavior of any controls placed inside them.\n\n<StoryEmbed\n storyId=\"ui-surfaces-card--display\"\n title=\"Card example\"\n height={200}\n/>\n\n## Usage\n\n```tsx\nimport { useId } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Heading, Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportSummary = () => {\n const titleId = useId();\n\n return (\n <Card.Root fullWidth role=\"region\" aria-labelledby={titleId}>\n <Card.Header>\n <Heading id={titleId} level={2}>\n Import summary\n </Heading>\n </Card.Header>\n <Card.Content>\n <Text>24 records are ready to import.</Text>\n </Card.Content>\n <Card.Footer>\n <Button>Review records</Button>\n </Card.Footer>\n </Card.Root>\n );\n};\n```\n\nUse [Heading](/ui/primitives/typography/heading) at the level required by the surrounding page. Put actions in [Button](/ui/primitives/input/button) or a native link so keyboard and assistive-technology users can activate them.\n\n## Anatomy\n\n```text\nCard.Root (outer surface)\n├── Card.Header (optional)\n├── Card.Content (optional, repeatable)\n├── Card.Footer (optional)\n├── Card.Action (optional, inside an action area)\n└── Card.Control (optional, independent control or tooltip target)\n```\n\nImport `Card` from `twenty-ui/primitives/surfaces`. `Card.Root` supplies the outer border and clipping, but creates no sections internally. No part requires another part or a particular section order. The sections also work independently, without `Card.Root` or context.\n\nRoot, Header, Content and Footer render a `div` by default and accept native div attributes, event handlers, `className`, `style`, and a DOM `ref`. Action renders a native button with `type=\"button\"`, and Control renders a span. Use `render` with an element or callback to choose a semantic target. No part infers an element or role from `onClick`.\n\n`CardRootProps`, `CardHeaderProps`, `CardContentProps`, `CardFooterProps`, `CardActionProps`, and `CardControlProps` are exported from `twenty-ui/primitives/surfaces`, `twenty-ui/primitives`, and the root package.\n\n## Appearance and dividers\n\n`Card.Root` has a transparent background by default. `fullWidth` fills its container, and `backgroundColor` changes the outer background. Child sections have their own backgrounds.\n\n`Card.Header` has a primary background, padding, and a bottom border. `Card.Content` has a secondary background and padding; its optional `divider` adds a bottom border. `Card.Footer` has a primary background, padding, and a top border unless `divider={false}`. Avoid adding two borders at the same section boundary.\n\n```tsx\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportSections = () => (\n <Card.Root>\n <Card.Content divider>\n <Text>24 records are ready to import.</Text>\n </Card.Content>\n <Card.Content divider>\n <Text>3 records need review.</Text>\n </Card.Content>\n <Card.Footer divider={false}>\n <Text>Last checked just now.</Text>\n </Card.Footer>\n </Card.Root>\n);\n```\n\n## Interactive composition\n\nChoose a native button for an action or an anchor for navigation through `render`. Supply target-specific attributes such as `type`, `disabled`, `href`, and `target` on that element. The actual owner supplies its keyboard, focus, disabled, and link behavior. Card does not add those behaviors to a display `div`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype ReviewCardProps = {\n disabled?: boolean;\n onReview: () => void;\n onDismiss: () => void;\n};\n\nexport const ReviewCard = ({\n disabled,\n onReview,\n onDismiss,\n}: ReviewCardProps) => (\n <Card.Root>\n <Card.Content\n render={<button type=\"button\" disabled={disabled} />}\n onClick={onReview}\n >\n <Text render={<span />}>Review 24 ready records</Text>\n </Card.Content>\n <Card.Footer>\n <Button onClick={onDismiss}>Dismiss</Button>\n </Card.Footer>\n </Card.Root>\n);\n```\n\nThe action and dismiss button are siblings inside a display card. Do not place another button, link, input, or other interactive control inside a button or link owner. When a button contains Card parts, render those parts as phrasing elements such as `span`.\n\n```tsx\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportLinkCard = () => (\n <Card.Root render={<a href=\"/imports\" />} fullWidth>\n <Card.Content>\n <Text>View imports</Text>\n </Card.Content>\n </Card.Root>\n);\n```\n\nNative button and link owners retain the card layout and get a visible focus outline. Explicit button and link owners highlight on hover. Disabled owners keep their disabled appearance. Custom owners must supply their interaction behavior, including keyboard activation and disabled handling when applicable.\n\n## Stretched actions and independent controls\n\nUse `Card.Action` when one primary action covers a card section that also contains independent controls. Place the action directly inside Card.Root, Card.Header, Card.Content or Card.Footer. That immediate part defines the stretched area. Keep one primary action per area, and keep expanded forms or other independent sections outside it.\n\n`Card.Action` is a native button by default. Give an empty action an accessible name with `aria-label` or `aria-labelledby`, and use `aria-describedby` for supporting text. A native anchor or router link supplied through `render` keeps its own navigation, target, modifier-click and context-menu behavior. Custom owners receive no synthetic button role, keyboard handler or tab stop. Put target-specific native attributes on the rendered element.\n\n`Card.Control` lifts an independent control or tooltip target above the stretched action. Compose its existing element through `render` to keep its layout and attributes. Controls stay siblings of the primary action, rather than children of a button or link. Card does not infer which descendants are interactive and does not forward their clicks to the primary action. Applications own any additional handling needed for raised plain text.\n\n```tsx\nimport { useId } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Card } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const CustomerImportActions = () => {\n const titleId = useId();\n\n return (\n <Card.Root>\n <Card.Content>\n <Card.Action\n aria-labelledby={titleId}\n render={<a href=\"/imports/review\" />}\n />\n <Text id={titleId}>Review customer import</Text>\n <Card.Control render={<Button variant=\"ghost\" />}>\n Import options\n </Card.Control>\n </Card.Content>\n </Card.Root>\n );\n};\n```\n\nEnabled action areas use the shared Card hover color, including when an independent control is hovered. A nested action area owns its highlight and does not highlight its ancestors. Native button and link actions show a 2px inset focus outline around the stretched area. A disabled native button is removed from keyboard navigation and its area does not highlight, including a button supplied through `render`. Links and controls associated through labels remain responsible for their own disabled behavior; the Action `disabled` prop also suppresses the shared action-area treatment.\n\nFor a Switch or Radio row, render Action as `<label htmlFor={controlId} />` and give the actual control that ID. Keep its visible label and accessible description associated with the control. The label creates no additional keyboard target or focus ring. Switch and Radio retain their own focus and keyboard behavior. Put a radio option's expanded form in a separate Card.Content so the label covers only its selection header.\n\n<StoryEmbed\n storyId=\"ui-surfaces-card-interactions--stretched-actions\"\n title=\"Stretched actions with independent controls\"\n height={360}\n/>\n\n## Independent parts and custom wrappers\n\nA section can be used without the outer surface. Wrappers can use its exported props type and spread it to preserve native attributes, event handlers, refs, render composition, classes, and styles. With a custom target, put its target-specific ref on the supplied element. Base UI merges that ref with the part ref and composed props.\n\n```tsx\nimport { Card, type CardContentProps } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\ntype SummaryContentProps = CardContentProps;\n\nconst SummaryContent = ({ children, ...props }: SummaryContentProps) => (\n <Card.Content {...props}>{children}</Card.Content>\n);\n\nexport const StandaloneSummary = () => (\n <SummaryContent aria-label=\"Import summary\" style={{ maxWidth: 360 }}>\n <Text>24 records are ready to import.</Text>\n </SummaryContent>\n);\n```\n\n## Migration\n\nReplace the four separate imports with `import { Card } from 'twenty-ui/primitives/surfaces'`. The root package and `twenty-ui/primitives` also export the same `Card` object.\n\n| Previous API | Compound API |\n| ----------------------------- | ---------------------------------- |\n| `Card` as a component | `Card.Root` |\n| `CardHeader` | `Card.Header` |\n| `CardContent` | `Card.Content` |\n| `CardFooter` | `Card.Footer` |\n| `ComponentProps<typeof Card>` | `ComponentProps<typeof Card.Root>` |\n| `styled(Card)` | `styled(Card.Root)` |\n\nApply the same member names to JSX tags, styled wrappers, and prop types. Standalone part exports are removed without compatibility aliases. Layout props, styling defaults, and independent section use remain. Replace `isClickable` and `hasHoverHighlight` with an explicit native owner through `render`. Move action handlers off display-only wrappers, preserve accessible names, and keep nested controls outside the primary action. Use `render={<button type=\"button\" disabled={disabled} />}` for an action and `render={<a href=\"/imports\" />}` for navigation. DOM refs now point to the actual rendered part.\n\n## Props\n\n<CardReference />\n\n<PageBanner illustration=\"section-ui-primitives\" />\n","api":{"name":"Card","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/card","props":[],"parts":[{"name":"Root","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"CSS background color of the outer card. Child sections have their own backgrounds."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Card sections or other content."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Sets the card width to 100% of its container."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."},{"name":"variant","type":"\"compact\" | \"default\"","required":false,"defaultValue":"default","description":"default keeps the standard section appearance. compact uses secondary section backgrounds, 8px header and footer padding, 8px horizontal content padding without vertical padding, and no header divider."}]},{"name":"Action","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional content inside the stretched action. Supply an accessible name for empty actions."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the action class."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables native button owners and suppresses the action hover treatment. Links and associated controls remain responsible for their own disabled behavior."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the default button, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Native element or render callback composed through Base UI useRender. Links retain native navigation and labels activate their associated controls without an additional keyboard target."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered action."}]},{"name":"Control","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Independent controls or tooltip targets lifted above a sibling Card.Action."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the control class."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Ref to the default span, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. The supplied control retains its native attributes, events and semantics."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered control wrapper."}]},{"name":"Header","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Header content. Supply a Heading when the title should be a semantic heading."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."}]},{"name":"Content","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content displayed in the padded body."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"divider","type":"boolean","required":false,"defaultValue":null,"description":"Adds a bottom border."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."}]},{"name":"Footer","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Footer content, such as actions or supporting text."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class merged with the part class."},{"name":"divider","type":"boolean","required":false,"defaultValue":"true","description":"Shows the top border unless explicitly set to false."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the default div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Native styles applied to the rendered part."}]}]}},{"name":"Dialog","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Dialog\ndescription: Present a focused task above the current page.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DialogReference from '/snippets/ui/generated/surfaces/dialog.mdx';\n\n## Overview\n\nUse `Dialog` for forms, details, and other tasks that open above the page. It manages focus, keyboard dismissal, outside clicks, and scrolling. Use [AlertDialog](/ui/primitives/surfaces/alert-dialog) when the user must explicitly respond to a decision.\n\nThis API is for standalone Twenty UI and the Twenty host application. Front components must use the SDK's [`openCommandConfirmationModal`](/developers/extend/apps/layout/front-components#host-communication-api) instead of rendering `Dialog` or `AlertDialog` directly. Native browser dialogs and popovers are also prohibited in the front component renderer.\n\n<StoryEmbed\n storyId=\"ui-surfaces-dialog--display\"\n title=\"Dialog example\"\n height={440}\n/>\n\n## Usage\n\n### Uncontrolled state\n\n`Root` owns visibility by default. Set `defaultOpen` for its initial state. Triggers, close controls, Escape, and outside clicks update that state.\n\n```tsx\nimport { Button, Field, Input } from 'twenty-ui/primitives/input';\nimport { Dialog } from 'twenty-ui/primitives/surfaces';\n\nexport const AccountDialog = () => (\n <Dialog.Root defaultOpen={false}>\n <Dialog.Trigger render={<Button>Edit account</Button>} />\n <Dialog.Portal>\n <Dialog.Backdrop />\n <Dialog.Viewport>\n <Dialog.Popup>\n <Dialog.Header>\n <Dialog.Title>Edit account</Dialog.Title>\n <Dialog.Description>Update the account details.</Dialog.Description>\n </Dialog.Header>\n <Dialog.Body>\n <Field.Root name=\"company\">\n <Field.Label>Company name</Field.Label>\n <Input defaultValue=\"Acme\" />\n </Field.Root>\n </Dialog.Body>\n <Dialog.Footer>\n <Dialog.Close render={<Button variant=\"outline\">Close</Button>} />\n <Dialog.Close render={<Button>Save</Button>} />\n </Dialog.Footer>\n </Dialog.Popup>\n </Dialog.Viewport>\n </Dialog.Portal>\n </Dialog.Root>\n);\n```\n\n## Anatomy\n\n```text\nDialog.Root\n├── Dialog.Trigger\n└── Dialog.Portal\n ├── Dialog.Backdrop\n └── Dialog.Viewport\n └── Dialog.Popup\n ├── Dialog.Header\n │ ├── Dialog.Title\n │ └── Dialog.Description\n ├── Dialog.Body\n └── Dialog.Footer\n └── Dialog.Close\n```\n\n| Part | Native and ref target |\n| -------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| `Root` | Coordinates visibility and modal behavior. Renders no DOM node and accepts no native attributes or DOM ref. |\n| `Trigger` | A button by default. Opens the dialog and supplies a focus restoration target. |\n| `Portal` | The portal div. Owns the destination container and whether closed content stays mounted. |\n| `Backdrop` | The backdrop div beneath the popup. Optional; omit it when no visible backdrop is needed. |\n| `Viewport` | The positioning div around the popup. |\n| `Popup` | The dialog div. Owns content, size, focus targets and dialog semantics. |\n| `Title` | An `h2` by default. Supplies the accessible name. Supply `aria-label` on `Popup` when omitting it. |\n| `Description` | A paragraph by default. Associates supporting text with the dialog. |\n| `Header`, `Body`, `Footer` | Optional divs arranging headings, content and actions. |\n| `Close` | A button by default. Provides a visible close action, including for touch screen readers. |\n\nAssemble `Portal`, `Backdrop`, `Viewport` and `Popup` explicitly. Each DOM part accepts its own native attributes, handlers, `className`, `style`, ref and `render` composition. A ref targets that part's rendered element. `Popup` does not create a portal, backdrop or viewport.\n\n## Controlled state\n\nPass `open` and `onOpenChange` when the application owns visibility. The callback receives the requested state and Base UI event details, including `reason`, `event`, `trigger` and `cancel()`. Update state to accept a change, or call `eventDetails.cancel()` to reject it. `onOpenChangeComplete` runs when the opening or closing animation finishes.\n\n```tsx\nimport { useState } from 'react';\nimport { Button, Field, Input } from 'twenty-ui/primitives/input';\nimport { Dialog } from 'twenty-ui/primitives/surfaces';\n\nexport const AccountDialog = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Dialog.Root open={open} onOpenChange={setOpen}>\n <Dialog.Trigger render={<Button>Edit account</Button>} />\n <Dialog.Portal>\n <Dialog.Backdrop />\n <Dialog.Viewport>\n <Dialog.Popup>\n <Dialog.Header>\n <Dialog.Title>Edit account</Dialog.Title>\n <Dialog.Description>\n Update the account details.\n </Dialog.Description>\n </Dialog.Header>\n <Dialog.Body>\n <Field.Root name=\"company\">\n <Field.Label>Company name</Field.Label>\n <Input defaultValue=\"Acme\" />\n </Field.Root>\n </Dialog.Body>\n <Dialog.Footer>\n <Dialog.Close render={<Button variant=\"outline\">Close</Button>} />\n <Dialog.Close render={<Button>Save</Button>} />\n </Dialog.Footer>\n </Dialog.Popup>\n </Dialog.Viewport>\n </Dialog.Portal>\n </Dialog.Root>\n );\n};\n```\n\nFor an asynchronous form, keep the dialog open while submitting. Close it after success and display failures inside the dialog.\n\n## Composition\n\n`Trigger` and `Close` accept `render` to compose with `Button`, as shown above. Custom wrappers must [forward supplied props and refs](/ui/primitives/overview#custom-components). DOM parts preserve Base UI's state-aware class names, styles and callback `render` contracts. `Header`, `Body` and `Footer` retain their styled layout and native div composition.\n\nNest another `Dialog.Root` inside a popup to open a second dialog. Closing the nested dialog returns focus to its trigger in the parent.\n\nTo open one dialog from triggers outside `Root`, create a handle once with `Dialog.createHandle<TPayload>()` and pass it to `handle` on both `Root` and each `Trigger`. Trigger `payload` values are available in `Root`'s render function. `Dialog.Handle` and the public `DialogHandle` type expose the installed handle contract:\n\n| Member | Purpose |\n| -------------------------- | ----------------------------------------------------- |\n| `open(triggerId)` | Opens with a matching trigger as the active trigger. |\n| `open(null)` | Opens without associating a trigger. |\n| `openWithPayload(payload)` | Opens with a typed payload and no associated trigger. |\n| `close()` | Requests closure. |\n| `isOpen` | Reads whether the associated dialog is open. |\n\nImperative actions take effect only while the associated Root is mounted. Root's `actionsRef` also exposes `close()` and `unmount()` for explicit transition control. To control an external closing animation, call `eventDetails.preventUnmountOnClose()` in `onOpenChange`, then call the `unmount()` action when the animation finishes.\n\n`Title` uses `Heading` and defaults to an `h2` with large type, primary text color, centered alignment, and spacing-4 below it. Use `level` to change the heading level independently of `size`, or `color` to change its text color. Native `className`, `style`, refs, and `render` are forwarded to the heading. Keep a heading element when using `render`. `Description` is centered like `Title`; AlertDialog keeps both left-aligned.\n\n`Popup` has no padding. `Header`, `Body` and `Footer` provide the inset, so content placed directly in `Popup` sits against its edges.\n\n## Focus, scrolling, and dismissal\n\n`Root.modal` controls the interaction boundary:\n\n| Value | Focus | Page scrolling and outside interaction |\n| ---------------- | ------------------------- | -------------------------------------------------------- |\n| `true` (default) | Trapped inside the dialog | Page scrolling and outside interaction are blocked. |\n| `\"trap-focus\"` | Trapped inside the dialog | Page scrolling and outside interaction remain available. |\n| `false` | Can leave the dialog | Page scrolling and outside interaction remain available. |\n\nOmit `Backdrop` when no visible backdrop is needed. For a nonmodal dialog whose viewport should pass pointer events through to the page, use `<Dialog.Viewport data-backdrop-hidden=\"true\">`; Popup remains interactive. Omitting the visual backdrop alone does not change `Root.modal`.\n\nSet `Popup.initialFocus` or `Popup.finalFocus` to a ref or callback to choose focus targets; `false` disables that automatic focus move. Focus callbacks receive the interaction type and retain Base UI's boolean, element, null and undefined return behavior. Closing normally restores focus to the trigger or previously focused element.\n\n`Root.disablePointerDismissal` prevents outside clicks from requesting closure. To prevent Escape dismissal, cancel the `escape-key` change in `onOpenChange`. Always provide a visible way to close a modal dialog.\n\n## Sizes and portals\n\n`Popup.size` accepts `sm`, `compact`, `md`, `lg`, `xl`, and `fullscreen`, and defaults to `md`. Long content scrolls within the popup. Width is constrained to the viewport.\n\nSet `Portal.container` to choose a destination:\n\n| Value | Resolution |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| Omitted or `undefined` | Uses the nearest scoped theme container. Without one, Base UI uses the parent portal or document body. |\n| Element or `ShadowRoot` | Uses that explicit destination instead of the theme scope. |\n| Ref | Base UI resolves its current element. A ref whose current value is null falls back to the parent portal or document body. |\n| `null` | Waits without mounting. Supply a destination in a later render to mount. |\n\n`Portal.keepMounted` retains content and form state while closed. `Viewport` and `Popup` carry the provided text direction into an external container; their explicit `dir` props take precedence. Without a direction provider or explicit `dir`, they inherit from the destination. See [theming](/ui/theming) and [DirectionProvider](/ui/primitives/layout/direction-provider).\n\nCustomize `Backdrop` and `Viewport` through their own props. Their native attributes, handlers, refs and `render` apply to those elements independently of Popup. Backdrop's `forceRender` keeps a nested dialog's backdrop visible when needed. Base UI open and transition state remains available to state-aware styles and render callbacks.\n\n## Migration\n\nWrap existing `Dialog.Popup` content in `Dialog.Portal` and `Dialog.Viewport`, and add a sibling `Dialog.Backdrop` inside Portal. Move `container` and `keepMounted` from Popup to Portal. Move former `backdrop` props onto Backdrop; replace `backdrop={false}` by omitting Backdrop. Move `viewportProps` onto Viewport, retaining `data-backdrop-hidden=\"true\"` when the viewport must pass outside pointer events through. Keep `size`, `initialFocus`, `finalFocus`, native popup attributes and popup refs on Popup. The fused Popup assembly props are removed.\n\nRoot, Trigger, Close, Title, Description, Header, Body, Footer and existing handles retain their roles. Public part props, state, actions and event-detail types are exported from `twenty-ui/primitives/surfaces`.\n\n## Props\n\n<DialogReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Dialog","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/dialog","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<DialogRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the dialog after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the dialog completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the dialog imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"Parts or a render function receiving the active trigger payload. Root renders no DOM node."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the dialog is initially open.\n\nTo render a controlled dialog, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open dialog."},{"name":"disablePointerDismissal","type":"boolean","required":false,"defaultValue":"false","description":"Whether to prevent the dialog from closing on outside presses.\nFor non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it."},{"name":"handle","type":"DialogHandle<Payload>","required":false,"defaultValue":null,"description":"Connects detached triggers and imperative dialog actions."},{"name":"modal","type":"boolean | \"trap-focus\"","required":false,"defaultValue":"true","description":"Determines if the dialog enters a modal state when open.\n- `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n- `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled.\n\nWhen `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so\ntouch screen readers can escape the popup."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested state and Base UI event details, including reason, event, trigger and cancel()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the dialog is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the dialog is currently open."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled dialog.\nThere's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: DialogTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"handle","type":"DialogHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with a dialog.\nCan be created with the Dialog.createHandle() method."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the dialog when it is opened."},{"name":"ref","type":"((((instance: HTMLButtonElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<HTMLButtonElement | null>) & (((instance: HTMLElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<...>)) | null","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: DialogPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Omit to use the nearest theme scope, then the parent portal or document body. Explicit null defers mounting; an element, ShadowRoot or ref keeps Base UI resolution."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the portal and its content mounted while closed."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPortalState>","required":false,"defaultValue":null,"description":"Composes the portal element. Native props and handlers target it."},{"name":"style","type":"CSSProperties | ((state: DialogPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: DialogBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"forceRender","type":"boolean","required":false,"defaultValue":"false","description":"Renders the backdrop even when this dialog is nested."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the backdrop div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Popup and any other content within the positioning viewport."},{"name":"className","type":"string | ((state: DialogViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the viewport div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Dialog content. Compose inside Viewport and Portal; Popup does not create those parts or a Backdrop."},{"name":"className","type":"string | ((state: DialogPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Controls focus restoration on closing. Accepts a boolean, element ref or callback receiving the interaction type."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Controls focus on opening. Accepts a boolean, element ref or callback receiving the interaction type."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>","required":false,"defaultValue":null,"description":"Composes the popup element while retaining native props, handlers, dialog semantics and focus behavior."},{"name":"size","type":"\"compact\" | \"fullscreen\" | \"lg\" | \"md\" | \"sm\" | \"xl\"","required":false,"defaultValue":"md","description":"Width of the dialog, or `fullscreen` to fill the viewport."},{"name":"style","type":"CSSProperties | ((state: DialogPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: DialogTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Theme font color. Defaults to `primary`."},{"name":"level","type":"1 | 2 | 3 | 4 | 5 | 6","required":false,"defaultValue":"2","description":"Semantic heading level, from `h1` through `h6`. Does not change the visual size. Defaults to `2`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"lg","description":"Visual font size, independent of the heading level. Defaults to `lg`."},{"name":"style","type":"CSSProperties | ((state: DialogTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: DialogDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLParagraphElement>","required":false,"defaultValue":null,"description":"Ref to the description paragraph, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"className","type":"string | ((state: DialogCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the close button, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Header","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Body","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Footer","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]}]}},{"name":"AlertDialog","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: AlertDialog\ndescription: Ask for confirmation before an action that needs an explicit decision.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AlertDialogReference from '/snippets/ui/generated/surfaces/alert-dialog.mdx';\n\n## Overview\n\nUse `AlertDialog` for a decision that interrupts the current workflow, such as confirming deletion. It provides `alertdialog` semantics, focus management, and explicit confirmation or cancellation.\n\nThis primitive is for standalone Twenty UI and host-owned interfaces. Front components must request a confirmation through the [SDK host dialog API](/developers/extend/apps/layout/front-components#host-communication-api). Direct `Dialog`, `AlertDialog`, and native browser dialogs are prohibited inside the front component renderer.\n\n<StoryEmbed\n storyId=\"ui-surfaces-alertdialog--display\"\n title=\"AlertDialog example\"\n height={440}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultOpen` to set the initial visibility. The dialog owns subsequent changes from its trigger, close controls, and dismissal interactions.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AlertDialog } from 'twenty-ui/primitives/surfaces';\n\ntype DeleteConfirmationProps = { onDelete: () => void };\n\nexport const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (\n <AlertDialog.Root defaultOpen={false}>\n <AlertDialog.Trigger\n render={<Button variant=\"solid\">Delete record</Button>}\n />\n <AlertDialog.Portal>\n <AlertDialog.Backdrop />\n <AlertDialog.Viewport>\n <AlertDialog.Popup>\n <AlertDialog.Header>\n <AlertDialog.Title>Delete this record?</AlertDialog.Title>\n <AlertDialog.Description>\n This record will be permanently deleted. This action cannot be\n undone.\n </AlertDialog.Description>\n </AlertDialog.Header>\n <AlertDialog.Footer>\n <AlertDialog.Close render={<Button>Cancel</Button>} />\n <AlertDialog.Close\n onClick={onDelete}\n render={<Button color=\"danger\">Delete</Button>}\n />\n </AlertDialog.Footer>\n </AlertDialog.Popup>\n </AlertDialog.Viewport>\n </AlertDialog.Portal>\n </AlertDialog.Root>\n);\n```\n\n`defaultOpen` defaults to `false`, so it can be omitted. This example uses a synchronous confirmation callback and closes after the action runs.\n\n## Anatomy\n\nKeep related parts inside `AlertDialog.Root`, or connect detached triggers through a handle. Compose the portal, backdrop, viewport, and popup separately.\n\n```text\nAlertDialog.Root\n├── AlertDialog.Trigger\n└── AlertDialog.Portal\n ├── AlertDialog.Backdrop\n └── AlertDialog.Viewport\n └── AlertDialog.Popup\n ├── AlertDialog.Header\n │ ├── AlertDialog.Title\n │ └── AlertDialog.Description\n ├── AlertDialog.Body\n └── AlertDialog.Footer\n ├── AlertDialog.Close\n └── Confirmation action\n```\n\n| Part | Requirement | Purpose |\n| -------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |\n| `Root` | Required | Coordinates open state and modal behavior. |\n| `Trigger` | Optional for a programmatically opened dialog | Opens the dialog and provides a return focus target. |\n| `Portal` | Recommended | Moves the overlay to its container and controls mounting. |\n| `Backdrop` | Optional | Visually separates the alert from the surrounding page. |\n| `Viewport` | Recommended | Positions the popup and provides its scrollable surrounding area. |\n| `Popup` | Required | Renders the alert content with focus management. |\n| `Title` | Recommended | Supplies the visible alert name. An accessible name is always required. |\n| `Description` | Recommended for a confirmation | Explains the decision and its consequences. |\n| `Header`, `Body`, `Footer` | Optional layout parts | Arrange headings, additional content, and actions. |\n| `Close` | Recommended for cancellation | Supplies an explicit close action. |\n\nSet `container` and `keepMounted` on `Portal`, backdrop attributes on `Backdrop`, layout attributes on `Viewport`, and `size` and focus props on `Popup`. Each element part accepts its own native attributes, handlers, ref, and `render` composition. `Popup.ref` points to the alert content element. `Title` and `Description` establish the accessible relationships; provide `aria-label` on `Popup` when omitting a title.\n\nThe confirmation action is application content, not an exported part. Use `Close` with a synchronous handler or a `Button` with controlled open state for asynchronous confirmation.\n\n## Controlled state\n\nPass `open` and update it with `onOpenChange` to own the same dialog's visibility in React state. The callback receives the requested boolean and upstream event details, including `reason`, `event`, and `cancel()`. Call `eventDetails.cancel()` to reject a requested change. `onOpenChangeComplete` runs after opening or closing transitions finish.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AlertDialog } from 'twenty-ui/primitives/surfaces';\n\ntype DeleteConfirmationProps = { onDelete: () => void };\n\nexport const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => {\n const [open, setOpen] = useState(false);\n\n return (\n <AlertDialog.Root open={open} onOpenChange={setOpen}>\n <AlertDialog.Trigger\n render={<Button variant=\"solid\">Delete record</Button>}\n />\n <AlertDialog.Portal>\n <AlertDialog.Backdrop />\n <AlertDialog.Viewport>\n <AlertDialog.Popup>\n <AlertDialog.Header>\n <AlertDialog.Title>Delete this record?</AlertDialog.Title>\n <AlertDialog.Description>\n This record will be permanently deleted. This action cannot be\n undone.\n </AlertDialog.Description>\n </AlertDialog.Header>\n <AlertDialog.Footer>\n <AlertDialog.Close render={<Button>Cancel</Button>} />\n <AlertDialog.Close\n onClick={onDelete}\n render={<Button color=\"danger\">Delete</Button>}\n />\n </AlertDialog.Footer>\n </AlertDialog.Popup>\n </AlertDialog.Viewport>\n </AlertDialog.Portal>\n </AlertDialog.Root>\n );\n};\n```\n\nFor asynchronous confirmation, use a `Button` with your action handler instead of `AlertDialog.Close`. Keep `open` true while the action is pending, call `setOpen(false)` after it succeeds, and show an error inside the dialog if it fails.\n\n## Compose with buttons\n\nUse `render` to give the trigger and close controls Twenty UI button styling. The dialog parts supply their interaction handlers and refs to the buttons.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { AlertDialog } from 'twenty-ui/primitives/surfaces';\n\ntype DeleteConfirmationProps = { onDelete: () => void };\n\nexport const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (\n <AlertDialog.Root>\n <AlertDialog.Trigger\n render={<Button variant=\"solid\">Delete record</Button>}\n />\n <AlertDialog.Portal>\n <AlertDialog.Backdrop />\n <AlertDialog.Viewport>\n <AlertDialog.Popup>\n <AlertDialog.Header>\n <AlertDialog.Title>Delete this record?</AlertDialog.Title>\n <AlertDialog.Description>\n This record will be permanently deleted. This action cannot be\n undone.\n </AlertDialog.Description>\n </AlertDialog.Header>\n <AlertDialog.Footer>\n <AlertDialog.Close render={<Button>Cancel</Button>} />\n <AlertDialog.Close\n onClick={onDelete}\n render={<Button color=\"danger\">Delete</Button>}\n />\n </AlertDialog.Footer>\n </AlertDialog.Popup>\n </AlertDialog.Viewport>\n </AlertDialog.Portal>\n </AlertDialog.Root>\n);\n```\n\nKeep each action as a single interactive control. If you wrap `Button` in your own component, [forward the supplied props and ref](/ui/primitives/overview#custom-components).\n\n## Detached triggers and imperative actions\n\nCreate a handle once with `AlertDialog.createHandle<Payload>()` and pass it to `handle` on `Root` and each detached `Trigger`. A trigger's typed `payload` is available to the root's child render function. A handle also supports `open(triggerId)`, `openWithPayload(payload)`, `close()`, and the `isOpen` getter while its root is mounted. Pass a matching trigger ID to `open`, or `null` to open without a trigger. Call imperative methods from event handlers or effects.\n\n`Root.actionsRef` exposes `close()` and `unmount()`. For an externally controlled closing animation, call `eventDetails.preventUnmountOnClose()` in `onOpenChange`, then call `actionsRef.current?.unmount()` after the animation finishes. The regular styled parts manage their own transitions without these imperative actions.\n\n## Sizing and portals\n\n`Popup.size` accepts `sm`, `md`, `lg`, `xl`, and `fullscreen`, and defaults to `md`. Size and appearance belong to the AlertDialog surface and do not have to match Dialog presets.\n\n`Portal.container` defaults to the nearest theme's portal container. Without one, Base UI uses its default portal destination, normally `document.body`. An explicit element, shadow root, or ref overrides that destination. An explicit `null` defers mounting until a container is available. Base UI resolves a ref whose `current` is `null` using its default destination; use `container={null}` when mounting must wait.\n\nPortaled content retains the theme context. `Portal` and `Viewport` inherit the provided text direction unless you set `dir` explicitly. Set `Portal.keepMounted` to retain mounted content and form state while closed.\n\n## Focus and dismissal\n\nThe alert traps focus, blocks outside interaction, and locks page scrolling while open. Escape requests closure; clicking outside does not. To prevent Escape dismissal, cancel the `escape-key` change in `onOpenChange`. Always provide a visible Cancel or Close action.\n\nBy default, focus moves to the first tabbable control, or to the popup for a touch opening. Put the least destructive action first, or use `Popup.initialFocus` to select it. Focus returns to the trigger or previously focused element when the alert closes. Use `Popup.finalFocus` when a successful action removes that target. Both focus props accept a boolean, element ref, or interaction-type callback according to the upstream contract.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<AlertDialogReference />\n\n<PageBanner illustration=\"card-page-billing-faq\" />\n","api":{"name":"AlertDialog","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/alert-dialog","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<DialogRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the alert dialog after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the alert dialog completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the alert dialog imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"The content of the dialog.\nThis can be a regular React node or a render function that receives the `payload` of the active trigger."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the dialog is initially open.\n\nTo render a controlled dialog, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open dialog."},{"name":"handle","type":"AlertDialogHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the alert dialog with a trigger.\nIf specified, allows external triggers to control the alert dialog's open state.\nCan be created with the AlertDialog.createHandle() method."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Event handler called when the alert dialog is opened or closed."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the dialog is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the dialog is currently open."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the dialog is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled dialog.\nThere's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: DialogTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"handle","type":"AlertDialogHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with an alert dialog.\nCan be created with the AlertDialog.createHandle() method."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the dialog when it is opened."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: DialogPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Omission uses the theme container or Base UI default; explicit `null` defers mounting. A ref with a null current value uses the Base UI default destination."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps content mounted while the alert is closed."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: DialogBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"forceRender","type":"boolean","required":false,"defaultValue":"false","description":"Whether the backdrop is forced to render even when nested."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"className","type":"string | ((state: DialogViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"className","type":"string | ((state: DialogPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the dialog is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the dialog is opened.\nBy default, focus moves to the first tabbable element inside the popup, except when the dialog\nis opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"fullscreen\" | \"lg\" | \"md\" | \"sm\" | \"xl\"","required":false,"defaultValue":"md","description":"Width of the alert, or `fullscreen` to fill the viewport."},{"name":"style","type":"CSSProperties | ((state: DialogPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: DialogTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: DialogDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"className","type":"string | ((state: DialogCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: DialogCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Header","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Body","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Footer","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]}]}},{"name":"Popover","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Popover\ndescription: Display contextual content anchored to a trigger.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport PopoverReference from '/snippets/ui/generated/surfaces/popover.mdx';\n\n## Overview\n\nUse `Popover` for contextual information or lightweight controls. Compose its portal, positioning wrapper and popup separately. Use [Dropdown](/ui/components/navigation/dropdown) for menus, pickers and panels with higher-level navigation.\n\n<StoryEmbed\n storyId=\"ui-surfaces-popover--display\"\n title=\"Popover example\"\n height={280}\n/>\n\n## Usage\n\n### Uncontrolled state\n\nUse `defaultOpen` to set the initial visibility. The popover owns subsequent changes from its trigger, close controls, and dismissal interactions.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const ContactDetailsPopover = () => (\n <Popover.Root defaultOpen={false}>\n <Popover.Trigger render={<Button>Show details</Button>} />\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup\n style={{ boxSizing: 'border-box', width: 260, padding: 16, gap: 12 }}\n >\n <Popover.Title>Contact details</Popover.Title>\n <Popover.Description>\n Reach Alex at [email protected].\n </Popover.Description>\n <Popover.Close\n style={{ alignSelf: 'flex-end' }}\n render={<Button size=\"sm\">Close</Button>}\n />\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n);\n```\n\n`defaultOpen` defaults to `false`, so it can be omitted. Use `Title` and `Description` to identify the popup. The trigger renders a button by default; `render` lets you supply a compatible element.\n\n## Placement comparison\n\nCompare the supported sides with and without an arrow. These open examples keep each popup beside its trigger for inspection; use the Display example to try opening and dismissing a popover.\n\n<StoryEmbed\n storyId=\"ui-surfaces-popover--catalog\"\n title=\"Placement comparison for popover\"\n height={640}\n/>\n\n## Anatomy\n\nKeep the trigger and popup inside `Popover.Root`. The popup can contain text, form controls, and actions.\n\n```text\nPopover.Root\n├── Popover.Trigger\n└── Popover.Portal\n ├── Popover.Backdrop (optional)\n └── Popover.Positioner\n └── Popover.Popup\n ├── Popover.Arrow (optional)\n └── Popover.Viewport (optional)\n ├── Popover.Title\n ├── Popover.Description\n └── Popover.Close\n```\n\n| Part | Purpose and native target |\n| ------------- | --------------------------------------------------------------------------------- |\n| `Root` | Owns state, triggers and interactions. Renders no DOM element. |\n| `Trigger` | Opens the popup and supplies its default anchor. Targets a button. |\n| `Portal` | Chooses the destination. Native props, handlers, `render` and ref target its div. |\n| `Positioner` | Owns anchors, alignment, offsets and collision handling. Targets its div. |\n| `Popup` | Renders content and manages focus. Targets its div. |\n| `Arrow` | Optional styled arrow inside Popup. Targets its div. |\n| `Backdrop` | Optional upstream backdrop inside Portal. Targets its div. |\n| `Viewport` | Optional transition container for changing content. Targets its div. |\n| `Title` | Supplies a visible accessible name. Targets an h2. |\n| `Description` | Associates explanatory text. Targets a paragraph. |\n| `Close` | Requests closing. Targets a button. |\n\nAll rendered parts support the installed Base UI native attributes, handlers, refs and element/function `render` composition. Custom components must forward the supplied props and ref. Every part has a public `Popover<Part>Props` and `Popover<Part>State` type. `PopoverRootProps` and `PopoverTriggerProps` preserve payload generics. `PopoverHandle`, `PopoverRootActions`, `PopoverRootChangeEventDetails` and `PopoverRootChangeEventReason` are also exported from `twenty-ui/primitives/surfaces`.\n\n## Controlled state\n\nPass `open` and update it with `onOpenChange` to own the same popover's visibility in React state.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const ContactDetailsPopover = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Popover.Root open={open} onOpenChange={setOpen}>\n <Popover.Trigger render={<Button>Show details</Button>} />\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup\n style={{\n boxSizing: 'border-box',\n width: 260,\n padding: 16,\n gap: 12,\n }}\n >\n <Popover.Title>Contact details</Popover.Title>\n <Popover.Description>\n Reach Alex at [email protected].\n </Popover.Description>\n <Popover.Close\n style={{ alignSelf: 'flex-end' }}\n render={<Button size=\"sm\">Close</Button>}\n />\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n );\n};\n```\n\n`onOpenChange` receives the next boolean and event details, including changes requested by the trigger, close controls, Escape, and outside interaction.\n\n## Compose with buttons\n\nPass a Twenty UI `Button` through `render` to use it as the trigger or close control. The popover keeps its open state, keyboard behavior, and focus handling.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const ImportHelp = () => (\n <Popover.Root>\n <Popover.Trigger render={<Button variant=\"outline\">Import help</Button>} />\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup\n style={{ boxSizing: 'border-box', width: 260, padding: 16, gap: 12 }}\n >\n <Popover.Arrow />\n <Popover.Title>Import a CSV file</Popover.Title>\n <Popover.Description>\n Use a header row to identify your columns.\n </Popover.Description>\n <Popover.Close\n style={{ alignSelf: 'flex-end' }}\n render={<Button size=\"sm\">Got it</Button>}\n />\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n);\n```\n\n`render` composes behavior onto the supplied button. Custom wrapper components must [forward the supplied props and ref](/ui/primitives/overview#custom-components) to preserve that behavior.\n\n## Placement and focus\n\n`Positioner` defaults to `side=\"bottom\"`, `align=\"center\"` and `sideOffset={8}`. It accepts the full installed Base UI contract, including element/ref/function/virtual anchors, functional offsets, `positionMethod`, `collisionBoundary`, `collisionPadding`, `collisionAvoidance`, `arrowPadding`, `sticky` and `disableAnchorTracking`. DirectionProvider controls logical positioning and supplies the DOM direction. An explicit `dir` can override the native attribute; use the provider to change logical side placement.\n\n```tsx\nimport { useRef } from 'react';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const AnchoredHelp = () => {\n const anchor = useRef<HTMLDivElement>(null);\n\n return (\n <div ref={anchor}>\n <Popover.Root>\n <Popover.Trigger>Help</Popover.Trigger>\n <Popover.Portal>\n <Popover.Positioner\n anchor={anchor}\n side=\"inline-end\"\n align=\"start\"\n sideOffset={({ anchor }) => anchor.width / 2}\n collisionBoundary=\"clipping-ancestors\"\n collisionAvoidance={{ side: 'flip', align: 'shift' }}\n collisionPadding={8}\n positionMethod=\"fixed\"\n >\n <Popover.Popup aria-label=\"Help\">\n <Popover.Arrow />\n Contextual help\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n </Popover.Root>\n </div>\n );\n};\n```\n\nEscape closes the popup and restores focus to its trigger. Outside interaction dismisses it by default. `Popup.initialFocus` and `Popup.finalFocus` accept the upstream focus targets and callbacks. `Root.modal` retains Base UI's nonmodal default, modal and trap-focus modes for standalone usage.\n\n## Portal destinations and theme\n\nSet `container` and `keepMounted` on `Portal`:\n\n| Container | Resolution |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Omitted or `undefined` | Uses the nearest scoped ThemeProvider container. Without one, Base UI uses its parent portal or document body. |\n| `null` | Waits without rendering portal content until the container changes. It does not fall back to the theme or body. |\n| Element, ShadowRoot or ref | Passes the supplied target unchanged to Base UI. An unresolved ref retains Base UI's parent-portal/body fallback; use explicit null when waiting is required. |\n\nThe default scoped destination preserves its CSS tokens and color scheme. An explicit destination inherits CSS from its actual DOM scope. Put it inside the intended theme scope, or supply the theme styles there. ShadowRoot targets need the library's CSS and theme styles in that shadow tree. React theme context and provided text direction remain available across portals. This API does not expand the renderer's permitted portal destinations.\n\n## Detached triggers and payloads\n\n`Popover.createHandle<TPayload>()` connects detached triggers to a root and exposes `open(triggerId)`, `close()` and `isOpen`. `Popover.Handle` is the installed upstream handle constructor. Root's render function receives the active payload. Call imperative actions from event handlers or effects.\n\n```tsx\nimport { useState } from 'react';\nimport { Popover } from 'twenty-ui/primitives/surfaces';\n\nexport const OwnerHelp = () => {\n const [handle] = useState(() => Popover.createHandle<{ name: string }>());\n\n return (\n <>\n <Popover.Trigger handle={handle} id=\"owner\" payload={{ name: 'Alice' }}>\n Owner\n </Popover.Trigger>\n <Popover.Root handle={handle}>\n {({ payload }) => (\n <Popover.Portal>\n <Popover.Positioner align=\"start\">\n <Popover.Popup aria-label=\"Account owner\">\n {payload?.name}\n <Popover.Close>Close</Popover.Close>\n </Popover.Popup>\n </Popover.Positioner>\n </Popover.Portal>\n )}\n </Popover.Root>\n </>\n );\n};\n```\n\n`onOpenChange` preserves `reason`, `event`, `trigger`, `cancel()` and `preventUnmountOnClose()`. Controlled roots retain `triggerId`; uncontrolled roots retain `defaultTriggerId`. `actionsRef` exposes the upstream close/unmount actions.\n\n## Migration\n\nMove `container` and `keepMounted` from Popup to Portal. Move placement, anchor and collision props to Positioner. Replace `Popup.arrow` with an explicit `Popover.Arrow` child. Popup's native props, handlers, focus props and ref continue to target the content element. Dropdown.Content keeps its existing convenient assembly.\n\nInside front components, use nonmodal composition within the existing scoped portal policy. Native browser popovers/dialogs and direct app-owned modality are prohibited; use the SDK host dialog API for dialogs. Renderer portal, geometry, scrolling and dismissal capability work remains separate from this primitive API.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.\n\n<PopoverReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Popover","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/popover","props":[],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<PopoverRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the popover after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the popover completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the popover imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"Parts or a render function receiving the active trigger payload. Root renders no DOM element."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover is initially open.\n\nTo render a controlled popover, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the popover is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open popover."},{"name":"handle","type":"PopoverHandle<Payload>","required":false,"defaultValue":null,"description":"Connects detached triggers and imperative open/close actions."},{"name":"modal","type":"boolean | \"trap-focus\"","required":false,"defaultValue":"false","description":"Determines if the popover enters a modal state when open.\n- `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.\n- `false`: user interaction with the rest of the document is allowed.\n- `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.\n\nOn touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.\n\nWhen `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered\ninside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as\nTailwind's `sr-only` utility.\n\nWhen `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch\nscreen readers can escape the popup."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the popover is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popover is currently open."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the popover is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled popover.\nThere's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"handle","type":"PopoverHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with a popover."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the popover when it is opened."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: PopoverPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"When omitted, uses the scoped theme container, then the Base UI parent portal or document body. Explicit null delays rendering until a target is supplied. Explicit elements, ShadowRoots and refs are forwarded unchanged; their DOM scope supplies CSS tokens."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the portal mounted in the DOM while the popup is hidden."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div. Native props, handlers and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"How to align the popup relative to the specified side."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: PopoverPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div. Accepts the complete Base UI anchor, collision and positioning contract."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"8","description":"Distance from the anchor. Defaults to 8. Accepts a number or positioning function."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: PopoverPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Popup content. Compose Portal, Positioner and Arrow separately."},{"name":"className","type":"string | ((state: PopoverPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is opened.\nBy default, focus moves to the first tabbable element inside the popup, except when the popover\nis opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div. Focus props, native attributes, handlers and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: PopoverArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the arrow div. Compose inside Popup."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Backdrop","props":[{"name":"className","type":"string | ((state: PopoverBackdropState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the optional backdrop div. Compose inside Portal."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverBackdropState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverBackdropState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: PopoverTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Description","props":[{"name":"className","type":"string | ((state: PopoverDescriptionState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverDescriptionState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverDescriptionState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"className","type":"string | ((state: PopoverCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The content to render inside the transition container."},{"name":"className","type":"string | ((state: PopoverViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the content-transition div for changing trigger payloads."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Tooltip","entryPoint":"twenty-ui/primitives/surfaces","content":"---\ntitle: Tooltip\ndescription: Show supplementary information when a trigger is hovered or focused.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TooltipReference from '/snippets/ui/generated/surfaces/tooltip.mdx';\n\n## Overview\n\nUse `Tooltip` for a short explanation of a control or truncated text. Keep essential information visible, give controls an accessible name, and use [Popover](/ui/primitives/surfaces/popover) when the content contains links, buttons, or other controls.\n\n<StoryEmbed\n storyId=\"ui-surfaces-tooltip--display\"\n title=\"Tooltip example\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ExportHelp = () => (\n <Tooltip content=\"Download the visible records as a CSV file\" side=\"top\">\n <Text render={<span />}>\n <Button>Export records</Button>\n </Text>\n </Tooltip>\n);\n```\n\nThe convenience component accepts one trigger element as `children`. Native elements receive the trigger attributes, event handlers, and ref directly. Custom trigger components must forward all of them. A wrapper element also works with a component that does not forward every trigger prop.\n\nHover opens the tooltip after `delay` milliseconds, which defaults to `600`. Keyboard focus opens it immediately. `closeDelay` defaults to `0`; hovering over the popup keeps it open unless `disableHoverablePopup` is set. Escape dismisses it.\n\n## Controlled state\n\nUse `open` and `onOpenChange` together when the application owns visibility. Use `defaultOpen` only to set the initial visibility of an uncontrolled tooltip.\n\n```tsx\nimport { useState } from 'react';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const ControlledExportHelp = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <Tooltip\n content=\"Download the visible records as a CSV file\"\n open={open}\n onOpenChange={setOpen}\n delay={300}\n >\n <span>\n <Button>Export records</Button>\n </span>\n </Tooltip>\n );\n};\n```\n\n## Rich content and composition\n\nShorthand accepts `description` and `startIcon` beside `content`. Custom node content renders as supplied unless a description or icon requests the title layout.\n\n```tsx\nimport { IconInfoCircle } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const ExportDetails = () => (\n <Tooltip\n content=\"Export visible records\"\n description=\"Only records matching your current filters are included.\"\n startIcon={<IconInfoCircle />}\n arrow\n >\n <Button>Export records</Button>\n </Tooltip>\n);\n```\n\nCompound usage exposes every installed Base UI part and the optional `Tooltip.Body` layout. Assemble the portal, positioning, popup and optional arrow explicitly. Popup renders its children as supplied; Body provides the same title, description and decorative icon layout as shorthand.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const ComposedExportDetails = () => (\n <Tooltip.Provider delay={300} closeDelay={100} timeout={400}>\n <Tooltip.Root>\n <Tooltip.Trigger render={<Button>Export records</Button>} />\n <Tooltip.Portal>\n <Tooltip.Positioner side=\"inline-end\" sideOffset={10} arrowPadding={8}>\n <Tooltip.Popup>\n <Tooltip.Arrow />\n <Tooltip.Viewport>\n <Tooltip.Body description=\"Only records matching your current filters are included.\">\n Export visible records\n </Tooltip.Body>\n </Tooltip.Viewport>\n </Tooltip.Popup>\n </Tooltip.Positioner>\n </Tooltip.Portal>\n </Tooltip.Root>\n </Tooltip.Provider>\n);\n```\n\n| Part | Native, prop and ref target |\n| ------------ | --------------------------------------------------------------------------------------------------------------------------- |\n| `Root` | State and payload coordination. No DOM node, native props or DOM ref. `actionsRef` exposes `close` and `unmount`. |\n| `Provider` | Shared `delay`, `closeDelay` and `timeout`. No DOM node or DOM ref. |\n| `Trigger` | A button by default. Native props, handlers, `render` and ref target the trigger element. |\n| `Portal` | The portal div. Defaults to the theme container, then document body. |\n| `Positioner` | The positioning div. Owns anchor, physical/logical side, offsets, collision handling, sticky positioning and arrow padding. |\n| `Popup` | The popup div. Owns content, native props, styles, `render` and ref. |\n| `Body` | The optional body div inside Popup or Viewport. Native props, styles, `render` and ref target its root. |\n| `Arrow` | The arrow div inside Popup. |\n| `Viewport` | The optional div for transitions between trigger payloads. |\n\n`Tooltip.Body` accepts optional title children, `description` and `startIcon` nodes. Titles use medium weight; descriptions use the secondary tooltip color, preserve line breaks and wrap long text. Omit title children for a description-only tooltip. The icon is decorative and appears only with a title. Body adds no tooltip role, popup styling, sizing or positioning. Arbitrary Popup content remains supported. Import `TooltipBodyProps` from `twenty-ui/primitives/surfaces` when typing a wrapper.\n\nEvery DOM part accepts native props, refs, and element or callback `render` composition. Shorthand's top-level native props, `render` and ref target Popup. Use `triggerProps`, `positionerProps` and `portalProps` to customize the other targets; these override shorthand defaults. Children supply the default trigger render element. Both forms preserve controlled/uncontrolled Root state and Base UI callback event details, including cancellation, reason, original event and active trigger.\n\n`Tooltip.createHandle<TPayload>()` connects detached triggers to either form through `handle`. Compound Root's children or shorthand's `content` can be a function receiving the typed active payload. `Tooltip.Handle` and the public `TooltipHandle` type expose the installed handle contract. Handles support imperative `open(triggerId)` and `close()` while their Root is mounted.\n\n## Migration\n\nReplace `content={<Tooltip.Content description={description} startIcon={icon}>title</Tooltip.Content>}` with `content={title} description={description} startIcon={icon}`. In compound usage, use `Tooltip.Body` for the shared title and description layout or compose your own content. `Tooltip.Content` and `TooltipContentProps` are removed.\n\nExisting compound Popup positioning props move to Positioner. Wrap it in Portal, move `container` and `keepMounted` to Portal, keep `maxWidth` on Popup, and replace `arrow` with an Arrow child. Preserve the former spacing explicitly with `sideOffset={10}` when needed. Compound Positioner keeps Base UI's `sideOffset={0}`. Both forms cap Popup at 300 pixels by default.\n\n## Disabled controls\n\nNative disabled buttons cannot receive keyboard focus. Wrap one in a focusable trigger so users can discover why the action is unavailable.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Tooltip } from 'twenty-ui/primitives/surfaces';\n\nexport const UnavailableExport = () => (\n <Tooltip content=\"Select at least one record to export\">\n <span tabIndex={0} aria-label=\"Export records unavailable\">\n <Button disabled>Export records</Button>\n </span>\n </Tooltip>\n);\n```\n\nSetting `disabled` on shorthand or Root suppresses the tooltip itself. Trigger `disabled` suppresses that trigger’s tooltip interaction. Disable the native control through its own props or Trigger’s render element.\n\n## Placement and overflowing text\n\nShorthand defaults to `side=\"top\"`, `align=\"center\"`, and `sideOffset={10}`. Both shorthand and compound tooltips have a maximum width of 300 pixels, capped by the available space beside the anchor. Pass `maxWidth` to shorthand or `Tooltip.Popup` to choose a different maximum, including wider previews. Native popup styles remain available for custom sizing. Placement adjusts to available space. An open tooltip hides while its anchor is scrolled out of view, including out of a scroll container. Use `arrow` for an arrow and `container` to override the theme's portal destination; see [theming](/ui/theming).\n\nUse [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip) when a text label should show its full value only when truncated. Its existing `text`, `tooltipContent`, and `tooltipPlace` props remain available.\n\n## Props\n\nThe reference is generated from the public component types. Native popup attributes and event handlers are also accepted.\n\n<TooltipReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Tooltip","entryPoint":"twenty-ui/primitives/surfaces","slug":"surfaces/tooltip","props":[{"name":"actionsRef","type":"RefObject<TooltipRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the tooltip after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the tooltip completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the tooltip imperatively when called."},{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"Alignment relative to the trigger. Defaults to center."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Offset along the alignment axis in pixels."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An explicit positioning anchor for the popup."},{"name":"arrow","type":"boolean","required":false,"defaultValue":null,"description":"Displays an arrow pointing to the trigger. Defaults to false."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance from the arrow to the popup edges."},{"name":"children","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":true,"defaultValue":null,"description":"A single trigger element. Custom components must forward their ref, native attributes, and event handlers."},{"name":"className","type":"string | ((state: TooltipPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"Additional CSS class for the popup."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"Delay in milliseconds before closing after hover ends. Defaults to 0."},{"name":"closeOnClick","type":"boolean","required":false,"defaultValue":"true","description":"Whether the tooltip should close when this trigger is clicked."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Defaults to the current theme container."},{"name":"content","type":"ReactNode | PayloadChildRenderFunction<TPayload>","required":true,"defaultValue":null,"description":"Supplementary content, or a function receiving the active trigger payload. Strings and numbers use the shorthand title layout."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Initial visibility when the tooltip manages its own state."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip."},{"name":"delay","type":"number","required":false,"defaultValue":"600","description":"Delay in milliseconds before opening on hover. Defaults to 600."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional secondary text below the shorthand title."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Prevents the tooltip from opening."},{"name":"disableHoverablePopup","type":"boolean","required":false,"defaultValue":"false","description":"Prevents hovering over the popup from keeping it open."},{"name":"handle","type":"TooltipHandle<TPayload>","required":false,"defaultValue":null,"description":"Connects detached triggers and preserves their typed payloads."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":null,"description":"Keeps the popup mounted while closed."},{"name":"maxWidth","type":"MaxWidth<string | number>","required":false,"defaultValue":null,"description":"Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the tooltip is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controlled visibility of the tooltip."},{"name":"portalProps","type":"TooltipPortalProps","required":false,"defaultValue":null,"description":"Full Portal props, including native props, ref and render. Overrides shorthand portal defaults."},{"name":"positionerProps","type":"TooltipPositionerProps","required":false,"defaultValue":null,"description":"Full Positioner props, including native props, ref and render. Overrides shorthand placement defaults."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"CSS positioning method for the popup."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the popup element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"top","description":"Preferred side of the trigger. Defaults to top and may change to avoid collisions."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"10","description":"Distance from the trigger in pixels. Defaults to 10."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional node before the shorthand title."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Inline styles for the popup."},{"name":"trackCursorAxis","type":"\"both\" | \"none\" | \"x\" | \"y\"","required":false,"defaultValue":"none","description":"Determines which axis the tooltip should track the cursor on."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled tooltip.\nThere's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set)."},{"name":"triggerProps","type":"TooltipTriggerProps<TPayload>","required":false,"defaultValue":null,"description":"Full Trigger props, including native props, ref, render and payload. Overrides the shorthand trigger defaults."},{"name":"withExitAnimation","type":"boolean","required":false,"defaultValue":null,"description":"Fades and slides the popup out when it closes instead of hiding it at once."}],"parts":[{"name":"Root","props":[{"name":"actionsRef","type":"RefObject<TooltipRootActions | null>","required":false,"defaultValue":null,"description":"A ref to imperative actions.\n- `unmount`: Ends the closing phase of the tooltip after an externally controlled closing animation finishes.\nCall `preventUnmountOnClose()` in `onOpenChange` first, otherwise the tooltip completes closing on its own.\nWhether it leaves the DOM is decided by `keepMounted` on the portal.\n- `close`: Closes the tooltip imperatively when called."},{"name":"children","type":"ReactNode | PayloadChildRenderFunction<Payload>","required":false,"defaultValue":null,"description":"Parts or a render function receiving the active trigger payload. Root renders no DOM node."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Whether the tooltip is initially open.\n\nTo render a controlled tooltip, use the `open` prop instead."},{"name":"defaultTriggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the tooltip is disabled."},{"name":"disableHoverablePopup","type":"boolean","required":false,"defaultValue":"false","description":"Whether the tooltip contents can be hovered without closing the tooltip."},{"name":"handle","type":"TooltipHandle<Payload>","required":false,"defaultValue":null,"description":"Connects detached triggers and imperative open/close actions."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel()."},{"name":"onOpenChangeComplete","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Event handler called after any animations complete when the tooltip is opened or closed."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the tooltip is currently open."},{"name":"trackCursorAxis","type":"\"both\" | \"none\" | \"x\" | \"y\"","required":false,"defaultValue":"none","description":"Determines which axis the tooltip should track the cursor on."},{"name":"triggerId","type":"string | null","required":false,"defaultValue":null,"description":"ID of the trigger that the tooltip is associated with.\nThis is useful in conjunction with the `open` prop to create a controlled tooltip.\nThere's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set)."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: TooltipTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the tooltip. Specified in milliseconds."},{"name":"closeOnClick","type":"boolean","required":false,"defaultValue":"true","description":"Whether the tooltip should close when this trigger is clicked."},{"name":"delay","type":"number","required":false,"defaultValue":"600","description":"How long to wait before opening the tooltip on hover. Specified in milliseconds."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables tooltip interaction for this trigger without disabling its native element."},{"name":"handle","type":"TooltipHandle<Payload>","required":false,"defaultValue":null,"description":"A handle to associate the trigger with a tooltip."},{"name":"payload","type":"Payload","required":false,"defaultValue":null,"description":"A payload to pass to the tooltip when it is opened."},{"name":"ref","type":"((((instance: HTMLButtonElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<HTMLButtonElement | null>) & (((instance: HTMLElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<...>)) | null","required":false,"defaultValue":null,"description":"Ref to the rendered trigger element, a button by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipTriggerState>","required":false,"defaultValue":null,"description":"Composes a native element or a component that forwards attributes, handlers and ref."},{"name":"style","type":"CSSProperties | ((state: TooltipTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Portal","props":[{"name":"className","type":"string | ((state: TooltipPortalState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination. Defaults to the current theme container, then the document body."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Whether to keep the portal mounted in the DOM while the popup is hidden."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the portal div."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPortalState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipPortalState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Positioner","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"center","description":"How to align the popup relative to the specified side."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Additional offset along the alignment axis in pixels.\nAlso accepts a function that returns the offset to read the dimensions of the anchor\nand positioner elements, along with its side and alignment.\n\nThe function takes a `data` object parameter with the following properties:\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the positioner is aligned against.\n- `data.align`: how the positioner is aligned relative to the specified side."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"arrowPadding","type":"number","required":false,"defaultValue":"5","description":"Minimum distance to maintain between the arrow and the edges of the popup.\n\nUse it to prevent the arrow element from hanging out of the rounded corners of a popup."},{"name":"className","type":"string | ((state: TooltipPositionerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionAvoidance","type":"CollisionAvoidance","required":false,"defaultValue":null,"description":"Determines how to handle collisions when positioning the popup.\n\n`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):\n- `'flip'`: keep the requested side when it fits; otherwise try the opposite side\n (`top` and `bottom`, or `left` and `right`).\n- `'shift'`: never change side; keep the requested side and move the popup within\n the clipping boundary so it stays visible.\n- `'none'`: do not correct side-axis overflow.\n\n`align` controls overflow on the alignment axis (`start`/`center`/`end`):\n- `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.\n- `'shift'`: keep side and requested alignment, then nudge the popup along the\n alignment axis to fit.\n- `'none'`: do not correct alignment-axis overflow.\n\n`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the\npreferred axis cannot fit:\n- `'start'`: allow perpendicular fallback and try the logical start side first\n (`top` before `bottom`, or `left` before `right` in LTR).\n- `'end'`: allow perpendicular fallback and try the logical end side first\n (`bottom` before `top`, or `right` before `left` in LTR).\n- `'none'`: do not fallback to the perpendicular axis.\n\nWhen `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.\nIf `align` is omitted, it defaults to `'flip'`."},{"name":"collisionBoundary","type":"Boundary","required":false,"defaultValue":"clipping-ancestors","description":"An element or a rectangle that delimits the area that the popup is confined to."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"disableAnchorTracking","type":"boolean","required":false,"defaultValue":"false","description":"Whether to disable the popup from tracking any layout shift of its positioning anchor."},{"name":"positionMethod","type":"\"absolute\" | \"fixed\"","required":false,"defaultValue":"absolute","description":"Determines which CSS `position` property to use."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the positioning div. Native props, styles and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPositionerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"top","description":"Preferred physical or logical side of the anchor. Defaults to top."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Distance from the anchor. Defaults to 0 in compound usage. Accepts a number or positioning function."},{"name":"sticky","type":"boolean","required":false,"defaultValue":"false","description":"Whether to maintain the popup in the viewport after\nthe anchor element was scrolled out of view."},{"name":"style","type":"CSSProperties | ((state: TooltipPositionerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Popup","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Content rendered as supplied. Does not create a portal, positioner, title layout or arrow."},{"name":"className","type":"string | ((state: TooltipPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"maxWidth","type":"MaxWidth<string | number>","required":false,"defaultValue":null,"description":"Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the popup div. Native props, styles and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"withExitAnimation","type":"boolean","required":false,"defaultValue":"false","description":"Enables the optional Twenty exit transition."}]},{"name":"Body","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional title content, displayed with medium weight. Omit it for a description-only tooltip."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional secondary content. Preserves line breaks and wraps long text."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the body div. Native props, styles and render target this element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Composes the body root through an element or render callback while preserving its layout and content."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional decorative node before the title. Omitted when the title is empty."}]},{"name":"Arrow","props":[{"name":"className","type":"string | ((state: TooltipArrowState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the arrow div. Compose inside Popup."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipArrowState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipArrowState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Viewport","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"The content to render inside the transition container."},{"name":"className","type":"string | ((state: TooltipViewportState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the content-transition div. Useful when several triggers share changing content."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipViewportState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: TooltipViewportState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Provider","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Tooltips sharing delay, closeDelay and timeout configuration. Provider renders no DOM node."},{"name":"closeDelay","type":"number","required":false,"defaultValue":null,"description":"How long to wait before closing a tooltip. Specified in milliseconds."},{"name":"delay","type":"number","required":false,"defaultValue":null,"description":"How long to wait before opening the tooltip on hover. Specified in milliseconds."},{"name":"timeout","type":"number","required":false,"defaultValue":"400","description":"Another tooltip will open instantly if the previous tooltip\nis closed within this timeout. Specified in milliseconds."}]}]}},{"name":"Toast","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Toast\ndescription: Display status messages with optional details, actions, and progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ToastReference from '/snippets/ui/generated/components/feedback/toast.mdx';\nimport ToastProviderReference from '/snippets/ui/generated/components/feedback/toast-provider.mdx';\nimport ToasterReference from '/snippets/ui/generated/components/feedback/toaster.mdx';\n\n## Overview\n\n`Toast` renders one notification. Your application controls when it appears, its position, and when it is removed.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--display\"\n title=\"Toast example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SavedNotification = () => {\n const [isOpen, setIsOpen] = useState(true);\n\n return (\n <>\n <Button onClick={() => setIsOpen(true)}>Show notification</Button>\n {isOpen && (\n <Toast status=\"success\" progress={100} onClose={() => setIsOpen(false)}>\n Changes saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n## Visual options\n\nCompare neutral, success, error, information, and warning feedback with the same message and progress.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--catalog\"\n title=\"Toast feedback statuses\"\n height={530}\n/>\n\nFor application notifications, wrap the application in `ToastProvider`, mount a `Toaster` inside it, and use `useToast()` from descendants. Each provider owns an independent notification store, countdowns, and dismissal lifecycle. Multiple Toasters can mirror the same provider.\n\n## Application notifications\n\n```tsx\nimport { useState } from 'react';\n\nimport {\n ToastProvider,\n Toaster,\n useToast,\n} from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst SaveNotificationButton = () => {\n const { enqueueToast } = useToast();\n\n return (\n <Button\n onClick={() =>\n enqueueToast({\n children: 'Record saved',\n status: 'success',\n })\n }\n >\n Add saved notification\n </Button>\n );\n};\n\nexport const Notifications = () => {\n const [limit, setLimit] = useState(3);\n\n return (\n <ToastProvider limit={limit}>\n <SaveNotificationButton />\n <Button onClick={() => setLimit(1)}>Keep one notification</Button>\n <Button onClick={() => setLimit(3)}>Keep three notifications</Button>\n <Toaster />\n </ToastProvider>\n );\n};\n```\n\n`enqueueToast` accepts Toast props and an optional `dedupeKey`, and returns the notification ID. A matching visible key returns the existing ID without adding another notification. `updateToast({ id, ...changes })` patches that live notification. `closeToast(id)` dismisses one notification; `closeToast()` dismisses all visible notifications in the provider.\n\nThe provider defaults to three visible notifications. `limit` must be a positive integer and can change while the provider is mounted. Lowering it or adding above it dismisses the oldest visible notifications first. Increasing it leaves existing notifications unchanged and does not restore dismissed notifications. Configuration changes preserve the store, surviving IDs, order, and remaining countdown time.\n\n## Provider lifecycle\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--documentation\"\n title=\"Shared notification lifecycle\"\n height={430}\n/>\n\nMultiple Toasters inside a provider render the same notifications. Updates and dismissal apply to every mirror, and each notification has one shared countdown. Hover or focus inside any mirror pauses it; it resumes after all mirrors release both. Mounting another Toaster does not restart the countdown or create another callback lifecycle. Use separate providers for independent queues.\n\nFor provider notifications, expiry, the close button, `closeToast`, and limit eviction call the latest `onClose` once. The notification is already dismissed when the callback runs, so updates and repeated close requests for that ID have no effect. `onCancel` remains a separate action callback and does not dismiss automatically.\n\nDismissed notifications are inert during exit animations. Their entries are removed after all rendered mirrors finish their exit work or unmount. Unmounting the last Toaster clears dismissed entries and freezes the remaining time for visible notifications. Remounting a Toaster resumes that time. Unmounting the provider discards its notifications and cancels countdown and exit work without calling `onClose`. Captured `enqueueToast`, `updateToast`, and `closeToast` operations from that provider have no effect after it unmounts.\n\n`getToastProps` adapts each notification’s content and presentation. Set `duration` and `progress` in `enqueueToast` or `updateToast` so every mirror shares the same timing configuration. Existing timing overrides through `getToastProps` remain supported when all mirrors return the same duration and progress for a notification. The provider retains the ID, dismissal handler, and shared countdown.\n\n`container` selects a Toaster’s portal destination. When omitted, it uses the surrounding theme container or `document.body`. An explicit element renders there; `null` defers rendering. Visible notifications remain queued, with their countdowns paused while no Toaster is rendered. Portals retain the surrounding theme and direction. Set `aria-label` on each Toaster to localize its default region name, \"Notifications\", and give mirrored regions appropriate names.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--portal-documentation\"\n title=\"Scoped notification portal\"\n height={430}\n/>\n\n## Update a live notification\n\nUse the ID returned by `enqueueToast` to update content, feedback status, actions, or callbacks in place. Updates preserve the notification's ID and position. Unknown or dismissed IDs have no effect, including while the dismissal animation runs. Each `useToast()` call targets its closest provider.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster--updates-documentation\"\n title=\"Update a live notification\"\n height={380}\n/>\n\n```tsx\nimport { useToast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveButtonProps = {\n saveRecord: () => Promise<void>;\n onViewRecord: () => void;\n};\n\nexport const SaveButton = ({ saveRecord, onViewRecord }: SaveButtonProps) => {\n const { enqueueToast, updateToast } = useToast();\n\n const save = async () => {\n const id = enqueueToast({\n children: 'Saving record',\n status: 'info',\n progress: 0,\n });\n\n try {\n await saveRecord();\n updateToast({\n id,\n children: 'Record saved',\n status: 'success',\n progress: undefined,\n action: <Button onClick={onViewRecord}>View record</Button>,\n });\n } catch {\n updateToast({\n id,\n children: 'Record could not be saved',\n status: 'error',\n progress: undefined,\n });\n }\n };\n\n return <Button onClick={save}>Save record</Button>;\n};\n```\n\n`ToastUpdate` requires `id` and accepts partial Toast options. Omitted fields keep their current values. Explicit `undefined` clears an optional field or restores its component default, such as `progress: undefined` or `status: undefined`. Pass `null` to remove a content slot, including `description`, `icon`, or `action`. Setting `cancelLabel: null` hides the cancel control while preserving its callback. Callback changes take effect on the existing notification. `dedupeKey` belongs to enqueueing and cannot be updated.\n\n## Dismissal timing\n\nThe countdown defaults to 6,000 milliseconds. It pauses while the pointer is over the toast or keyboard focus is inside it, and resumes only after both leave. With multiple Toasters, pause state is shared across their mirrors. The visual countdown follows the remaining dismissal time. Automatic dismissal also works when reduced motion disables the animation.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-timing--documentation\"\n title=\"Toast timing controls\"\n height={480}\n/>\n\n| Operation | Countdown behavior |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Update content, status, actions, or callbacks | Preserve the remaining time. Repeated updates do not extend it. |\n| Supply `duration` to `updateToast` | Start a fresh duration, including when the value is unchanged. `duration: undefined` restores the default and restarts it. |\n| Change a standalone `Toast`'s `duration` prop | Start a fresh duration. Rendering the same value again keeps the remaining time. |\n| Set `duration: 0` | Keep the toast open until it is dismissed. |\n| Supply `progress` | Stop the countdown while progress is present. |\n| Remove `progress` | Start a fresh duration, or keep it open when its duration is zero. |\n| Update while hovered or focused | Apply the same rules, keeping the resulting countdown paused until both pointer and focus leave. |\n\nFor example, `updateToast({ id, children: 'Still saving' })` preserves the remaining time, while `updateToast({ id, duration: 6000 })` gives the reader another six seconds. These rules apply to the existing notification without changing its ID or position.\n\n## Dismissible notification\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveNotification = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <>\n <Button onClick={() => setVisible(true)}>Show saved notification</Button>\n {visible && (\n <Toast\n status=\"success\"\n description=\"Your changes are available to your team.\"\n duration={6000}\n onClose={() => setVisible(false)}\n >\n Record saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n`onClose` is called once by the close button or when the countdown completes. Remove the toast in that callback. Use `duration={0}` for a notification that stays open until dismissal.\n\n## Progress and cancellation\n\n```tsx\nimport { Toast } from 'twenty-ui/components/feedback';\n\ntype ImportProgressProps = { progress: number; onCancel: () => void };\n\nexport const ImportProgress = ({ progress, onCancel }: ImportProgressProps) => (\n <Toast\n status=\"info\"\n progress={progress}\n description=\"You can continue working while the import runs.\"\n onCancel={onCancel}\n cancelLabel=\"Cancel import\"\n >\n Importing records: {progress}%\n </Toast>\n);\n```\n\nPassing `progress` supplies a percentage and disables the countdown. Remove it after the operation finishes to start a fresh duration. Cancellation invokes `onCancel`; the parent owns cancellation and removal. `cancelLabel` accepts a React node for the button content. Children, `description`, `icon`, and `action` also accept caller-owned React nodes. Use Twenty UI controls for interactive actions and provide their accessible names.\n\n## Appearance and announcements\n\n`status` accepts `neutral`, `info`, `success`, `warning`, or `error` and defaults to `neutral`. It expresses feedback meaning and selects the icon and theme palette. Toast has one supported appearance, so it exposes no appearance `variant` or palette `color` option. Use `icon` to replace the icon, `icon={null}` to omit it, and `iconLabel` when the default icon needs its own accessible name.\n\nThe default role is `status` with polite announcements. Use `role=\"alert\"` for urgent feedback. Set `cancelLabel` and `closeLabel` to localize the controls, and allow enough time to read the content or interact with its actions.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, styles, class names, event handlers, and refs target the root. Use `render` to compose another element or component while retaining those props and the ref. Toaster portals inherit the surrounding theme and text direction.\n\n<ToastReference />\n\n### ToastProvider\n\n<ToastProviderReference />\n\n### Toaster\n\nNative div attributes, styles, class names, and refs target the notification region.\n\n<ToasterReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Toast","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/toast","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional footer node, such as a Button with a caller-owned action."},{"name":"cancelLabel","type":"ReactNode","required":false,"defaultValue":"Cancel","description":"Cancel button content node. Defaults to Cancel. Pass null to hide the control."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Main message node. Callers own its content and accessible text."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional class names merged onto the root."},{"name":"closeLabel","type":"string","required":false,"defaultValue":"Close","description":"Accessible name of the close button. Defaults to Close."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional supporting content node rendered below the message."},{"name":"duration","type":"number","required":false,"defaultValue":"6000","description":"Milliseconds before onClose is called, defaulting to 6000. Zero keeps the toast open. Changes restart the countdown; live updateToast duration patches restart it even when unchanged. Hover and keyboard focus pause it until both leave."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":null,"description":"Leading icon node. Defaults to the status icon. Pass null to omit it."},{"name":"iconLabel","type":"string","required":false,"defaultValue":null,"description":"Accessible name of the default icon. Without it, the icon is decorative."},{"name":"onCancel","type":"(() => void)","required":false,"defaultValue":null,"description":"Called when the cancel button is clicked. Providing it and renderable cancelLabel content shows the button."},{"name":"onClose","type":"(() => void)","required":false,"defaultValue":null,"description":"For standalone Toast, called once per mount by the close button or expiry. For provider notifications, called once on close, expiry, closeToast, or limit eviction, after dismissal and before exit cleanup. Provider teardown does not call it."},{"name":"progress","type":"number","required":false,"defaultValue":null,"description":"Completion percentage. Providing it disables the countdown. Removing it starts a fresh duration."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element supplied through render."},{"name":"render","type":"RenderProp<Record<string, unknown>>","required":false,"defaultValue":null,"description":"Element or callback composition for the root. Native props and the ref target the rendered element."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"neutral","description":"Feedback meaning: neutral, info, success, warning, or error. Defaults to neutral and selects the icon and theme palette."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles forwarded to the root."}]}},{"name":"Text","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: Text\ndescription: Compose theme typography with single-line truncation or a limited number of lines.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport TextReference from '/snippets/ui/generated/typography/text.mdx';\n\n## Overview\n\n`Text` provides typography and overflow handling. It renders a `div` by default. Omit `size`, `weight` and `color` to keep inheriting typography from its surroundings.\n\n<StoryEmbed\n storyId=\"ui-typography-text--display\"\n title=\"Text example\"\n height={90}\n/>\n\n## Usage\n\nGive the text a constrained width, then set `truncate` to show an ellipsis when it overflows:\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ContactName = () => (\n <Text truncate style={{ maxWidth: 160 }}>\n Alexandra Montgomery\n </Text>\n);\n```\n\n## Choose typography\n\n`size` uses the existing theme scale. It changes font size, with no height, font-family or line-height default:\n\n| Size | Theme value |\n| ----- | ----------- |\n| `xxs` | `0.625rem` |\n| `xs` | `0.85rem` |\n| `sm` | `0.92rem` |\n| `md` | `1rem` |\n| `lg` | `1.23rem` |\n| `xl` | `1.54rem` |\n| `xxl` | `1.85rem` |\n\n`weight` accepts `regular` (400), `medium` (500) or `semibold` (600). `color` accepts `primary`, `secondary`, `tertiary` or `light`. Each omitted prop inherits independently. The visual size does not change the semantic element.\n\n<StoryEmbed\n storyId=\"ui-typography-text--typography-catalog\"\n title=\"Text typography scale\"\n height={410}\n/>\n\nFor captions, compose the small size, semibold weight and light color:\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const Caption = () => (\n <Text size=\"xs\" weight=\"semibold\" color=\"light\">\n Workspace\n </Text>\n);\n```\n\nUse native `style` for runtime colors and parent-layout constraints. Caller classes and render composition target the same text element. Text adds no typography defaults when these props are omitted.\n\n## Limit the number of lines\n\n<StoryEmbed\n storyId=\"ui-typography-text--catalog\"\n title=\"Text overflow options\"\n height={210}\n/>\n\nUse `lineClamp` with a positive integer. Choose either `truncate` or `lineClamp`; their props are mutually exclusive.\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const Summary = () => (\n <Text lineClamp={2} style={{ maxWidth: 240 }}>\n Follow up with the customer about their onboarding milestones and upcoming\n renewal.\n </Text>\n);\n```\n\n## Choose an element\n\nUse `render` when the text needs another semantic element:\n\n```tsx\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const Description = () => (\n <Text render={<p />}>Account description</Text>\n);\n```\n\nTruncation affects the visual presentation; it does not shorten the text in the DOM. Provide a way to read the full content when the visible portion is insufficient.\n\n## Props\n\nNative attributes, children, refs, class names, and styles target the rendered text element. `TextProps` is exported from `twenty-ui/primitives/typography`. Text content is rendered unchanged, including caller-provided links.\n\n<TextReference />\n\n## Migration\n\n`color` now selects a semantic theme color. Move arbitrary CSS color values from a native `color` attribute to `style={{ color: customColor }}`. Existing styles, classes and render composition continue to target the text element.\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"Text","entryPoint":"twenty-ui/primitives/typography","slug":"typography/text","props":[{"name":"color","type":"\"light\" | \"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":null,"description":"Semantic text color. Omitted values inherit; native style supports runtime colors."},{"name":"lineClamp","type":"number","required":false,"defaultValue":null,"description":"Positive integer limiting the number of visible lines. Cannot be combined with `truncate`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default div. Native props and the ref target the rendered text element."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\" | \"xxs\"","required":false,"defaultValue":null,"description":"Font size from the theme scale. Omitted values inherit; this does not set height."},{"name":"truncate","type":"boolean","required":false,"defaultValue":null,"description":"Truncates one line with an ellipsis. Cannot be combined with `lineClamp`."},{"name":"weight","type":"\"medium\" | \"regular\" | \"semibold\"","required":false,"defaultValue":null,"description":"Theme font weight. Omitted values inherit."}]}},{"name":"Avatar","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Avatar\ndescription: Represent a person or record with an image, initial, or icon.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport AvatarReference from '/snippets/ui/generated/data-display/avatar.mdx';\n\n## Overview\n\n`Avatar` shows an image with a first-letter fallback. Use it beside a record name or inside a [Chip](/ui/primitives/data-display/chip). Its default root is a presentational `span`.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--display\"\n title=\"Avatar example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const WorkspaceAvatar = () => (\n <Avatar\n name=\"Acme\"\n colorSeed=\"acme-app\"\n shape=\"square\"\n variant=\"outline\"\n size=\"md\"\n />\n);\n```\n\nWhen the image is absent or fails to load, the fallback shows the first letter of the trimmed name in uppercase. An empty name shows `-`. `colorSeed` chooses stable fallback colors and defaults to `name`; use a record identifier to keep the color stable when the name changes.\n\nThe image and default fallback are decorative. `name` supplies the visual initial and fallback colors without adding an accessible label. When the avatar is the only representation of a person or record, set `imageProps={{ alt: name }}` to label both the image and default fallback. Keep the avatar decorative when a visible name or labeled owner already provides that information.\n\n`imageProps` accepts the complete image contract, including `srcSet`, `sizes`, `crossOrigin`, `referrerPolicy`, native events, refs, and `render`. Its `src` overrides the shorthand `src`. `fallbackProps` accepts the complete fallback contract, including `delay`, children, labeling, refs, and `render`. A custom fallback `render` owns its accessibility semantics; set `aria-hidden` explicitly when it is decorative.\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype RecordAvatarProps = {\n name: string;\n imageUrl?: string;\n initials: string;\n};\n\nexport const RecordAvatar = ({\n name,\n imageUrl,\n initials,\n}: RecordAvatarProps) => (\n <Avatar\n name={name}\n src={imageUrl}\n size=\"lg\"\n imageProps={{ alt: name, decoding: 'async', referrerPolicy: 'no-referrer' }}\n fallbackProps={{ children: initials, delay: 150 }}\n />\n);\n```\n\n## Compose the parts\n\nUse `Avatar.Root`, `Avatar.Image`, and `Avatar.Fallback` when you own the anatomy. Root supplies the size, shape, and fallback appearance; it does not generate children or accessible labels.\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype ContactAvatarProps = {\n name: string;\n imageUrl?: string;\n initials: string;\n};\n\nexport const ContactAvatar = ({\n name,\n imageUrl,\n initials,\n}: ContactAvatarProps) => (\n <Avatar.Root name={name} shape=\"circle\" size=\"xxl\">\n <Avatar.Image src={imageUrl} alt={name} decoding=\"async\" />\n <Avatar.Fallback role=\"img\" aria-label={name} delay={150}>\n {initials}\n </Avatar.Fallback>\n </Avatar.Root>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--parts\"\n title=\"Avatar parts\"\n height={110}\n/>\n\nThe parts share Base UI's image loading state. Image renders an `img` after a successful load by default, and Fallback renders a `span` while the image is absent, loading, or has failed. `delay` postpones the initial fallback display in milliseconds and defaults to `0`. A changed source is loaded again and can replace either the current image or fallback.\n\n`Avatar.Image` exposes `onLoadingStatusChange` with `idle`, `loading`, `loaded`, and `error` status values. The callback runs when Base UI reports a non-idle status change; unmounting the Image part resets the shared root state to `idle`. Root, Image, and Fallback accept state-aware `className`, `style`, and `render` functions with `imageLoadingStatus`; Image also exposes `transitionStatus`.\n\nUse `keepMounted` on Image when the rendered image must load in place, including `loading=\"lazy\"` or an optimized image component. Forward native attributes, events, and the ref from custom image renderers. A mounted image can still be loading or failed; inspect loading state rather than treating its presence as success.\n\nThe front component renderer currently supports the default preload path with `src`. Its host image does not receive `srcSet`, `sizes`, `loading`, `decoding`, or `referrerPolicy`. A changing custom `render` function with `keepMounted` can leave a decoded image hidden because the worker cannot read its completion state or dimensions. Use default preloading there until those renderer capabilities are available.\n\nThe public `AvatarRootProps`, `AvatarImageProps`, `AvatarFallbackProps`, `AvatarRootState`, `AvatarImageState`, `AvatarFallbackState`, and `AvatarImageLoadingStatus` types are exported from `twenty-ui/primitives/data-display`. Refs target the rendered DOM element: `span`, `img`, and `span` by default, or the element supplied through `render`.\n\n## Shape and appearance\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--catalog\"\n title=\"Avatar sizes and shapes\"\n height={320}\n/>\n\n`shape` accepts `square`, `rounded-square`, or `circle`. Sizes are `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), and `xxl` (40px). Both `xl` and `xxl` use 16px fallback text.\n\nThe former 40px `xl` size is now `xxl`. Update existing `size=\"xl\"` usages to `size=\"xxl\"` when they should remain 40px.\n\n`variant=\"outline\"` adds a border to the fallback. The `color`, `backgroundColor`, and `borderColor` overrides customize the fallback, while a loaded image keeps its original appearance.\n\n```tsx\nimport { IconUser } from 'twenty-ui/icon';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const ContactIcon = () => (\n <Avatar\n icon={<IconUser />}\n shape=\"rounded-square\"\n size=\"xxl\"\n role=\"img\"\n aria-label=\"Contact\"\n />\n);\n```\n\nAn `icon` takes precedence over both the image and the first-letter fallback. The icon itself is decorative, so label the root when it conveys information. `pulsing` animates opacity and respects reduced-motion preferences.\n\n## Open a profile\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype ProfileAvatarProps = {\n onOpenProfile: () => void;\n disabled?: boolean;\n};\n\nexport const ProfileAvatar = ({\n onOpenProfile,\n disabled = false,\n}: ProfileAvatarProps) => (\n <Avatar\n name=\"Jane\"\n shape=\"circle\"\n size=\"lg\"\n render={\n <button\n type=\"button\"\n disabled={disabled}\n aria-label=\"Open Jane's profile\"\n onClick={onOpenProfile}\n />\n }\n />\n);\n```\n\n<StoryEmbed\n storyId=\"ui-data-display-avatar--button-composition\"\n title=\"Avatar composed as a button\"\n height={110}\n/>\n\nCompose a native button for actions. It owns focus, Enter and Space activation, and disabled behavior. Supply an action-specific accessible name. Put `onClick` and `disabled` on the rendered button; shorthand Avatar has no `onClick`, `disabled`, or `nativeButton` prop.\n\nFor navigation, compose an anchor with an `href` or a router link that preserves anchor semantics. Native links activate with Enter. Keep navigation and disabled behavior with the link or interactive component you compose.\n\n```tsx\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const ProfileLink = () => (\n <Avatar\n name=\"Jane\"\n shape=\"circle\"\n size=\"lg\"\n render={<a href=\"/people/jane\" aria-label=\"Open Jane's profile\" />}\n />\n);\n```\n\n## Migrate clickable avatars\n\nCompose a native button through `render` for actions, or an anchor or router link for navigation. Move `onClick` and `disabled` onto that owner and remove `nativeButton`. Give the owner a useful accessible name and avoid nesting interactive elements. `Avatar.Root` and the other explicit parts retain the complete Base UI event contract.\n\nShorthand avatars are decorative by default. `name` does not name the image, fallback, or interactive owner. Use a nonempty `imageProps.alt` only when the avatar conveys identity that is not already supplied by visible text or an owner label. With explicit parts, supply image alternative text and fallback labels or decorative attributes yourself, and keep translated content in your application.\n\n## Props\n\nTypes and defaults are generated from the public component types. The explicit parts accept native attributes and event handlers. Shorthand Avatar omits `onClick`; supply it on the owner passed through `render`.\n\n<AvatarReference />\n\n<PageBanner illustration=\"page-cover-profile\" />\n","api":{"name":"Avatar","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/avatar","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"Background color override for a first-letter fallback."},{"name":"borderColor","type":"string","required":false,"defaultValue":null,"description":"Border color override for the outline fallback."},{"name":"className","type":"string | ((state: AvatarRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"Text color override for a first-letter fallback."},{"name":"colorSeed","type":"string","required":false,"defaultValue":null,"description":"Stable value used to choose fallback colors. Defaults to `name`."},{"name":"fallbackProps","type":"AvatarFallbackProps","required":false,"defaultValue":null,"description":"Complete `Avatar.Fallback` props, including caller-owned children, labeling, refs, `render`, and fallback `delay` in milliseconds."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information."},{"name":"imageProps","type":"AvatarImageProps","required":false,"defaultValue":null,"description":"Complete `Avatar.Image` props, including native image attributes, refs, `render`, `keepMounted`, and `onLoadingStatusChange`. Alternative text defaults to an empty string. Supply a nonempty `alt` to label the image and default fallback."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name used for the first-letter fallback and fallback colors. Does not add an accessible label."},{"name":"pulsing","type":"boolean","required":false,"defaultValue":"false","description":"Animates the avatar opacity. Respects reduced-motion preferences."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner."},{"name":"ring","type":"boolean","required":false,"defaultValue":"false","description":"Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct."},{"name":"shape","type":"\"circle\" | \"rounded-square\" | \"square\"","required":false,"defaultValue":"square","description":"Shape of the avatar and its fallback."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px)."},{"name":"src","type":"string | null","required":false,"defaultValue":null,"description":"Image URL. A missing or failed image shows the fallback. `imageProps.src` overrides this value."},{"name":"style","type":"CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"outline\" | \"soft\"","required":false,"defaultValue":"soft","description":"Visual treatment of the fallback."}],"parts":[{"name":"Root","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"Background color override for a first-letter fallback."},{"name":"borderColor","type":"string","required":false,"defaultValue":null,"description":"Border color override for the outline fallback."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned Image, Fallback, and other content."},{"name":"className","type":"string | ((state: AvatarRootState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"Text color override for a first-letter fallback."},{"name":"colorSeed","type":"string","required":false,"defaultValue":null,"description":"Stable value used to choose fallback colors. Defaults to `name`."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Name used to choose fallback colors. Does not add children or accessible labels."},{"name":"pulsing","type":"boolean","required":false,"defaultValue":"false","description":"Animates the avatar opacity. Respects reduced-motion preferences."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner."},{"name":"ring","type":"boolean","required":false,"defaultValue":"false","description":"Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct."},{"name":"shape","type":"\"circle\" | \"rounded-square\" | \"square\"","required":false,"defaultValue":"square","description":"Shape of the avatar and its fallback."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px)."},{"name":"style","type":"CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"variant","type":"\"outline\" | \"soft\"","required":false,"defaultValue":"soft","description":"Visual treatment of the fallback."}]},{"name":"Image","props":[{"name":"alt","type":"string","required":false,"defaultValue":null,"description":"Caller-owned alternative text. Use an empty string for decorative images."},{"name":"className","type":"string | ((state: AvatarImageState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"crossOrigin","type":"\"\" | \"anonymous\" | \"use-credentials\"","required":false,"defaultValue":null,"description":"Native image cross-origin policy, also used during preloading."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown."},{"name":"loading","type":"\"eager\" | \"lazy\"","required":false,"defaultValue":null,"description":"Native eager or lazy loading. Use keepMounted for lazy loading."},{"name":"onLoadingStatusChange","type":"((status: ImageLoadingStatus) => void)","required":false,"defaultValue":null,"description":"Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback."},{"name":"referrerPolicy","type":"\"\" | \"no-referrer-when-downgrade\" | \"no-referrer\" | \"origin-when-cross-origin\" | \"origin\" | \"same-origin\" | \"strict-origin-when-cross-origin\" | \"strict-origin\" | \"unsafe-url\"","required":false,"defaultValue":null,"description":"Native image referrer policy, also used during preloading."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState>","required":false,"defaultValue":null,"description":"Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref."},{"name":"sizes","type":"string","required":false,"defaultValue":null,"description":"Native responsive image sizes used with srcSet."},{"name":"src","type":"string","required":false,"defaultValue":null,"description":"Image URL. Image renders after a successful load unless keepMounted is enabled."},{"name":"srcSet","type":"string","required":false,"defaultValue":null,"description":"Native responsive image source candidates."},{"name":"style","type":"CSSProperties | ((state: AvatarImageState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Fallback","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned fallback content, such as initials or an icon."},{"name":"className","type":"string | ((state: AvatarFallbackState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"delay","type":"number","required":false,"defaultValue":"0","description":"Milliseconds before the initial fallback is shown. Defaults to 0."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarFallbackState>","required":false,"defaultValue":null,"description":"Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes."},{"name":"style","type":"CSSProperties | ((state: AvatarFallbackState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"Chip","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Chip\ndescription: Show compact caller-owned content with optional leading and trailing slots.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ChipReference from '/snippets/ui/generated/data-display/chip.mdx';\n\n## Overview\n\nUse `Chip` for compact references to people, records, or files. Use [Tag](/ui/primitives/data-display/tag) for colored categories and [Status](/ui/primitives/data-display/status) for workflow states.\n\n<StoryEmbed\n storyId=\"ui-data-display-chip--display\"\n title=\"Chip example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Avatar, Chip } from 'twenty-ui/primitives/data-display';\n\nexport const AssigneeChip = () => (\n <Chip\n variant=\"soft\"\n startElement={\n <Avatar name=\"Jane\" size=\"sm\" shape=\"circle\" imageProps={{ alt: '' }} />\n }\n >\n Jane\n </Chip>\n);\n```\n\nChildren accept text or nodes. `startElement` and `endElement` accept avatars, icons, or other content. `endElementDivider` adds a separator before the trailing content. The default chip is a `div`; its slots can contain a separate action while the chip itself remains presentational.\n\nChip never inserts a label. Supply a translated fallback from your application when needed. Omit children for content made entirely from slots. An interactive chip with only an icon needs a caller-supplied accessible name.\n\n## Appearance\n\n<StoryEmbed\n storyId=\"ui-data-display-chip--catalog\"\n title=\"Chip variants and sizes\"\n height={200}\n/>\n\n`size` accepts `sm` or `md`, with total heights of 20px and 24px. `variant` accepts `ghost`, `soft`, `solid`, `plain`, or `outline`; `ghost` is the default. Plain chips have no resting fill or leading padding. Outline chips have a strong 1px border, a lighter resting fill, and 8px inline padding on each side, with the same total height as other variants. Clickable plain and outline chips use the ghost hover and pressed backgrounds, pointer cursor, and focus ring. Use `shape=\"round\"` for a pill, `weight=\"medium\"` for emphasis, and `color=\"secondary\"` for secondary text.\n\n## Buttons and links\n\n```tsx\nimport { Avatar, Chip } from 'twenty-ui/primitives/data-display';\n\ntype AssigneeActionProps = {\n onOpenAssignee: () => void;\n disabled?: boolean;\n};\n\nexport const AssigneeAction = ({\n onOpenAssignee,\n disabled,\n}: AssigneeActionProps) => (\n <Chip\n render={<button type=\"button\" disabled={disabled} />}\n onClick={onOpenAssignee}\n aria-label=\"Open Jane's record\"\n startElement={\n <Avatar name=\"Jane\" size=\"sm\" shape=\"circle\" imageProps={{ alt: '' }} />\n }\n >\n Jane\n </Chip>\n);\n```\n\nSupplying `onClick` keeps the default `div`. Use `render` to compose an explicit native button, anchor, router link, or another appropriate owner. Native attributes, handlers, styles and the root ref reach that owner. A native button supplies keyboard activation and disabled behavior. Chip recognizes native disabled state and `aria-disabled` for appearance; `aria-disabled` alone does not prevent activation.\n\n`clickable` controls hover and pointer appearance and defaults to whether `onClick` is supplied. Set it explicitly for a link without a click handler. Do not nest buttons or links inside a chip that is itself interactive.\n\n```tsx\nimport { Chip } from 'twenty-ui/primitives/data-display';\n\nexport const DocumentationChip = () => (\n <Chip\n variant=\"outline\"\n shape=\"round\"\n render={<a href=\"https://twenty.com/developers\" />}\n clickable\n >\n Documentation\n </Chip>\n);\n```\n\nURL text remains plain text. Intentional links belong in caller content or in the explicit root composition.\n\n## Truncation and tooltips\n\n```tsx\nimport { Chip } from 'twenty-ui/primitives/data-display';\n\nexport const FileChip = () => (\n <Chip variant=\"soft\" maxWidth={180} tooltipPlace=\"top\">\n Quarterly customer research.pdf\n </Chip>\n);\n```\n\n`maxWidth` constrains the rendered chip width in pixels, including padding and any outline border. The same limit applies to plain chips with asymmetric padding. Content truncates with an ellipsis by default; `truncate={false}` leaves it unconstrained by truncation. String children supply their own tooltip text. Set `tooltipContent` for custom text or node content, `tooltipDelay` for the opening delay, and `isTooltipMultiline` to preserve line breaks. `alwaysShowTooltip` also enables the tooltip when content fits. These options follow [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip). Keep essential information available without relying on hover.\n\n## Migration\n\nReplace `emptyLabel` with caller-provided fallback children, and replace `forceEmptyText` or `isLabelHidden` with omitted children. Keep translated product fallbacks in the application. Replace `tooltipLabel` with `tooltipContent`. Move `disabled` to the explicit interactive owner and remove `nativeButton`. Add a native button or link through `render` wherever the chip previously relied on `onClick` to choose its element.\n\nReplace leading-padding overrides with `variant=\"plain\"`. Keep `clickable` enabled for native links and buttons that need hover and pressed feedback.\n\n## Props\n\nTypes and defaults are generated from the public component types. Native attributes and event handlers are also accepted.\n\n<ChipReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Chip","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/chip","props":[{"name":"alwaysShowTooltip","type":"boolean","required":false,"defaultValue":"false","description":"Shows the content tooltip even when the content is not truncated."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-owned content. Missing or empty children add no fallback label."},{"name":"clickable","type":"boolean","required":false,"defaultValue":"isDefined(onClick)","description":"Enables hover and pointer styling. Defaults to whether `onClick` is supplied; does not change the default div or add keyboard behavior."},{"name":"color","type":"\"primary\" | \"secondary\"","required":false,"defaultValue":"primary","description":"Primary or secondary text color."},{"name":"endElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content after the label. Avoid interactive content when the chip itself is a button or link."},{"name":"endElementDivider","type":"boolean","required":false,"defaultValue":"false","description":"Adds a divider before `endElement` when that slot has content."},{"name":"isTooltipMultiline","type":"boolean","required":false,"defaultValue":null,"description":"Preserves line breaks in the tooltip text."},{"name":"maxWidth","type":"number","required":false,"defaultValue":null,"description":"Maximum rendered chip width in pixels, including its leading and trailing padding and any outline border."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the default div. Compose a native button or link explicitly; that owner supplies disabled and native interaction behavior."},{"name":"shape","type":"\"round\" | \"square\"","required":false,"defaultValue":"square","description":"Square or round corners."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the chip."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content before the label, such as an avatar or icon."},{"name":"tooltipContent","type":"string","required":false,"defaultValue":null,"description":"Tooltip text. Defaults to string children. Supply text explicitly for node content."},{"name":"tooltipDelay","type":"number","required":false,"defaultValue":null,"description":"Delay in milliseconds before the tooltip opens."},{"name":"tooltipPlace","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":null,"description":"Position of the content tooltip."},{"name":"truncate","type":"boolean","required":false,"defaultValue":"true","description":"Truncates overflowing content with an ellipsis. Defaults to true."},{"name":"variant","type":"\"ghost\" | \"outline\" | \"plain\" | \"soft\" | \"solid\"","required":false,"defaultValue":"ghost","description":"Background and border treatment. Outline has a strong border, lighter resting fill and 8px inline padding. Plain has no resting fill or leading padding. Both use ghost hover and pressed feedback when clickable."},{"name":"weight","type":"\"medium\" | \"regular\"","required":false,"defaultValue":"regular","description":"Font weight of the content."}]}},{"name":"Tag","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Tag\ndescription: Label a category or attribute with a theme color and optional icon.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport TagReference from '/snippets/ui/generated/data-display/tag.mdx';\n\n## Overview\n\nUse `Tag` for categories, priorities, or other short attributes. Keep a text label so the meaning does not depend on color. Use [Status](/ui/primitives/data-display/status) when you need a state indicator and loading feedback.\n\n<StoryEmbed\n storyId=\"ui-data-display-tag--display\"\n title=\"Tag example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nexport const PriorityTag = () => <Tag color=\"red\">Urgent</Tag>;\n```\n\n`color` is required and accepts a theme color or `transparent`. The default element is always a `span`, including when a native click handler is supplied. Add a decorative icon with `startIcon`; the label supplies its accessible meaning.\n\n## Variants\n\n<StoryEmbed\n storyId=\"ui-data-display-tag--catalog\"\n title=\"Tag variants\"\n height={140}\n/>\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nexport const CategoryTags = () => (\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>\n <Tag color=\"blue\" variant=\"soft\">\n Customer\n </Tag>\n <Tag color=\"green\" variant=\"solid\">\n Partner\n </Tag>\n <Tag color=\"orange\" variant=\"outline\">\n Prospect\n </Tag>\n <Tag color=\"transparent\" variant=\"outline\" borderStyle=\"dashed\">\n Unassigned\n </Tag>\n </div>\n);\n```\n\n`soft` is the default treatment. `solid` emphasizes the label, `outline` adds a border, and `ghost` removes the background. Use `borderStyle=\"dashed\"` with `outline` and `weight=\"medium\"` for a stronger label.\n\n## Colors\n\n<StoryEmbed\n storyId=\"ui-data-display-tag--colors\"\n title=\"Tag theme colors\"\n height={240}\n/>\n\nKeep the label meaningful without relying on its color. The catalog compares the default soft treatment; the same palette is available to the other variants.\n\n## Filter by a tag\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\ntype CategoryFilterProps = {\n selected: boolean;\n onToggle: () => void;\n};\n\nexport const CategoryFilter = ({ selected, onToggle }: CategoryFilterProps) => (\n <Tag\n color=\"blue\"\n variant={selected ? 'solid' : 'outline'}\n render={<button type=\"button\" aria-pressed={selected} onClick={onToggle} />}\n >\n Customer\n </Tag>\n);\n```\n\nCompose an interactive owner through `render`. Put its click handler, native attributes, ref, and disabled state on that owner. A real button supplies focus, Enter, and Space activation. Selection state belongs to your application; use `aria-pressed` for a toggle and a visible treatment for the selected state. For navigation, render a link with its destination, such as `<a href=\"/records\" />`. Native owners retain Tag's appearance.\n\n## Long labels\n\nBy default, `truncate={true}` truncates constrained string labels and exposes their full text in a tooltip on hover. Set `truncate={false}` to keep the full label at its natural width without a tooltip, even when its parent is narrower. The parent layout owns wrapping, scrolling, and clipping.\n\n```tsx\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nexport const FullCategoryLabel = () => (\n <Tag color=\"green\" truncate={false}>\n Enterprise customer\n </Tag>\n);\n```\n\nNode children remain caller-owned content, so compose their text, translations, and intentional links directly.\n\n## Props\n\nTypes and defaults are generated from the public component types. Native attributes and event handlers are also accepted.\n\n<TagReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Tag","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/tag","props":[{"name":"borderStyle","type":"\"dashed\" | \"solid\"","required":false,"defaultValue":"solid","description":"Border style used by the outline variant."},{"name":"color","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"transparent\" | \"turquoise\" | \"violet\" | \"yellow\"","required":true,"defaultValue":null,"description":"Theme color for the tag, or `transparent` for an unfilled label."},{"name":"onClick","type":"MouseEventHandler<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Native click handler. Does not change the default span or add keyboard activation."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TagState>","required":false,"defaultValue":null,"description":"Replaces the default span. Compose a button or link to provide explicit interaction semantics."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative icon before the label. Hidden from assistive technology."},{"name":"truncate","type":"boolean","required":false,"defaultValue":"true","description":"Truncates constrained string labels and exposes the full text in a tooltip. Set to `false` to keep the full label at its natural width without a tooltip, even inside a narrower parent."},{"name":"variant","type":"\"ghost\" | \"outline\" | \"soft\" | \"solid\"","required":false,"defaultValue":"soft","description":"Visual treatment of the tag background and border."},{"name":"weight","type":"\"medium\" | \"regular\"","required":false,"defaultValue":"regular","description":"Font weight of the label."}]}},{"name":"Status","entryPoint":"twenty-ui/primitives/data-display","content":"---\ntitle: Status\ndescription: Show a named state with a colored indicator and optional loading feedback.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport StatusReference from '/snippets/ui/generated/data-display/status.mdx';\n\n## Overview\n\n`Status` combines a colored dot, a text label, and an optional loader. Use it for workflow or record states. Use [Tag](/ui/primitives/data-display/tag) for a category without the status indicator.\n\n<StoryEmbed\n storyId=\"ui-data-display-status--display\"\n title=\"Status example\"\n height={90}\n/>\n\n## Usage\n\n```tsx\nimport { Status } from 'twenty-ui/primitives/data-display';\n\nexport const RecordStatus = () => (\n <Status color=\"red\" weight=\"medium\">\n Urgent\n </Status>\n);\n```\n\n`color` is required and uses the theme palette. The label communicates the meaning independently of the color. The default element is always a `span`, including when a native click handler is supplied; `weight=\"medium\"` emphasizes its text.\n\n## Loading and announcements\n\n<StoryEmbed\n storyId=\"ui-data-display-status--loading\"\n title=\"Status while saving\"\n height={90}\n/>\n\n```tsx\nimport { Status } from 'twenty-ui/primitives/data-display';\n\ntype SaveStatusProps = { isSaving: boolean };\n\nexport const SaveStatus = ({ isSaving }: SaveStatusProps) => (\n <div role=\"status\">\n <Status color={isSaving ? 'blue' : 'green'} loading={isSaving}>\n {isSaving ? 'Saving' : 'Saved'}\n </Status>\n </div>\n);\n```\n\n`loading` shows a decorative loader after the label and defaults `aria-busy` to `true`. Supply `aria-busy` explicitly when the surrounding workflow owns that state. The component does not add a live region or change its text automatically. Keep a `role=\"status\"` container mounted when updates should be announced to assistive technology, and provide a label that describes the current state.\n\n## Change a state\n\n```tsx\nimport { Status } from 'twenty-ui/primitives/data-display';\n\ntype ChangeStatusActionProps = {\n isUpdating: boolean;\n onChangeStatus: () => void;\n};\n\nexport const ChangeStatusAction = ({\n isUpdating,\n onChangeStatus,\n}: ChangeStatusActionProps) => (\n <Status\n color=\"blue\"\n loading={isUpdating}\n render={\n <button\n type=\"button\"\n disabled={isUpdating}\n onClick={onChangeStatus}\n aria-label=\"Change record status\"\n />\n }\n >\n {isUpdating ? 'Updating' : 'In progress'}\n </Status>\n);\n```\n\nCompose an interactive owner through `render`. Put its click handler, native attributes, ref, and disabled state on that owner. A real button supplies focus, pointer, Enter, and Space activation. `Status.loading` displays progress; pass `disabled` to the button when the action should wait. For navigation, render a link with its destination, such as `<a href=\"/records\" />`. Native owners retain Status's appearance. Node children preserve caller-owned text, translations, and intentional links.\n\n## Props\n\nTypes and defaults are generated from the public component types. Native attributes and event handlers are also accepted.\n\n<StatusReference />\n\n<PageBanner illustration=\"page-cover-checkbox\" />\n","api":{"name":"Status","entryPoint":"twenty-ui/primitives/data-display","slug":"data-display/status","props":[{"name":"color","type":"\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"turquoise\" | \"violet\" | \"yellow\"","required":true,"defaultValue":null,"description":"Theme color used for the status background, text, and loader."},{"name":"loading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a decorative loader after the label and defaults aria-busy to true. The caller owns announcements and disabled interaction."},{"name":"onClick","type":"MouseEventHandler<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Native click handler. Does not change the default span or add keyboard activation."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, StatusState>","required":false,"defaultValue":null,"description":"Replaces the default span. Compose a button or link to provide explicit interaction semantics."},{"name":"weight","type":"\"medium\" | \"regular\"","required":false,"defaultValue":"regular","description":"Font weight of the label."}]}},{"name":"Heading","entryPoint":"twenty-ui/primitives/typography","content":"---\ntitle: Heading\ndescription: Render semantic headings with independent visual sizes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport HeadingReference from '/snippets/ui/generated/typography/heading.mdx';\n\n## Overview\n\n`Heading` renders an `h2` by default. Use `children` for its content, `level` for document structure, and `size` for appearance.\n\n<StoryEmbed\n storyId=\"ui-typography-heading--display\"\n title=\"Heading example\"\n height={90}\n/>\n\n## Usage\n\nChoose levels in document order. A smaller visual size does not change the level announced by assistive technology.\n\n```tsx\nimport { Heading } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceTitle = () => <Heading>Workspace settings</Heading>;\n```\n\nSizes `xs`, `sm`, `md`, `lg`, `xl`, and `xxl` use the matching font tokens. The larger sizes use `1.54rem` and `1.85rem`, respectively. All sizes keep semibold weight and a `1.1` line height. `Section.Header` and `Dialog.Title` accept the same size values. Headings have no outer margin; their surrounding layout owns spacing.\n\n## Color and composition\n\n<StoryEmbed\n storyId=\"ui-typography-heading--catalog\"\n title=\"Heading sizes and colors\"\n height={480}\n/>\n\nUse `color=\"secondary\"` for less prominent headings. `tertiary` is also available, but its contrast depends on the font size, theme, and background. Check readability when using it.\n\nNative attributes, styles, class names, and refs pass to the heading. Use `render` to compose with a custom element or component; that element is responsible for preserving heading semantics.\n\nFor a heading with supporting text or actions, use [Section](/ui/components/layout/section).\n\n## Props\n\n<HeadingReference />\n\n<PageBanner illustration=\"section-document-generator\" />\n","api":{"name":"Heading","entryPoint":"twenty-ui/primitives/typography","slug":"typography/heading","props":[{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Theme font color. Defaults to `primary`."},{"name":"level","type":"1 | 2 | 3 | 4 | 5 | 6","required":false,"defaultValue":"2","description":"Semantic heading level, from `h1` through `h6`. Does not change the visual size. Defaults to `2`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Visual font size from `xs` through `xxl`, independent of the heading level. Uses the matching font token. Defaults to `md`."}]}},{"name":"SettingsRow","entryPoint":"twenty-ui/components/settings","content":"---\ntitle: SettingsRow\ndescription: A labeled switch row with flat control props and native label composition.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SettingsRowReference from '/snippets/ui/generated/components/settings/settings-row.mdx';\n\n## Overview\n\n`SettingsRow` combines the appearance of [ListItem](/ui/primitives/navigation/list-item) with [Switch](/ui/primitives/input/switch). It renders a native label associated with its switch. Your application supplies the row content and owns any preference updates.\n\n<StoryEmbed\n storyId=\"ui-components-settingsrow--display\"\n title=\"Settings row example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { IconBell } from 'twenty-ui/icon';\n\nexport const NotificationSetting = () => (\n <SettingsRow startElement={<IconBell aria-hidden />}>\n Notifications\n </SettingsRow>\n);\n```\n\n## Visual options\n\nCompare switch sizes and checked, disabled, and read-only states.\n\n<StoryEmbed\n storyId=\"ui-components-settingsrow--catalog\"\n title=\"Settings row sizes and states\"\n height={520}\n/>\n\n## Configure the switch\n\nPass [Switch props](/ui/primitives/input/switch) directly to `SettingsRow`. Checked state, event details, disabled and read-only behavior, size, native form configuration, handlers, refs, and render composition configure the switch. `children` supplies the visible row label.\n\nUse `checked` and `onCheckedChange` when your application owns the value. The handler receives the next checked state and Base UI event details. Clicking the label or switch invokes it once. Call `eventDetails.cancel()` to reject a change, and keep your controlled value unchanged when the change is canceled.\n\n```tsx\nimport { useState } from 'react';\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { IconBell } from 'twenty-ui/icon';\n\nexport const NotificationSetting = () => {\n const [enabled, setEnabled] = useState(false);\n\n return (\n <SettingsRow\n startElement={<IconBell aria-hidden />}\n checked={enabled}\n onCheckedChange={setEnabled}\n >\n Notifications\n </SettingsRow>\n );\n};\n```\n\nUse `defaultChecked` for an uncontrolled setting. Keyboard users focus the switch and press Space. `disabled` disables the control and applies the row's disabled appearance. `readOnly` prevents changes while keeping the switch focusable.\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const WorkspaceSettings = () => (\n <>\n <SettingsRow disabled>Notifications</SettingsRow>\n <SettingsRow readOnly defaultChecked>\n Activity history\n </SettingsRow>\n </>\n);\n```\n\n## Row content and accessible text\n\n`children`, `startElement`, and `description` accept caller-owned nodes. The children supply the switch's accessible name, and the description supplies its accessible description. Keep content inside the label non-interactive. Use [ListItemButton](/ui/components/navigation/list-item-button) for action rows, or compose [ListItem](/ui/primitives/navigation/list-item) with a link for navigation.\n\n<StoryEmbed\n storyId=\"ui-components-settingsrow--with-description\"\n title=\"Settings row with a description\"\n height={110}\n/>\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const WeeklyDigestSetting = () => (\n <SettingsRow defaultChecked description=\"Sent every Monday\" name=\"digest\">\n Weekly digest\n </SettingsRow>\n);\n```\n\nSet `aria-label`, `aria-labelledby`, or `aria-describedby` to supply your own accessible text for the switch. An explicit `aria-label` replaces the generated name association; explicit `aria-labelledby` and `aria-describedby` values replace the corresponding generated associations.\n\n## Native targets and composition\n\nThe ordinary native props configure the control. Label customization has two explicit names:\n\n| Props | Target |\n| --------------------------------------------------------------------------------------- | --------------------------------------- |\n| Native attributes, handlers, `className`, `style`, `ref`, and `render` | The visible Switch root |\n| `inputRef`, `name`, `value`, `uncheckedValue`, `required`, and `form` | The Switch's underlying native checkbox |\n| `labelRef` and attributes, handlers, classes, and styles supplied through `labelRender` | The outer native label |\n\nThe label's `htmlFor` is managed internally and follows `id`, or a generated control ID when no ID is supplied. With the default Switch composition, this ID identifies the underlying checkbox. With `nativeButton`, it identifies the visible button. `ref` targets the visible root in both cases.\n\nUse `labelRender` to customize the row's native label. Preserve a label element and forward the render callback props to your element. Its `props.children` contains the complete row, including the switch. Element composition merges its classes and styles with the row's defaults.\n\n```tsx\nimport { useRef } from 'react';\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const ComposedNotificationSetting = () => {\n const labelRef = useRef<HTMLLabelElement>(null);\n const controlRef = useRef<HTMLElement>(null);\n const inputRef = useRef<HTMLInputElement>(null);\n\n return (\n <SettingsRow\n id=\"notification-control\"\n ref={controlRef}\n inputRef={inputRef}\n nativeButton\n render={<button />}\n labelRef={labelRef}\n labelRender={<label id=\"notification-row\" data-setting=\"notifications\" />}\n >\n Notifications\n </SettingsRow>\n );\n};\n```\n\n`onClick` receives control clicks. Native handlers supplied through `labelRender` receive label events and bubbled control events. Calling `preventDefault()` on a label click prevents its native control activation. Use `onCheckedChange` for preference updates, rather than inferring state from a label click.\n\nThe switch defaults to `size=\"sm\"`; use `\"md\"` for a larger switch. The row height stays the same. `focused` applies the row's highlighted appearance without moving keyboard focus. `className`, `style`, and `render` accept Switch state callbacks and customize the control. Supply label classes and styles through `labelRender` to customize the row.\n\n## Front component renderer\n\nInside a front component, use the native button composition for a switch nested in the row's label:\n\n```tsx\nimport { SettingsRow } from 'twenty-ui/components/settings';\n\nexport const FrontComponentNotificationSetting = () => (\n <SettingsRow nativeButton render={<button />}>\n Notifications\n </SettingsRow>\n);\n```\n\nThis composition activates once when clicking the label or control. The renderer's asynchronous event bridge cannot cancel the host label's default activation in time for a span-based control, which can produce duplicate change callbacks on a direct control click. Native form validation attributes such as `required` are also filtered by the current renderer. Standalone `SettingsRow` retains the full Switch form contract.\n\n## Forms and reset\n\n`name`, `value`, and `required` configure the underlying checkbox for form submission and validation. A checked switch submits its value. An unchecked switch omits the value unless `uncheckedValue` is supplied. Use `form` to associate the input with a form outside the row's parent tree.\n\nFor controlled form reset, restore the application-owned checked value in the form's `onReset` handler. Base UI 1.8 does not restore uncontrolled switch state on native form reset. `SettingsRow` preserves this upstream behavior.\n\n```tsx\nimport { useState } from 'react';\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const NotificationPreferences = () => {\n const [enabled, setEnabled] = useState(true);\n\n return (\n <form onReset={() => setEnabled(true)}>\n <SettingsRow\n checked={enabled}\n onCheckedChange={setEnabled}\n name=\"notifications\"\n value=\"enabled\"\n uncheckedValue=\"disabled\"\n >\n Notifications\n </SettingsRow>\n <Button type=\"reset\">Reset</Button>\n </form>\n );\n};\n```\n\n## Props\n\n<SettingsRowReference />\n\n<PageBanner illustration=\"settings\" />\n","api":{"name":"SettingsRow","entryPoint":"twenty-ui/components/settings","slug":"components/settings/settings-row","props":[{"name":"checked","type":"boolean","required":false,"defaultValue":null,"description":"Whether the switch is currently active.\n\nTo render an uncontrolled switch, use the `defaultChecked` prop instead."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Visible label and default accessible name of the switch. Use non-interactive node content."},{"name":"className","type":"string | ((state: SwitchRootState) => string | undefined)","required":false,"defaultValue":null,"description":"Customizes the visible Switch root and accepts a Switch state callback."},{"name":"defaultChecked","type":"boolean","required":false,"defaultValue":"false","description":"Whether the switch is initially active.\n\nTo render a controlled switch, use the `checked` prop instead."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Non-interactive supporting node content, used as the default accessible description of the switch."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component should ignore user interaction."},{"name":"focused","type":"boolean","required":false,"defaultValue":"false","description":"Applies the highlighted row style without moving keyboard focus."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Identifies the form that owns the hidden input.\nUseful when the switch is rendered outside the form."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Identifies the associated checkbox, or the visible root with nativeButton. The label association follows this ID."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Targets the underlying native checkbox."},{"name":"labelRef","type":"Ref<HTMLLabelElement>","required":false,"defaultValue":null,"description":"Targets the outer native label."},{"name":"labelRender","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the outer native label with its complete composed row children. Preserve a label element and forward its props to retain control association."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Identifies the field when a form is submitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"false","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `true` if the rendered element is a native button."},{"name":"onCheckedChange","type":"((checked: boolean, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Receives the next checked value and Base UI event details. Controlled callers own accepted state updates; cancellation prevents a change."},{"name":"onClick","type":"((event: BaseUIEvent<MouseEvent<HTMLSpanElement, MouseEvent>>) => void)","required":false,"defaultValue":null,"description":"Native click handler for the visible Switch root."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user should be unable to activate or deactivate the switch."},{"name":"ref","type":"Ref<HTMLSpanElement>","required":false,"defaultValue":null,"description":"Targets the visible Switch root, which defaults to a span."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>","required":false,"defaultValue":null,"description":"Customizes the visible Switch root with control props and Switch state. Use nativeButton when composing a button."},{"name":"required","type":"boolean","required":false,"defaultValue":"false","description":"Whether the user must activate the switch before submitting a form."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Visual size of the switch. Defaults to sm."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Non-interactive node content before the label."},{"name":"style","type":"CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Customizes the visible Switch root and accepts a Switch state callback."},{"name":"uncheckedValue","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is off.\nBy default, unchecked switches do not submit any value, matching native checkbox behavior."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"The value submitted with the form when the switch is on.\nBy default, switch submits the \"on\" value, matching native checkbox behavior."}]}},{"name":"PhoneCountryPicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: PhoneCountryPicker\ndescription: A complete phone country picker and composable parts sharing country data and selection.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport PhoneCountryPickerReference from '/snippets/ui/generated/components/input/phone-country-picker.mdx';\n\n## Overview\n\n`PhoneCountryPicker` combines a country flag trigger, popup, search and calling-code choices. Use the complete component for ordinary selection, or compose `Root`, `Trigger` and `Options` with [Dropdown](/ui/components/navigation/dropdown) when you need a custom popup. Both forms share the same prepared countries and selection.\n\n<StoryEmbed\n storyId=\"ui-input-phonecountrypicker--display\"\n title=\"Phone country selection\"\n height={260}\n/>\n\n## Usage\n\nSupply your own country data and a trigger accessible name. Use `value` with `onValueChange` for controlled selection, or `defaultValue` for uncontrolled selection. `null` represents no selected country.\n\n```tsx\nimport { useState } from 'react';\nimport {\n PhoneCountryPicker,\n type PhoneCountryOption,\n} from 'twenty-ui/components/input';\n\nconst COUNTRIES: PhoneCountryOption[] = [\n { value: 'FR', label: 'France', callingCode: '33', flag: '🇫🇷' },\n { value: 'GB', label: 'United Kingdom', callingCode: '44', flag: '🇬🇧' },\n { value: 'US', label: 'United States', callingCode: '1', flag: '🇺🇸' },\n];\n\nexport const PhoneCountryExample = () => {\n const [value, setValue] = useState<string | null>('FR');\n\n return (\n <PhoneCountryPicker\n aria-label=\"Phone country\"\n countries={COUNTRIES}\n value={value}\n onValueChange={setValue}\n contentProps={{ width: 280 }}\n optionsProps={{\n searchLabel: 'Search countries',\n listLabel: 'Phone countries',\n emptyLabel: 'No countries found',\n }}\n />\n );\n};\n```\n\nEach `PhoneCountryOption` has a unique stable `value`, a localized country `label`, a digits-only `callingCode` without the leading plus sign, and a decorative `flag` node. It may also be `disabled`. Values are caller-owned identifiers, such as ISO country codes, and are returned unchanged. Labels, flags and calling codes are presentation data and do not become the selected identifier.\n\nThe picker adds the plus sign and isolates calling codes left to right in option rows and overflow tooltips, including in right-to-left interfaces. Supply countries in the order you want them displayed. The selected country appears first while it matches the query; the remaining matches retain their supplied order.\n\n## Compound composition\n\nThis is a breaking API change for existing compound callers. Add `PhoneCountryPicker.Root` around `Dropdown.Root`, move `countries`, `value` and `onValueChange` from `Options` to `Root`, and remove `Trigger.country`. Both parts now require `Root` and derive the selected country from it.\n\n`Root` owns countries and the controlled or uncontrolled selection. Put the shared `Dropdown.Root` inside it and compose the trigger, content and options. `Trigger` derives its selected flag and accessible description from `Root`; `Options` reads the same data and selection. Do not supply another country or selected value to those parts.\n\n```tsx\nimport {\n PhoneCountryPicker,\n type PhoneCountryOption,\n} from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst COUNTRIES: PhoneCountryOption[] = [\n { value: 'FR', label: 'France', callingCode: '33', flag: '🇫🇷' },\n { value: 'GB', label: 'United Kingdom', callingCode: '44', flag: '🇬🇧' },\n];\n\n<PhoneCountryPicker.Root countries={COUNTRIES} defaultValue=\"FR\">\n <Dropdown.Root type=\"picker\">\n <PhoneCountryPicker.Trigger\n aria-label=\"Phone country\"\n render={<Button variant=\"outline\" />}\n />\n <Dropdown.Content width={320}>\n <PhoneCountryPicker.Options\n searchLabel=\"Search countries\"\n listLabel=\"Phone countries\"\n emptyLabel=\"No countries found\"\n />\n </Dropdown.Content>\n </Dropdown.Root>\n</PhoneCountryPicker.Root>;\n```\n\nKeep one root per selector. The shared Dropdown owns opening, popup placement, pages, focus and search navigation. Use `dropdownProps` and `contentProps` on the complete picker, or configure the Dropdown parts directly in compound usage.\n\n## Search and selection\n\nSearch matches substrings of the supplied country labels, stable identifiers and calling codes. Labels and identifiers use the shared `normalizeSearchText` normalization: lowercase text, Unicode NFD decomposition and script-aware accent handling. For example, `reunion` matches `Réunion` and `gb` matches a `GB` identifier. Meaningful distinctions in scripts are preserved according to that helper. Surrounding query whitespace is trimmed; internal whitespace is preserved. For calling-code search, one leading plus sign is optional, so `44`, `+44` and `\" +44 \"` match the supplied calling code `44`. Search does not parse a full phone number or infer a country from it.\n\n`onValueChange(value, eventDetails)` receives the requested identifier and the shared `Dropdown.SelectionGroup` details: `reason`, the native `event`, the selected option `trigger`, `cancel()` and `isCanceled`. Call `cancel()` before updating controlled state to reject the request. A canceled request preserves uncontrolled selection and leaves the popup open. Set `closeOnSelect={false}` to keep it open after an accepted selection. Selection changes do not modify any phone input value.\n\nSet `disabled` on the complete picker or `Root` to disable its trigger, search and selection. A disabled country stays visible and cannot be selected. `Trigger.disabled` and `Options.disabled` can additionally disable those individual parts.\n\n## Native targets and labels\n\nThe complete picker's native attributes, event handlers, `className`, `style`, `ref`, `render` and optional `children` target its trigger. `children` replaces the default flag or world icon and chevron. `contentProps` targets `Dropdown.Content`; `optionsProps` targets the options root div and supplies `searchLabel`, `listLabel` and `emptyLabel`. In compound usage, native props, refs and render composition target the corresponding `Trigger` button or `Options` div. `Root` renders no DOM node.\n\nSupply localized country labels and the required trigger `aria-label`. The selected country label describes the trigger, while its flag and chevron are decorative. An empty selection shows a world icon. The popup takes the trigger name unless a `Dropdown.Title` or an explicit content label names it. `searchLabel` defaults to `Search` and names both the search field and its placeholder. `listLabel` defaults to `Countries` and names the listbox independently. `emptyLabel` defaults to `No results`.\n\n## Phone input integration\n\nThe picker ships without a country catalog, flag asset package or phone-input runtime. The frontend adapter owns phone parsing, validation, formatting, editing drafts and persistence. Map the phone library's selected country to `Root.value` or the complete picker's `value`, and map country changes back through one callback. Keep the phone text in its existing owner when changing or clearing a country, or applying an external selected-country update.\n\nNative form submission, reset, required, read-only and Field integration for this custom picker are deferred. The complete picker forwards native trigger attributes according to the Dropdown button contract.\n\n## Front component renderer\n\nThe React and Preact gallery fixtures include the complete picker and compound composition. Portal placement, geometry, scrolling, dismissal and focus belong to the shared Dropdown and renderer integration. The picker does not introduce a separate renderer runtime.\n\n## Props\n\n<PhoneCountryPickerReference />\n\n<PageBanner illustration=\"card-page-tutorial-http\" />\n","api":{"name":"PhoneCountryPicker","entryPoint":"twenty-ui/components/input","slug":"components/input/phone-country-picker","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Required accessible name for the country selector trigger."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trigger content replacing the default country flag or world icon and chevron."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Closes the dropdown after an accepted selection. Defaults to true."},{"name":"contentProps","type":"Omit<DropdownContentProps, \"children\">","required":false,"defaultValue":null,"description":"Props for the internally assembled Dropdown.Content, including its accessible name, placement, width and popup ref."},{"name":"countries","type":"readonly PhoneCountryOption[]","required":true,"defaultValue":null,"description":"Prepared choices with a unique stable value, localized label, digits-only calling code without a plus sign, decorative flag node and optional disabled state. Matching choices retain their supplied order after the selected country."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":null,"description":"Initial uncontrolled country identifier. Omit it or use null to start empty."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables the trigger, search and country selection."},{"name":"dropdownProps","type":"Omit<DropdownRootProps, \"children\" | \"type\" | \"multiple\">","required":false,"defaultValue":null,"description":"Props for the internally assembled Dropdown.Root, including controlled open state and open-change events. The picker fixes its type to picker."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested country identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"optionsProps","type":"PhoneCountryPickerOptionsProps","required":false,"defaultValue":null,"description":"Props for the options root div, including native attributes, ref, render, searchLabel, listLabel and emptyLabel. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Composes the trigger with an element or render callback. Native attributes, handlers, className, style and ref target the trigger."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled country identifier. Use null to clear the selection. Labels and calling codes do not replace this value."}],"parts":[{"name":"Root","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"A Dropdown.Root with type=\"picker\", its Trigger, Content and Options. Root shares prepared data and selection and renders no DOM node."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":"true","description":"Closes the composed Dropdown after an accepted selection. Defaults to true."},{"name":"countries","type":"readonly PhoneCountryOption[]","required":true,"defaultValue":null,"description":"Prepared choices shared by Trigger and Options, with unique stable values, localized labels, digits-only calling codes without a plus sign, decorative flag nodes and optional disabled states."},{"name":"defaultValue","type":"string | null","required":false,"defaultValue":"null","description":"Initial uncontrolled country identifier. Omit it or use null to start empty."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables the composed trigger, search and country selection."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection."},{"name":"value","type":"string | null","required":false,"defaultValue":null,"description":"Controlled country identifier shared by the parts. Use null to clear the selection."}]},{"name":"Trigger","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Required accessible name for the country selector button."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trigger content replacing the selected country flag or empty world icon and chevron. The selected label comes from Root."},{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables the native trigger button in addition to Root.disabled."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the trigger button, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Composes the Dropdown trigger with an element or render callback. Native attributes, handlers, className, style and ref target this element."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Options","props":[{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables search and selection in addition to Root.disabled."},{"name":"emptyLabel","type":"string","required":false,"defaultValue":"No results","description":"Status message shown when no country label, identifier or calling code matches. Defaults to No results."},{"name":"listLabel","type":"string","required":false,"defaultValue":"Countries","description":"Accessible name of the country listbox, separate from the search field. Defaults to Countries."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the options root div, or the element composed through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Composes the non-interactive options root with an element or render callback. Native attributes, handlers, className, style and ref target this element. searchLabel names the internal search input."},{"name":"searchLabel","type":"string","required":false,"defaultValue":"Search","description":"Accessible name and placeholder of the country search field. Defaults to Search. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed."}]}]}},{"name":"Dropdown","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: Dropdown\ndescription: Action menus, searchable pickers, and form panels with shared presentation and interaction.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DropdownReference from '/snippets/ui/generated/components/navigation/dropdown.mdx';\n\n## Overview\n\n`Dropdown` combines a positioned popup, visual rows, keyboard navigation, focus, and dismissal. Your application owns data, filtering, fetching and pagination. `SelectionGroup` owns independent selection values inside the popup. Import it from `twenty-ui/components`.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--display\"\n title=\"Dropdown actions\"\n height={420}\n/>\n\nDropdown.Content accepts numeric offsets or functions for `sideOffset` and `alignOffset`. Offset functions receive the anchor and popup dimensions, side, and alignment. Use them to preserve an anchored field picker’s overlap when the cell is scaled.\n\n## Usage\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { IconArchive, IconCopy, IconDownload } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const RecordActions = () => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Record actions</Button>} />\n <Dropdown.Content aria-label=\"Record actions\" width={240}>\n <Dropdown.Section>\n <Dropdown.ActionItem startIcon={<IconCopy />}>\n Duplicate\n </Dropdown.ActionItem>\n <Dropdown.Submenu>\n <Dropdown.SubmenuTrigger startIcon={<IconDownload />}>\n Export\n </Dropdown.SubmenuTrigger>\n <Dropdown.Content aria-label=\"Export formats\">\n <Dropdown.Section>\n <Dropdown.ActionItem>CSV</Dropdown.ActionItem>\n <Dropdown.ActionItem>Excel</Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Submenu>\n </Dropdown.Section>\n <Dropdown.Separator />\n <Dropdown.Section>\n <Dropdown.ActionItem startIcon={<IconArchive />}>\n Archive\n </Dropdown.ActionItem>\n <Dropdown.ActionItem\n render={\n <a href=\"#dropdown-documentation\" aria-label=\"Documentation\" />\n }\n >\n Documentation\n </Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n## Choose an interaction type\n\nSet `type` on `Dropdown.Root` to match the popup's contents.\n\n| Type | Content | Interaction |\n| -------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |\n| `menu` | Commands and navigation links | Menu semantics with arrow navigation and typeahead. |\n| `picker` | Search, selectable values, and optional commands | A dialog containing search, selectable listboxes and optional commands. Arrow keys navigate result rows. |\n| `panel` | Inputs, forms, and supporting actions | A dialog with native input behavior and Tab navigation. |\n\nPickers allow creation actions and independent selection groups in the same page, in any order. Each picker group is a listbox, and its options expose `aria-selected`. Menu groups use checked radio or checkbox menu items. Panel groups use buttons with `aria-pressed`. Commands retain their mode’s action semantics. Give each group and `Search` an accessible name. This custom picker is not a native Combobox.\n\n`Content` takes its accessible name from `Trigger`, or from `SubmenuTrigger` in a submenu. Pass `aria-label` on `Content` when the trigger shows a value, such as the selected option, or when the root has no trigger. An explicit `aria-label` or `aria-labelledby`, and a `Title` inside a `Header`, take precedence over the trigger name.\n\n[Select](/ui/primitives/input/select) and [Popover](/ui/primitives/surfaces/popover) remain available for direct composition.\n\n## Anatomy\n\n```text\nDropdown.Root\n├── Dropdown.Trigger\n└── Dropdown.Content\n ├── Dropdown.Header\n │ ├── Dropdown.Close\n │ └── Dropdown.Title\n ├── Dropdown.Search\n └── Dropdown.Section\n ├── Dropdown.ActionItem\n └── Dropdown.SelectionGroup\n └── Dropdown.OptionItem\n```\n\n`Content` includes the portal and positioner. Use `width`, `side`, `align`, `sideOffset`, and `alignOffset` to control placement, and `collisionPadding` to keep the popup further from the edges of the viewport before it shifts or flips (5 pixels by default). `Section` groups rows with shared spacing, and `Separator` divides sections. A `scrollable` Section caps its height and scrolls; nest labelled sections inside it to scroll them as one list. Rows use [ListItem](/ui/primitives/navigation/list-item) for their appearance.\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const RecordActions = ({ onDuplicate }: { onDuplicate: () => void }) => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Record actions</Button>} />\n <Dropdown.Content>\n <Dropdown.Section>\n <Dropdown.ActionItem startIcon={<IconCopy />} onClick={onDuplicate}>\n Duplicate\n </Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\nPass custom trigger elements through `render` so the trigger remains one interactive element. Custom components must forward the supplied props and ref. `ActionItem` also accepts `render` for links.\n\n## Item actions\n\n`ActionItem` and `OptionItem` accept `actions` for trailing controls, such as a tab's edit button. Use them in `picker` and `panel` pages only: a `menu` may only contain menu items, so it cannot hold other controls. Set `actionsVisibility=\"always\"` to keep them visible; the default is `\"hover\"`. Secondary controls render beside the primary row control and activate independently: they do not close the popup, so close it from the action's handler when needed. The `render` prop and ref still apply to the primary control, so it can also serve as a drag handle.\n\nUse `tabIndex={-1}` for a pointer-only secondary action that has a separate keyboard alternative. Keyboard navigation continues to focus and activate the primary control.\n\n## Headers\n\n`Header` lays out a row at the top of the popup. Put a `Title` in it to name the popup after the title instead of the trigger. `Close` closes the popup the same way an outside press does. It renders an icon button with an X by default, so give it an `aria-label`, or pass `render` and children for another control. Other controls, such as a button that returns to a previous step, can sit in the same row. Use `Dropdown.Back` when navigating the root's page history.\n\n## Search and selection\n\n`Search` provides the input and navigation into the result rows. Pass `value` and `onValueChange`; compute or fetch matching results in your application. Render `Loading` while a request is pending and `Empty` when no results match. Both accept caller-provided status text.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--picker-documentation\"\n title=\"Searchable picker with inline creation\"\n height={420}\n/>\n\nWrap selectable options in `SelectionGroup` and give each option a stable `value` unique within the group. An uncontrolled group also needs an `id` unique within its dropdown tree, including submenus. Independently nested `Root` components keep their own selection store. Single selection uses a string or `null` for no selection. Multiple selection uses an array, including `[]` for no selection.\n\n```tsx\nimport { useState } from 'react';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const PersonPicker = () => {\n const [search, setSearch] = useState('');\n const [selectedPerson, setSelectedPerson] = useState<string | null>(null);\n const people = ['Ada Lovelace', 'Grace Hopper'].filter((person) =>\n person.toLowerCase().includes(search.toLowerCase()),\n );\n\n return (\n <Dropdown.Root type=\"picker\">\n <Dropdown.Trigger render={<Button>Choose person</Button>} />\n <Dropdown.Content>\n <Dropdown.Search\n aria-label=\"Search people\"\n value={search}\n onValueChange={setSearch}\n />\n <Dropdown.SelectionGroup\n id=\"person\"\n aria-label=\"Person\"\n value={selectedPerson}\n onValueChange={setSelectedPerson}\n >\n {people.map((person) => (\n <Dropdown.OptionItem key={person} value={person}>\n {person}\n </Dropdown.OptionItem>\n ))}\n </Dropdown.SelectionGroup>\n </Dropdown.Content>\n </Dropdown.Root>\n );\n};\n```\n\nPass `value` and `onValueChange` for controlled selection. Omitting `value`, or passing `undefined`, leaves selection uncontrolled; `defaultValue` sets its initial value. An uncontrolled group defaults to `null`, or `[]` with `multiple`. Its stable `id` preserves selection across close and reopen and across page navigation. Removing or filtering an option does not clear its selected identifier or emit a change; the option is selected again when it returns. Use a controlled value when the application needs to clear unavailable choices.\n\nEach group changes independently. An option commits to its nearest group, while the active page supplies one ordered collection for arrow navigation across groups and action rows. Repeated activation of a selected single option preserves its value without another change callback. Multiple activation toggles the option in the array.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--selection-groups-documentation\"\n title=\"Independent owner and watcher selections\"\n height={440}\n/>\n\nSingle selection closes by default; multiple selection stays open. `SelectionGroup.closeOnSelect` changes the group default, and `OptionItem.closeOnSelect` overrides it for one option. Action rows use `closeOnClick` independently. A cancelled change preserves the previous selection and does not automatically close the popup.\n\n`onValueChange` receives the next value and event details with `event`, `reason`, `trigger`, `cancel()` and `isCanceled`. The reason is `item-press`, and `event` is the original activation event. `OptionItem.onSelect` receives the same details before its owner commits. Call `cancel()` in either callback to prevent selection and automatic closing.\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\n<Dropdown.SelectionGroup\n id=\"watchers\"\n aria-label=\"Watchers\"\n multiple\n defaultValue={[]}\n onValueChange={(value, eventDetails) => {\n if (value.length > 3) {\n eventDetails.cancel();\n }\n }}\n>\n <Dropdown.OptionItem value=\"ada\">Ada Lovelace</Dropdown.OptionItem>\n <Dropdown.OptionItem value=\"grace\">Grace Hopper</Dropdown.OptionItem>\n</Dropdown.SelectionGroup>;\n```\n\nSearch receives focus when the picker opens. Without search, the first enabled selected option receives focus, or the first enabled row when no selected option is present. While `Search` has focus and a nonempty query, the first eligible `OptionItem` across selection groups is highlighted and Enter activates it. Action rows are never picked this way. ArrowDown moves focus to the first enabled row, including actions. Leaving search clears the preview and `aria-activedescendant`, even when the popup stays open. Returning to search restores the preview for the current query.\n\nEnter does nothing for an empty or whitespace-only query, or when no eligible option remains. Composing text with an input method does not activate an option or move focus with arrow keys. When rows are pinned above matches, such as the current value or a \"none\" row, render them only when they match the search text. The popup stays open when no option matches. Filtering remains caller-owned.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--multiple-selection-documentation\"\n title=\"Multiple selection\"\n height={420}\n/>\n\nStandalone `OptionItem` still accepts `selected` and `onSelect` for callers that own selection themselves. Grouped options derive selection from the group value; do not duplicate that state on the option. Custom selection groups do not provide native form submission, reset, required validation, read-only behavior or Field integration. Use [Select](/ui/primitives/input/select) when those native form contracts are needed.\n\n## Icon grids\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--icon-grid-documentation\"\n title=\"Icon grid with selected cell styling\"\n height={360}\n/>\n\nSet `columns` on `Section` to lay out items in equal-width grid columns. The same count drives keyboard navigation: Left and Right move within a row, while Up and Down move between rows. Navigation skips disabled options and follows the reading direction. When no enabled option is left in the column, Up and Down move to the nearest enabled option of the next row. Up from the first row returns to the search field when no earlier section exists. A short final row uses its last item when the requested column is missing. Inside a submenu, the backward arrow closes the submenu when no enabled option remains to its left.\n\nRender each icon as an `OptionItem` with an accessible label and an icon button through `render`. Use `indicator=\"none\"` to show selection through the button background. The `render` callback receives `{ selected, multiple, disabled }` state; use it to style a selected cell and forward the supplied props and ref.\n\n```tsx\nimport { LightIconButton } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { IconCalendar } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const IconGrid = () => (\n <Dropdown.Root type=\"picker\">\n <Dropdown.Trigger render={<Button>Choose icon</Button>} />\n <Dropdown.Content>\n <Dropdown.SelectionGroup\n id=\"icon\"\n aria-label=\"Icon\"\n defaultValue=\"calendar\"\n >\n <Dropdown.Section columns={5}>\n <Dropdown.OptionItem\n value=\"calendar\"\n aria-label=\"Calendar\"\n indicator=\"none\"\n nativeButton\n render={(props, state) => (\n <LightIconButton\n // oxlint-disable-next-line react/jsx-props-no-spreading\n {...props}\n size=\"md\"\n color={state.selected ? 'accent' : 'neutral'}\n aria-label=\"Calendar\"\n >\n <IconCalendar />\n </LightIconButton>\n )}\n />\n </Dropdown.Section>\n </Dropdown.SelectionGroup>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n## Keyboard focus\n\nIn `menu` and `picker` pages, the rows form a single Tab stop. Arrow keys move focus across sections, actions and options, and Home and End move to the first and last enabled rows unless the search field has focus. Moving focus never selects an option; Enter or Space activates the focused row. Tabbing back to the rows returns to the last focused row, or to the first enabled row once that row is gone. Search, `Back` beside a search, header buttons and other controls inside the popup keep their own Tab stops.\n\nTab and Shift+Tab close a `menu`, along with its parent menus when focus is in a submenu. In a `picker`, Tab moves through the popup's controls and closes the popup when focus leaves it. A `panel` keeps the native Tab order of its controls.\n\n## Pages and submenus\n\nUse `Page` for navigation that replaces the contents of the same popup. Wrap the first page in `Page id=\"root\"`, or choose another initial page with `defaultPage`. Set `page` on an action to navigate without closing. `Back` returns to the previous page and restores focus to its invoking row.\n\nPages mount when first visited and stay mounted for that open session. Returning to a page preserves its local search, form drafts and scrollable sections. Inactive pages are hidden and inert: they do not participate in keyboard navigation, focus or the accessibility tree, and their nested Dropdown popups are inactive.\n\nReopening starts a new session at `defaultPage` with fresh content, including when `Content.keepMounted` is set or the popup reopens during its exit transition. Page history, local search and drafts reset. The closing page remains mounted during its exit transition.\n\nUncontrolled `SelectionGroup` values stay stored in `Root` under each group's stable `id` and survive reopening. Caller-controlled values remain caller-owned. For example, a search value stored above `Content` stays unchanged until the caller updates it. Put temporary search or draft state in a component inside `Content` or `Page` when it should reset with the session; keep durable application state above `Content`.\n\nA page can override the root's `type`. For example, an action menu can open a searchable picker page or a form panel. Search receives focus when entering a searchable page; other pages focus their first row after `Back`.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--pages-documentation\"\n title=\"Menu to picker page navigation\"\n height={420}\n/>\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const FilterMenu = () => (\n <Dropdown.Root type=\"menu\">\n <Dropdown.Trigger render={<Button>Filters</Button>} />\n <Dropdown.Content>\n <Dropdown.Page id=\"root\">\n <Dropdown.Section>\n <Dropdown.ActionItem page=\"status\">Status</Dropdown.ActionItem>\n </Dropdown.Section>\n </Dropdown.Page>\n <Dropdown.Page id=\"status\" type=\"picker\">\n <Dropdown.Back>Filters</Dropdown.Back>\n <Dropdown.Section>\n <Dropdown.SelectionGroup id=\"status\" aria-label=\"Status\">\n <Dropdown.OptionItem value=\"active\">Active</Dropdown.OptionItem>\n <Dropdown.OptionItem value=\"archived\">Archived</Dropdown.OptionItem>\n </Dropdown.SelectionGroup>\n </Dropdown.Section>\n </Dropdown.Page>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\nTo navigate from code, call `useDropdownPage` in a component rendered inside the root. It returns the current `page`, `goToPage(page)`, `goBack()`, `canGoBack` and `isActive`. Inside a page, `isActive` is true only while that page is active and its dropdown is open. Use `isActive` to show a page's custom portaled popups so they disappear when the page becomes inactive or the dropdown closes. For example, an option can return to the previous page after a selection while the popup stays open:\n\n```tsx\nimport { Dropdown, useDropdownPage } from 'twenty-ui/components/navigation';\n\nexport const StatusOptions = ({\n status,\n onStatusChange,\n}: {\n status: string | null;\n onStatusChange: (status: string | null) => void;\n}) => {\n const { goBack } = useDropdownPage();\n\n return (\n <Dropdown.SelectionGroup\n id=\"status\"\n aria-label=\"Status\"\n value={status}\n closeOnSelect={false}\n onValueChange={(value) => {\n onStatusChange(value);\n goBack();\n }}\n >\n {['Active', 'Archived'].map((option) => (\n <Dropdown.OptionItem key={option} value={option}>\n {option}\n </Dropdown.OptionItem>\n ))}\n </Dropdown.SelectionGroup>\n );\n};\n```\n\nUse `Submenu` with `SubmenuTrigger` and a nested `Content` for a side-by-side menu. Arrow Right enters the submenu; Arrow Left returns to its parent. Selecting a closing action closes the whole dropdown.\n\n```text\nDropdown.Content\n└── Dropdown.Submenu\n ├── Dropdown.SubmenuTrigger\n └── Dropdown.Content\n └── Dropdown.ActionItem\n```\n\n## Independent nested pickers\n\nPlace another `Dropdown.Root` inside `Content` when a control opens its own picker, such as a sort direction selector. Selecting an inner option closes only that picker and restores focus to its trigger. Escape and outside presses dismiss one layer at a time. Use `Submenu` for commands that should close the entire menu tree when selected.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--nested-documentation\"\n title=\"Sort picker with a nested direction picker\"\n height={420}\n/>\n\n## Panels and controlled state\n\nUse `type=\"panel\"` for form inputs. Input interaction keeps the panel open; a save action can close it. Own `open` and `onOpenChange` when another component or a shortcut needs to open the dropdown. Keep that state with the feature that coordinates the interaction.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--panel-documentation\"\n title=\"Controlled form panel\"\n height={420}\n/>\n\nEscape dismisses the popup and restores focus to its trigger. Outside interaction also dismisses it, and the click that dismisses it doesn't activate what it lands on. Keys pressed inside the popup stay inside it, except Ctrl or Cmd shortcuts the dropdown doesn't handle, so page-level shortcuts keep working. `Content` accepts focus and portal options from Popover, including an explicit return-focus target for editor workflows.\n\n## Dismissal\n\nEscape, a press outside the popup and Tab out of it close the dropdown. Pass `onEscapeKeyDown` or `onInteractOutside` to `Root` to react before it closes, and call `event.preventDefault()` to keep it open. `event.target` is the element pressed outside, or `null` when focus leaves with Tab, and `event.type` is the type of the DOM event that triggered it, such as `touchmove` for a swipe outside the popup. A prevented outside press still reaches the element it lands on.\n\n```tsx\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const ViewSettings = ({ isEditing }: { isEditing: boolean }) => (\n <Dropdown.Root\n type=\"panel\"\n onInteractOutside={(event) => {\n if (isEditing) {\n event.preventDefault();\n }\n }}\n >\n <Dropdown.Trigger render={<Button>View settings</Button>} />\n <Dropdown.Content>\n <Dropdown.ActionItem>Save view</Dropdown.ActionItem>\n </Dropdown.Content>\n </Dropdown.Root>\n);\n```\n\n## Anchoring without a trigger\n\nA root can open without a `Trigger`, for example as a context menu. Control it with `open` and `onOpenChange`, and pass `anchor` to `Content`: an element, a ref, or a virtual element that returns a rectangle in viewport coordinates. Give `Content` an `aria-label`, since there is no trigger to name it after. On close, focus returns to the element that was focused when the popup opened.\n\n<StoryEmbed\n storyId=\"ui-components-dropdown--context-menu-documentation\"\n title=\"Context menu anchored to the pointer\"\n height={420}\n/>\n\n```tsx\nimport { useState } from 'react';\nimport { Dropdown } from 'twenty-ui/components/navigation';\n\nexport const RecordContextMenu = ({ recordName }: { recordName: string }) => {\n const [open, setOpen] = useState(false);\n const [point, setPoint] = useState({ x: 0, y: 0 });\n\n return (\n <>\n <p\n onContextMenu={(event) => {\n event.preventDefault();\n setPoint({ x: event.clientX, y: event.clientY });\n setOpen(true);\n }}\n >\n {recordName}\n </p>\n <Dropdown.Root type=\"menu\" open={open} onOpenChange={setOpen}>\n <Dropdown.Content\n aria-label=\"Record actions\"\n anchor={{\n getBoundingClientRect: () => new DOMRect(point.x, point.y, 0, 0),\n }}\n >\n <Dropdown.ActionItem>Duplicate</Dropdown.ActionItem>\n </Dropdown.Content>\n </Dropdown.Root>\n </>\n );\n};\n```\n\nRight-clicking elsewhere while the menu is open moves it to the new point.\n\nCall `useDropdownPlacementOrThrow` inside `Dropdown.Content` to read its resolved `side` and `align`, including collision flips. Use the resolved side to place a picker's search and create controls beside its trigger. Keep the controls in their visual DOM order so keyboard navigation follows the layout. A search below the results receives focus from `ArrowDown` on the last result; `ArrowUp` from that search returns to the last result.\n\n## Labels\n\nEach part owns its text: supply `Search.placeholder` and native accessible names, `Close` accessible attributes, and children for `Back`, `Loading`, and `Empty`. `Back` defaults to `Back`; loading and empty states have no built-in message. Item parts accept `shortcutJoinLabel` to replace the default `then` between sequential shortcut steps. Native `aria-labelledby` takes precedence over `aria-label`.\n\n## Props\n\n<DropdownReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"Dropdown","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/dropdown","props":[],"parts":[{"name":"Root","props":[{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is initially open when uncontrolled."},{"name":"defaultPage","type":"string","required":false,"defaultValue":null,"description":"ID of the `Page` shown when the popup opens. Closing the popup resets the page history to it. Defaults to `root`."},{"name":"multiple","type":"boolean","required":false,"defaultValue":null,"description":"Default for standalone options. Use `SelectionGroup.multiple` for independently owned selection values."},{"name":"onEscapeKeyDown","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called when Escape is about to close the popup. Call `event.preventDefault()` to keep it open."},{"name":"onInteractOutside","type":"((event: DropdownDismissEvent) => void)","required":false,"defaultValue":null,"description":"Called when a press outside the popup, or Tab out of it, is about to close it. `event.target` is the element pressed outside, or `null` after Tab, and `event.type` is the type of the DOM event that triggered it. Call `event.preventDefault()` to keep it open."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Called with the next open state when the popup opens or closes."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is open. Use with `onOpenChange` to control it."},{"name":"type","type":"\"menu\" | \"panel\" | \"picker\"","required":true,"defaultValue":null,"description":"Interaction model: `menu` for commands and links, `picker` for search and selectable options, or `panel` for forms. It sets the ARIA roles, initial focus, and keyboard navigation."}]},{"name":"Trigger","props":[{"name":"className","type":"string | ((state: PopoverTriggerState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"closeDelay","type":"number","required":false,"defaultValue":"0","description":"How long to wait before closing the popover that was opened on hover.\nSpecified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"delay","type":"number","required":false,"defaultValue":"300","description":"How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"ID of the trigger. In addition to being forwarded to the rendered element,\nit is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop)."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (e.g. `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"false","description":"Whether the popover should also open when the trigger is hovered."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Content","props":[{"name":"align","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":"start","description":"Alignment along the anchor. Defaults to start."},{"name":"alignOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Offset along the alignment axis. Accepts a number or positioning function."},{"name":"anchor","type":"Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null","required":false,"defaultValue":null,"description":"An element to position the popup against.\nBy default, the popup will be positioned against the trigger."},{"name":"className","type":"string | ((state: PopoverPopupState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"collisionPadding","type":"Padding","required":false,"defaultValue":"5","description":"Additional space to maintain from the edge of the collision boundary."},{"name":"container","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Portal destination, using the scoped theme when omitted. Explicit null waits for a target, matching Popover.Portal."},{"name":"finalFocus","type":"boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is closed.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (trigger or previously focused element).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"initialFocus","type":"boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)","required":false,"defaultValue":null,"description":"Determines the element to focus when the popover is opened.\nBy default, focus moves to the first tabbable element inside the popup, except when the popover\nis opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.\n\n- `false`: Do not move focus.\n- `true`: Move focus based on the default behavior (first tabbable element or popup).\n- `RefObject`: Move focus to the ref element.\n- `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).\n Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing."},{"name":"keepMounted","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the popup mounted while closed."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"side","type":"\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"","required":false,"defaultValue":"bottom","description":"Preferred side of the anchor. Defaults to bottom, or inline-end in a submenu."},{"name":"sideOffset","type":"number | OffsetFunction","required":false,"defaultValue":"0","description":"Distance from the anchor. Defaults to 0. Accepts a number or positioning function."},{"name":"style","type":"CSSProperties | ((state: PopoverPopupState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"width","type":"Width<string | number>","required":false,"defaultValue":"200","description":"CSS width of the popup. Numbers are in pixels."}]},{"name":"ActionItem","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Trailing controls rendered beside the primary row control. Only supported in picker and panel pages, since a menu may only contain menu items. Secondary actions activate independently of the row."},{"name":"actionsVisibility","type":"\"always\" | \"hover\"","required":false,"defaultValue":null,"description":"Whether trailing actions appear on hover or remain visible. Defaults to `hover`."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"closeOnClick","type":"boolean","required":false,"defaultValue":"true","description":"Closes the dropdown after activation, along with parent menus when inside a submenu. Ignored when `page` is set."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Shows a chevron indicating that the item opens a submenu."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"page","type":"string","required":false,"defaultValue":null,"description":"ID of the `Page` to show on activation. The popup stays open, and the row shows a chevron by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":false,"defaultValue":null,"description":"Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."}]},{"name":"OptionItem","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Trailing controls rendered beside the primary row control. Only supported in picker and panel pages, since a menu may only contain menu items. Secondary actions activate independently of the row."},{"name":"actionsVisibility","type":"\"always\" | \"hover\"","required":false,"defaultValue":null,"description":"Whether trailing actions appear on hover or remain visible. Defaults to `hover`."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Overrides the nearest group close policy for this option. A cancelled selection never closes automatically."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Shows a chevron indicating that the item opens a submenu."},{"name":"indicator","type":"\"check\" | \"checkbox\" | \"none\"","required":false,"defaultValue":null,"description":"Selection indicator: a check icon after the content, a checkbox before it, or none. Defaults to `checkbox` when `multiple` is set, otherwise `check`, and to `none` when `selected` is omitted."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"onSelect","type":"((eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called before the nearest group commits selection, with `event`, `reason`, `trigger`, `cancel` and `isCanceled`. Calling `cancel()` prevents the value change and automatic close."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DropdownOptionItemState>","required":false,"defaultValue":null,"description":"Element or function rendered as the row. Functions receive the supplied props and `{ selected, multiple, disabled }` state. Forward the props and ref to the rendered control."},{"name":"selected","type":"boolean","required":false,"defaultValue":null,"description":"Selected state for standalone options. Options inside a `SelectionGroup` derive it from their owner. Grouped picker options expose `aria-selected`, menu options expose `aria-checked`, and panel options expose `aria-pressed`."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"Stable option identifier within its nearest `SelectionGroup`. The group supplies selected state and commits this value on activation."}]},{"name":"SelectionGroup","props":[{"name":"closeOnSelect","type":"boolean","required":false,"defaultValue":null,"description":"Default close policy for owned options: true for single selection, false for multiple selection. Individual options can override it."},{"name":"defaultValue","type":"string | string[] | null","required":false,"defaultValue":null,"description":"Initial uncontrolled selection. Defaults to null for single selection and an empty array for multiple selection."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Stable identifier unique within the dropdown root. Required for uncontrolled groups, whose values persist under it across popup close and page navigation. Optional for controlled groups."},{"name":"multiple","type":"boolean","required":false,"defaultValue":null,"description":"Uses an array of selected identifiers when true. Otherwise the value is one identifier or null."},{"name":"onValueChange","type":"((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void) | ((value: string[], eventDetails: DropdownSelectionGroupChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Called with the next value and cancellable event details: `event`, `reason`, `trigger`, `cancel` and `isCanceled`. Calling `cancel()` preserves the value and keeps the popup open. Repeated single selection does not emit another change."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DropdownSelectionGroupState>","required":false,"defaultValue":null,"description":"Element or function rendered as the group. Functions receive supplied props and `{ value, multiple }` state. Forward the props and ref."},{"name":"value","type":"string | string[] | null","required":false,"defaultValue":null,"description":"Controlled selection: a string or null for single selection, or an array for multiple selection. Undefined leaves selection uncontrolled."}]},{"name":"Search","props":[{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"false","description":"Shows the search input focus outline. Defaults to false for all dropdown searches. Set true to opt in. Error styling remains visible."},{"name":"onValueChange","type":"((value: string) => void)","required":false,"defaultValue":null,"description":"Called with the search text on every change. The application filters the results."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, InputState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: InputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"textAlign","type":"\"end\" | \"start\"","required":false,"defaultValue":null,"description":"Aligns text to the logical start or end of the input. Follows the text direction."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The value of the input. Use when controlled."}]},{"name":"Header","props":[{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Title","props":[{"name":"className","type":"string | ((state: PopoverTitleState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverTitleState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Close","props":[{"name":"aria-label","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the close control. Required because the default control only shows an icon."},{"name":"className","type":"string | ((state: PopoverCloseState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverCloseState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"style","type":"CSSProperties | ((state: PopoverCloseState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]},{"name":"Page","props":[{"name":"id","type":"string","required":true,"defaultValue":null,"description":"Identifier matched by `defaultPage`, the `page` prop of actions, and `goToPage`. The page renders only while it is current."},{"name":"type","type":"\"menu\" | \"panel\" | \"picker\"","required":false,"defaultValue":null,"description":"Interaction model while the page is shown. Defaults to the root `type`."}]},{"name":"Back","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Shows a chevron indicating that the item opens a submenu."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":false,"defaultValue":null,"description":"Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."}]},{"name":"Submenu","props":[{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is initially open when uncontrolled."},{"name":"defaultPage","type":"string","required":false,"defaultValue":null,"description":"ID of the `Page` shown when the popup opens. Closing the popup resets the page history to it. Defaults to `root`."},{"name":"multiple","type":"boolean","required":false,"defaultValue":null,"description":"Default for standalone options. Use `SelectionGroup.multiple` for independently owned selection values."},{"name":"onOpenChange","type":"((open: boolean) => void)","required":false,"defaultValue":null,"description":"Called with the next open state when the popup opens or closes."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Whether the popup is open. Use with `onOpenChange` to control it."},{"name":"type","type":"\"menu\" | \"panel\" | \"picker\"","required":false,"defaultValue":"menu","description":"Interaction model: `menu` for commands and links, `picker` for search and selectable options, or `panel` for forms. It sets the ARIA roles, initial focus, and keyboard navigation."}]},{"name":"SubmenuTrigger","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the row."},{"name":"closeDelay","type":"number","required":false,"defaultValue":null,"description":"Delay in milliseconds before a submenu opened on hover closes. Requires `openOnHover`. Defaults to `0`."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"delay","type":"number","required":false,"defaultValue":null,"description":"Delay in milliseconds before the submenu opens on hover. Requires `openOnHover`. Defaults to `300`."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":"true","description":"Shows a chevron indicating that the item opens a submenu."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true when render is omitted; false otherwise","description":"Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."},{"name":"openOnHover","type":"boolean","required":false,"defaultValue":"true","description":"Also opens the submenu when the row is hovered."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>>","required":false,"defaultValue":null,"description":"Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Keyboard shortcut keys displayed at the end of the row. Registering the\nshortcut is up to the application."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the row."}]},{"name":"Section","props":[{"name":"columns","type":"number","required":false,"defaultValue":null,"description":"Number of grid columns. Sets the grid layout and enables horizontal arrow navigation and vertical movement by row."},{"name":"label","type":"ReactNode","required":false,"defaultValue":null,"description":"Heading displayed above the rows. It also names the group for assistive technologies."},{"name":"scrollable","type":"boolean","required":false,"defaultValue":null,"description":"Caps the section height and scrolls its rows. Nest labelled sections inside it to scroll them as one list."}]},{"name":"Separator","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the separator. Native div attributes and refs are also accepted."}]},{"name":"Loading","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Loading message announced as a polite, busy status."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the status. Native div attributes and refs are also accepted."}]},{"name":"Empty","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Empty-state message announced as a polite status."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the status. Native div attributes and refs are also accepted."}]}]}},{"name":"OverflowingList","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: OverflowingList\ndescription: Fit a row of items into the available space and show the complete list in a popup.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport OverflowingListReference from '/snippets/ui/generated/components/layout/overflowing-list.mdx';\n\n## Overview\n\n`OverflowingList` measures its available width, keeps fitting items in a compact row, and offers a `+N` button that opens the complete list in a popup. The count updates when the container, item content or ordered list changes. Empty lists and lists that fit have no overflow button or exposed popup.\n\n<StoryEmbed\n storyId=\"ui-components-overflowinglist--display\"\n title=\"Overflowing list example\"\n height={280}\n/>\n\nSupply the complete ordered list as keyed elements. Your application owns each item's content, actions and data. The compact row remains visible when the popup opens. The popup repeats the complete list, including the items that fit in the row.\n\n## Usage\n\n```tsx\nimport { OverflowingList, Section } from 'twenty-ui/components/layout';\nimport { Tag } from 'twenty-ui/primitives/data-display';\n\nconst TAGS = ['Customer', 'Partner', 'Priority', 'Renewal'];\n\nexport const CompanyTags = () => (\n <Section.Root>\n <Section.Header\n title=\"Company tags\"\n description=\"Open the count to see all tags.\"\n />\n <OverflowingList\n style={{ width: 180 }}\n showOverflowCount\n overflowLabel=\"Show all company tags\"\n >\n {TAGS.map((label) => (\n <Tag\n key={label}\n color=\"blue\"\n truncate={false}\n style={{ width: 80, minWidth: 'fit-content' }}\n >\n {label}\n </Tag>\n ))}\n </OverflowingList>\n </Section.Root>\n);\n```\n\n## Count visibility\n\n| `showOverflowCount` | Behavior when items overflow |\n| ------------------- | ---------------------------------------------------------------------------- |\n| Omitted | Shows the count on pointer hover, keyboard focus or while the popup is open. |\n| `true` | Keeps the count visible. |\n| `false` | Hides the count and clips the row. An open popup stays open until dismissed. |\n\nThe default mode keeps the current count visibility while an inline item is focused, so showing the count does not push that item out of the row. Focusing the count button makes the count visible.\n\nUse `false` when the surrounding interface provides another way to access the hidden items. Changing it to `false` hides the count without dismissing an already-open popup. `open` and `defaultOpen` can still expose the complete list when items overflow. Removing the overflow items or widening the list until everything fits closes the popup and removes the count button. The count always describes the items outside the compact row.\n\n`maxInlineCount` caps the number of visible row items. Available width can reduce that number further. The popup still contains the complete list. It does not fetch missing items or virtualize the popup.\n\n## Popup state\n\nThe list owns its popup state when `open` is omitted. Use `defaultOpen` for its initial state. The default is `false`; an initially open popup still requires overflowing items.\n\nPass `open` and update it in `onOpenChange` to own the popup state. The callback receives the requested boolean and the installed [Popover](/ui/primitives/surfaces/popover) event details, including `reason`, `event`, `trigger`, `cancel()` and `preventUnmountOnClose()`. Calling `cancel()` prevents the requested state change. In controlled use, update your state only for changes you accept.\n\nPass `actionsRef` to receive the Popover `close()` and `unmount()` methods. `close()` requests closure through `onOpenChange` and respects cancellation. If your callback calls `preventUnmountOnClose()` to run a caller-owned exit, call `actionsRef.current?.unmount()` when that exit finishes. This releases the retained popup without removing the list and allows it to open again.\n\n```tsx\nimport { useState } from 'react';\nimport { OverflowingList } from 'twenty-ui/components/layout';\nimport { Tag } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst TEAMS = ['Design', 'Engineering', 'Support', 'Operations'];\n\nexport const ControlledTeamList = () => {\n const [open, setOpen] = useState(false);\n\n return (\n <OverflowingList\n open={open}\n onOpenChange={setOpen}\n showOverflowCount\n overflowLabel=\"Show all teams\"\n style={{ width: 220 }}\n triggerProps={{ render: <Button variant=\"outline\" size=\"sm\" /> }}\n >\n {TEAMS.map((team) => (\n <Tag key={team} color=\"blue\">\n {team}\n </Tag>\n ))}\n </OverflowingList>\n );\n};\n```\n\n<StoryEmbed\n storyId=\"ui-components-overflowinglist--controlled\"\n title=\"Controlled state with a custom trigger\"\n height={280}\n/>\n\n## Native targets and composition\n\nNative `div` attributes, handlers, styles, class names and refs on `OverflowingList` target the compact row root. Use `triggerProps` for the count button and `popupProps` for the popup content div. Both retain their Popover part's native props, handlers, ref and element/function `render` composition.\n\nCustomize the trigger with `triggerProps.render`, as in the controlled example, or supply `triggerProps.children` to replace `+N`. Custom components must [forward the supplied props and ref](/ui/primitives/overview#custom-components). Custom popup components must also render the supplied children; OverflowingList owns the item content. `overflowLabel` defaults to \"Show all items\". The default button's accessible name combines its count and that label, for example \"+3 Show all teams\". Override `triggerProps['aria-label']` or `popupProps['aria-label']` when their content needs a different name.\n\n`OverflowingList` stops `click`, `mousedown`, `pointerdown`, `keydown` and `keyup` propagation on the trigger and popup by default. This keeps opening the popup and interacting with its items from activating a surrounding field or picker. A handler supplied through `triggerProps` or `popupProps` replaces the default for that event. Call `event.stopPropagation()` in your handler to retain blocking, or omit it to allow that event to bubble. Other events keep their defaults. Handlers on a custom `render` element compose with the supplied props as usual.\n\nWhen a popup click override allows bubbling, the installed Base UI portal can dispatch that click to a surrounding React ancestor twice with the same native event. This also occurs with a plain `Popover`. OverflowingList preserves that upstream behavior; it does not guarantee one ancestor callback per native popup event when bubbling is enabled.\n\n## Keyboard and focus\n\nEnter, Space and pointer activation open a non-modal popup. Escape and outside interaction dismiss it. Ordinary dismissal restores focus to the count button. Focus already on a visible inline item or an outside control is preserved. The popup supports content, links and buttons with their native keyboard behavior; it does not turn them into menu items or add menu arrow navigation.\n\nUse `popupProps.initialFocus` and `popupProps.finalFocus` to customize opening and dismissal focus through the installed Popover contract.\n\nEach list owns its responsive measurements independently. Unmounting one list releases its observers and leaves other lists working.\n\n## Server rendering and hydration\n\nServer markup includes the first `maxInlineCount` items, or all items when the cap is omitted. Width measurement and popup content become available after client mounting.\n\nHydration reuses the provisional row and applies responsive measurement after client mounting. Row and popup children are separate rendered instances. Keep state shared between those locations in the caller.\n\n## Migration\n\nThe popup continues to show the complete list and uses \"Show all items\" by default. `showOverflowCount={false}` preserves the clipped row and hides the count. It does not dismiss an already-open popup. The trigger and popup retain their default blocking for click, mousedown, pointerdown, keydown and keyup. Override an individual handler through `triggerProps` or `popupProps` when the surrounding interface should receive that event.\n\n## Props\n\n<OverflowingListReference />\n\n<PageBanner illustration=\"section-apps-data\" />\n","api":{"name":"OverflowingList","entryPoint":"twenty-ui/components/layout","slug":"components/layout/overflowing-list","props":[{"name":"actionsRef","type":"RefObject<PopoverRootActions | null>","required":false,"defaultValue":null,"description":"Ref exposing the Popover close() and unmount() methods. After preventUnmountOnClose(), call unmount() when the caller-owned exit finishes."},{"name":"children","type":"ReactElement<unknown, string | JSXElementConstructor<any>>[]","required":true,"defaultValue":null,"description":"Complete ordered list of elements, each with a stable key. The popup contains the complete list, including items visible in the compact row."},{"name":"defaultOpen","type":"boolean","required":false,"defaultValue":"false","description":"Initial popup visibility when uncontrolled. Defaults to false."},{"name":"maxInlineCount","type":"number","required":false,"defaultValue":null,"description":"Maximum number of items visible in the compact row. Available width can reduce this count further. The popup still contains the complete list."},{"name":"onOpenChange","type":"((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)","required":false,"defaultValue":null,"description":"Receives the requested open state and unchanged Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose()."},{"name":"open","type":"boolean","required":false,"defaultValue":null,"description":"Controlled popup visibility. A popup can appear only when items overflow."},{"name":"overflowLabel","type":"string","required":false,"defaultValue":"Show all items","description":"Accessible label for the popup. The default overflow button is named by its visible count followed by this label. Defaults to Show all items."},{"name":"popupProps","type":"Omit<PopoverPopupProps, \"children\">","required":false,"defaultValue":null,"description":"Popover.Popup native props, handlers, ref, render composition and focus options for the overflow content. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the compact row root div."},{"name":"showOverflowCount","type":"boolean","required":false,"defaultValue":null,"description":"Shows the count on hover, keyboard focus or while open by default. Use true to keep it visible whenever items overflow, or false to hide the count and clip the row. An already-open popup stays open until dismissed. Empty lists and lists that fit have no trigger."},{"name":"triggerProps","type":"Omit<\n ComponentPropsWithRef<typeof Popover.Trigger>,\n 'handle' | 'payload' | 'ref'\n > & { ref?: Ref<HTMLElement> }","required":false,"defaultValue":null,"description":"Popover.Trigger native props, handlers, ref, children and render composition for the count button. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default. Custom components must forward supplied props and ref."}]}},{"name":"LabeledSeparator","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: LabeledSeparator\ndescription: Separate content with a centered or end-aligned text label.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport LabeledSeparatorReference from '/snippets/ui/generated/components/layout/labeled-separator.mdx';\n\n## Overview\n\n`LabeledSeparator` composes [Separator](/ui/primitives/layout/separator) and [Text](/ui/primitives/typography/text) into a named horizontal divider. Your application supplies the label and surrounding spacing.\n\n<StoryEmbed\n storyId=\"ui-layout-labeledseparator--display\"\n title=\"Labeled separator between import options\"\n height={180}\n/>\n\n## Usage\n\n```tsx\nimport { LabeledSeparator } from 'twenty-ui/components/layout';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const ImportOptions = () => (\n <Text\n style={{\n display: 'grid',\n gap: 'var(--t-spacing-3)',\n width: 320,\n maxWidth: '100%',\n }}\n >\n <Button fullWidth>Import a CSV file</Button>\n <LabeledSeparator>Or</LabeledSeparator>\n <Button fullWidth variant=\"outline\">\n Connect a data source\n </Button>\n </Text>\n);\n```\n\n## Label placement and tone\n\n`labelPosition` defaults to `center`, with a line on each side of the label. Use `end` to place the label after the leading line. The label accepts a string supplied and localized by your application.\n\n`tone` defaults to `neutral`. Use `danger` for a red marker with a medium-weight label and a thicker rule. Set `hasStartMarker` to add a small decorative cap at the beginning of the rule.\n\nThe optional cap follows the [shared calendar and chat line design](https://www.figma.com/design/xt8O9mFeLl46C5InWwoMrN/Twenty?node-id=118289-146574).\n\n<StoryEmbed\n storyId=\"ui-layout-labeledseparator--unread-marker\"\n title=\"Unread marker with an end-aligned label\"\n height={100}\n/>\n\n```tsx\nimport { LabeledSeparator } from 'twenty-ui/components/layout';\n\nexport const UnreadMarker = () => (\n <LabeledSeparator\n labelPosition=\"end\"\n tone=\"danger\"\n hasStartMarker\n style={{ width: 488, maxWidth: '100%' }}\n >\n New\n </LabeledSeparator>\n);\n```\n\n## Spacing and application state\n\nThe component fills its container and adds no outer margin. Use parent layout spacing or native `style` and `className` for margins and alignment. Keep offsets for adjacent avatars or calendar positions in your application.\n\nThe component presents the supplied label. Your application decides where an unread boundary or calendar marker belongs and when it is visible.\n\n## Accessibility and composition\n\nThe root exposes one horizontal separator named from its label. The rule segments and optional start marker are decorative, so assistive technology does not announce extra separators. Native accessible attributes can provide a different name or description when needed.\n\nNative attributes, styles, class names, and `ref` target the outer `div`. Use `render` to compose another noninteractive element while forwarding the supplied props and ref. `LabeledSeparatorProps` is exported from `twenty-ui/components/layout`.\n\n## Migration\n\nReplace the frontend `LabeledDivider` with `LabeledSeparator`. Rename `textPosition` to `labelPosition`, and use `tone=\"danger\"` for the unread marker's red appearance. Remove `noMargin`, since outer margins default to zero. Preserve the former default spacing with `style={{ marginBlock: 'var(--t-spacing-3)' }}` where needed.\n\n## Props\n\n<LabeledSeparatorReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"LabeledSeparator","entryPoint":"twenty-ui/components/layout","slug":"components/layout/labeled-separator","props":[{"name":"children","type":"string","required":true,"defaultValue":null,"description":"Text naming the separator. Supplied and localized by the caller."},{"name":"hasStartMarker","type":"boolean","required":false,"defaultValue":"false","description":"Show a decorative cap at the beginning of the rule."},{"name":"labelPosition","type":"\"center\" | \"end\"","required":false,"defaultValue":"center","description":"Place the label between two lines or at the end of one line."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"tone","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":"neutral","description":"Neutral divider or red marker with a thicker rule."}]}},{"name":"Section","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: Section\ndescription: Group content with a heading, supporting description, and optional action.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SectionReference from '/snippets/ui/generated/components/layout/section.mdx';\n\n## Overview\n\n`Section.Root` groups related content. `Section.Header` combines [Heading](/ui/primitives/typography/heading) with a description and optional `actions` content. Descriptions are ordinary text associated with the heading, so they do not add levels to the document outline.\n\n<StoryEmbed\n storyId=\"ui-components-section--display\"\n title=\"Section example\"\n height={150}\n/>\n\n## Usage\n\n```tsx\nimport { Section } from 'twenty-ui/components/layout';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceSection = () => (\n <Section.Root>\n <Section.Header\n title=\"Workspace settings\"\n description=\"Manage your workspace name and preferences.\"\n />\n <Text>Workspace preferences appear here.</Text>\n </Section.Root>\n);\n```\n\n## Add a description and action\n\n```tsx\nimport { Section } from 'twenty-ui/components/layout';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const WorkspaceSection = () => (\n <Section.Root>\n <Section.Header\n title=\"Workspace settings\"\n description=\"Manage your workspace name and preferences.\"\n actions={<Button>Edit workspace</Button>}\n />\n <Text>Workspace preferences appear here.</Text>\n </Section.Root>\n);\n```\n\n`Section.Root` defaults to a full-width `div` with left alignment and the primary text color. Use `align`, `color`, and `fullWidth` to adjust the content wrapper.\n\n`Section.Header` can also be used by itself. Its `level`, `size`, and `color` configure the heading and default to `2`, `md`, and `primary`. The header has one spacing-4 margin after it. Use native `style` or `className` to adjust that spacing.\n\n## Description overflow\n\nString descriptions show up to five lines. Set `descriptionLineClamp` to a positive integer to choose another limit, or `false` to display the full description without an overflow tooltip. Hover reveals overflowing text. Descriptions do not add a tab stop by default; set `isDescriptionFocusable` to enable focus access to the tooltip. Escape dismisses the tooltip.\n\nThe heading accepts node content. Choose `level` for the document outline independently of visual `size` and `color`. Compose links and other rich content explicitly in a node description.\n\nPass a React node for richer supporting content. Rich descriptions render as supplied, without automatic truncation or tooltips.\n\n## Composition\n\nBoth parts forward native attributes, refs, class names, styles, and `render` to their outer element. For example, `Section.Root render={<section aria-label=\"Workspace settings\" />}` provides a named section, and `Section.Header render={<header />}` uses a header container.\n\nWhen migrating, replace `adornment` with `actions`. Opt into description focus with `isDescriptionFocusable` when needed. `SectionRootProps` and `SectionHeaderProps` are exported from `twenty-ui/components/layout`.\n\n## Props\n\n<SectionReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"Section","entryPoint":"twenty-ui/components/layout","slug":"components/layout/section","props":[],"parts":[{"name":"Root","props":[{"name":"align","type":"\"center\" | \"left\"","required":false,"defaultValue":"left","description":"Text alignment within the section. Defaults to `left`."},{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Text color within the section. Defaults to `primary`."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"true","description":"Whether the section fills the available width. Defaults to `true`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]},{"name":"Header","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Content alongside the heading, such as an action button or status."},{"name":"color","type":"\"primary\" | \"secondary\" | \"tertiary\"","required":false,"defaultValue":"primary","description":"Theme font color. Defaults to `primary`."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text associated with the heading. Strings have optional truncation and overflow tooltips; React nodes render as supplied."},{"name":"descriptionLineClamp","type":"number | false","required":false,"defaultValue":"5","description":"Maximum visible lines for a string description. Defaults to `5`; use `false` to display the full description without a tooltip."},{"name":"isDescriptionFocusable","type":"boolean","required":false,"defaultValue":"false","description":"Adds a tab stop to a truncated string description so its overflow tooltip can open on focus. Defaults to `false`."},{"name":"level","type":"1 | 2 | 3 | 4 | 5 | 6","required":false,"defaultValue":"2","description":"Semantic heading level, from `h1` through `h6`. Does not change the visual size. Defaults to `2`."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\"","required":false,"defaultValue":"md","description":"Visual font size from `xs` through `xxl`, independent of the heading level. Uses the matching font token. Defaults to `md`."},{"name":"title","type":"ReactNode","required":true,"defaultValue":null,"description":"Content of the section heading."}]}]}},{"name":"CodeEditor","entryPoint":"twenty-ui/components/code-editor","content":"---\ntitle: CodeEditor\ndescription: Edit and display code in a Monaco editor styled with the Twenty theme.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CodeEditorReference from '/snippets/ui/generated/components/code-editor/code-editor.mdx';\nimport CodeEditorHeaderReference from '/snippets/ui/generated/components/code-editor/code-editor-header.mdx';\n\n## Overview\n\n`CodeEditor` renders a [Monaco](https://microsoft.github.io/monaco-editor/) editor that follows the Twenty theme in light and dark mode. `CodeEditorHeader` adds a bar above it for a title, tabs, or actions. Both come from `twenty-ui/components/code-editor`, a separate entry point, so the rest of Twenty UI works without Monaco.\n\n<StoryEmbed\n storyId=\"ui-components-codeeditor--display\"\n title=\"Code editor example\"\n height={280}\n/>\n\n## Usage\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\n\nexport const WorkspaceEditor = () => (\n <>\n <CodeEditorHeader title=\"workspace.json\" />\n <CodeEditor\n variant=\"with-header\"\n language=\"json\"\n defaultValue={JSON.stringify(\n { name: 'Acme', plan: 'Pro', seats: 12 },\n null,\n 2,\n )}\n height={160}\n />\n </>\n);\n```\n\n## Setup\n\nInstall the editor's optional peer dependencies:\n\n```bash\nyarn add @monaco-editor/react monaco-editor\n```\n\nThe editor loads your installed `monaco-editor` package rather than a copy from a CDN. Monaco runs language features such as validation and autocompletion in web workers, and creating those workers depends on your bundler. Before an editor mounts, define `MonacoEnvironment.getWorker` as described in [Monaco's ESM integration guide](https://github.com/microsoft/monaco-editor/blob/main/docs/integrate-esm.md). Without it, the editor still renders, but language features are unavailable.\n\nThe code editor does not run inside [front components](/developers/extend/apps/layout/front-components) yet.\n\n## Controlled content\n\n```tsx\nimport { useState } from 'react';\nimport { isDefined } from 'twenty-ui/utilities';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const PayloadEditor = () => {\n const [payload, setPayload] = useState('{\\n \"name\": \"Acme\"\\n}');\n\n return (\n <CodeEditor\n language=\"json\"\n value={payload}\n onChange={(value) => {\n if (isDefined(value)) {\n setPayload(value);\n }\n }}\n height={200}\n />\n );\n};\n```\n\n`CodeEditorProps` includes the installed Monaco React editor contract. `onChange(value, event)` receives the content (`string | undefined`) and the original `IModelContentChangedEvent`, including changed ranges, version and undo/redo details. Guard an undefined value at the boundary where your application requires a string.\n\n`beforeMount(monaco)` runs after the Twenty theme is defined and before editor creation. `onMount(editor, monaco)` receives the editor instance after the selected theme is applied. `onValidate(markers)` receives Monaco diagnostics unchanged. `overrideServices` passes through to editor creation.\n\nA Twenty `Loader` shows until Monaco loads. Pass `loading` to customize that content, or set `isLoading` to keep it visible while your own data loads. `isLoading` unmounts an existing editor and follows Monaco React's model disposal rules.\n\n## Models and values\n\nUse `defaultValue`, `defaultLanguage` and `defaultPath` to initialize an uncontrolled model, or `value`, `language` and `path` for updates. These props retain Monaco React's behavior, including its rules for choosing initial values and reusing an existing model URI. Changing `defaultValue` does not overwrite a model that already exists.\n\nChanging `path` selects or creates a model. `saveViewState` defaults to true and restores the model's cursor and scroll state when switching back. `line` reveals a line when the editor mounts or the prop changes. `keepCurrentModel` defaults to false; when true, the caller owns disposal of the retained model.\n\n```tsx\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const FileEditor = () => (\n <CodeEditor\n defaultPath=\"file:///workspace/settings.json\"\n defaultLanguage=\"json\"\n defaultValue={'{\\n \"name\": \"Acme\"\\n}'}\n saveViewState\n />\n);\n```\n\n## Native integration\n\n`ref` points to the outer Twenty group div, which uses `display: contents` by default. This keeps the Monaco section in the parent's sizing and flex layout. The outer div has no measurable layout box.\n\nUse `containerProps` for the outer div's native attributes, event handlers, class and style. Background, border, padding and dimensions require overriding its `display`. Prefer Monaco React's `wrapperProps` section for layout styles and a measurable native ref. `className` targets the editor-container div inside that section; use `onMount` for the Monaco editor instance.\n\nThe Monaco React section contains its own loading content until the editor is ready. During initial bundled Monaco configuration or `isLoading`, Twenty renders a separate loader without `wrapperProps` or `className`. The outer `containerProps` and `ref` remain available in these states.\n\n```tsx\nimport { useRef } from 'react';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const NamedEditor = () => {\n const containerRef = useRef<HTMLDivElement>(null);\n\n return (\n <CodeEditor\n ref={containerRef}\n containerProps={{ id: 'payload-editor' }}\n wrapperProps={{ 'data-editor-surface': 'payload' }}\n options={{ ariaLabel: 'Payload code' }}\n />\n );\n};\n```\n\n## Add a header\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype ScriptEditorProps = {\n script: string;\n onRun: () => void;\n};\n\nexport const ScriptEditor = ({ script, onRun }: ScriptEditorProps) => (\n <div>\n <CodeEditorHeader\n title=\"index.ts\"\n endElement={\n <Button size=\"sm\" onClick={onRun}>\n Run\n </Button>\n }\n />\n <CodeEditor language=\"typescript\" value={script} variant=\"with-header\" />\n </div>\n);\n```\n\n`variant=\"with-header\"` removes the editor's top border so it joins the header. Use `borderless` when the editor sits inside a surface that already has a border.\n\nThe header accepts node content in `title`, `startElement`, and `endElement`. Use fragments for multiple tabs or actions. Native props, `className`, `style`, and `ref` target its root div. Use `render` to replace that root, for example `render={<header />}`. The `title` prop supplies visible content; to set a native title attribute, pass it on the element supplied to `render`.\n\n## Size and appearance\n\nThe editor is 450px tall and 100% wide by default. `width` and `height` accept pixels or a CSS length.\n\nSizing follows this order:\n\n1. `resizable` starts from the rendered height, including CSS lengths, within the resize handle's 50px to 500px bounds. It adds a handle after Monaco mounts. Dragging or keyboard input then sets a pixel height. Changing `height` resets it within the same bounds.\n2. Otherwise, `autoHeight` uses Monaco's content height. The explicit or default height is used until content is measured.\n3. Otherwise, the explicit or default `height` applies.\n\nMonaco React enables `automaticLayout` by default. If you disable it in `options`, your application must call `editor.layout()` when the container changes size. Native `wrapperProps.style` is passed unchanged and can override the section's width or height.\n\nPass a localized `resizeLabel` to name the resize handle for screen readers.\n\nTwenty supplies font, formatting, scrollbar, minimap and padding defaults. `contentPadding=\"comfortable\"` also widens the gap between line numbers and code. Caller `options` replace the corresponding defaults, including the whole `padding` object and `lineDecorationsWidth`.\n\nAn explicit `theme` takes precedence over `options.theme`; otherwise the editor follows Twenty's light or dark theme. Define custom Monaco themes in `beforeMount`. Monaco themes are global, so changing one affects other Monaco editors on the same page. `transparentBackground` controls the Twenty wrapper appearance independently.\n\n## Validation\n\nMonaco reports its own diagnostics, such as JSON syntax errors, through `onValidate`. To add your own, return marker data from `setMarkers`. It runs on mount, model selection and every model content change, including controlled value updates, and replaces the custom markers for the current model.\n\n## Keyboard\n\nWhile the editor has focus, it stops keyboard events from propagating. React key handlers on parent components and document-level shortcuts do not receive keystrokes typed in the editor.\n\n## Props\n\n### CodeEditor\n\n<CodeEditorReference />\n\n### CodeEditorHeader\n\n<CodeEditorHeaderReference />\n\n<PageBanner illustration=\"dev-api\" />\n","api":{"name":"CodeEditor","entryPoint":"twenty-ui/components/code-editor","slug":"components/code-editor/code-editor","props":[{"name":"autoHeight","type":"boolean","required":false,"defaultValue":"false","description":"Grows the editor to fit its content instead of using `height`. Ignored when `resizable` is set."},{"name":"beforeMount","type":"BeforeMount","required":false,"defaultValue":null,"description":"Called with Monaco before editor creation, after the Twenty theme has been defined. Use it to register custom themes or languages."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the Monaco editor-container div."},{"name":"containerProps","type":"Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"ref\">, \"children\">","required":false,"defaultValue":null,"description":"Native props, className and style for the outer Twenty group div. Its default `display: contents` preserves the Monaco section's parent sizing and flex layout without creating a layout box. Background, border, padding and dimensions require overriding `display`. Prefer `wrapperProps` for section layout styles. Its keyboard handler runs before focused editor keystrokes stop propagating."},{"name":"contentPadding","type":"\"comfortable\" | \"default\"","required":false,"defaultValue":"default","description":"`default` supplies top and bottom padding. `comfortable` also widens the gap between line numbers and code. Explicit Monaco options override these defaults."},{"name":"defaultLanguage","type":"string","required":false,"defaultValue":null,"description":"Initial Monaco language for a newly created model."},{"name":"defaultPath","type":"string","required":false,"defaultValue":null,"description":"Initial model URI, used when `path` is omitted."},{"name":"defaultValue","type":"string","required":false,"defaultValue":null,"description":"Initial content for a model created by Monaco React."},{"name":"height","type":"string | number","required":false,"defaultValue":"450","description":"Editor height in pixels or as a CSS length, defaulting to 450px. Resizing starts from this rendered height and resets when this prop changes. Auto-height uses it until content is measured."},{"name":"isLoading","type":"boolean","required":false,"defaultValue":"false","description":"Shows a loader at the editor height instead of the editor. A loader also shows while Monaco loads."},{"name":"keepCurrentModel","type":"boolean","required":false,"defaultValue":"false","description":"Keeps the current model when the editor unmounts. Defaults to false. The caller owns disposal of retained models."},{"name":"language","type":"string","required":false,"defaultValue":null,"description":"Monaco language identifier for highlighting and language services, such as `json` or `typescript`."},{"name":"line","type":"number","required":false,"defaultValue":null,"description":"Line revealed when the editor mounts or this prop changes."},{"name":"loading","type":"ReactNode","required":false,"defaultValue":"<Loader />","description":"Content shown while Monaco loads or `isLoading` is true. Defaults to the Twenty Loader."},{"name":"onChange","type":"OnChange","required":false,"defaultValue":null,"description":"Monaco React callback with the full content (string or undefined) and the original IModelContentChangedEvent."},{"name":"onMount","type":"OnMount","required":false,"defaultValue":null,"description":"Called when the editor is ready, with the editor instance and the Monaco namespace. The selected theme is already applied."},{"name":"onValidate","type":"OnValidate","required":false,"defaultValue":null,"description":"Called with the markers Monaco reports after validating the content, such as JSON syntax errors."},{"name":"options","type":"IStandaloneEditorConstructionOptions","required":false,"defaultValue":null,"description":"Monaco editor options merged over Twenty defaults. Explicit values, including padding, replace the corresponding defaults. The `theme` prop takes precedence over `options.theme`."},{"name":"overrideServices","type":"IEditorOverrideServices","required":false,"defaultValue":null,"description":"Monaco services passed through when the editor is created."},{"name":"path","type":"string","required":false,"defaultValue":null,"description":"URI of the current model. Changing it selects or creates a model using Monaco React behavior."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the outer Twenty group div, which has no measurable layout box with its default `display: contents`. Use `wrapperProps` for a measurable section ref or `onMount` for the Monaco editor instance."},{"name":"resizable","type":"boolean","required":false,"defaultValue":"false","description":"Adds a height resize handle after Monaco mounts, bounded from 50px to 500px. Takes precedence over autoHeight. A changed height prop resets the resized height within these bounds."},{"name":"resizeLabel","type":"string","required":false,"defaultValue":"Resize editor","description":"Accessible name of the resize handle. Pass a localized label when `resizable` is enabled."},{"name":"saveViewState","type":"boolean","required":false,"defaultValue":"true","description":"Preserves Monaco React view state between model changes. Defaults to true."},{"name":"setMarkers","type":"((value: string) => IMarkerData[])","required":false,"defaultValue":null,"description":"Returns custom validation markers for the current model content. Runs on mount, model selection and content changes, including controlled updates."},{"name":"theme","type":"string","required":false,"defaultValue":"Twenty theme","description":"Monaco theme name. Takes precedence over `options.theme`, which takes precedence over the Twenty theme. Define custom themes in `beforeMount`."},{"name":"transparentBackground","type":"boolean","required":false,"defaultValue":null,"description":"Removes the editor background so the surrounding surface shows through."},{"name":"value","type":"string","required":false,"defaultValue":null,"description":"Content of the editor. Pair it with `onChange` to control the editor."},{"name":"variant","type":"\"borderless\" | \"default\" | \"with-header\"","required":false,"defaultValue":"default","description":"Border treatment: `default` draws a rounded border, `with-header` attaches the editor below a `CodeEditorHeader`, and `borderless` removes the border."},{"name":"width","type":"string | number","required":false,"defaultValue":"100%","description":"Width of the Monaco React section, in pixels or as a CSS length."},{"name":"wrapperProps","type":"object","required":false,"defaultValue":null,"description":"Native props passed unchanged to the Monaco React section around the editor and Monaco React loading content. Use this section for layout styles and a measurable native ref. Not applied to the separate Twenty loader during initial Monaco configuration or `isLoading`. Native styles can override the section sizing."}]}},{"name":"CodeEditorHeader","entryPoint":"twenty-ui/components/code-editor","content":"---\ntitle: CodeEditor\ndescription: Edit and display code in a Monaco editor styled with the Twenty theme.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CodeEditorReference from '/snippets/ui/generated/components/code-editor/code-editor.mdx';\nimport CodeEditorHeaderReference from '/snippets/ui/generated/components/code-editor/code-editor-header.mdx';\n\n## Overview\n\n`CodeEditor` renders a [Monaco](https://microsoft.github.io/monaco-editor/) editor that follows the Twenty theme in light and dark mode. `CodeEditorHeader` adds a bar above it for a title, tabs, or actions. Both come from `twenty-ui/components/code-editor`, a separate entry point, so the rest of Twenty UI works without Monaco.\n\n<StoryEmbed\n storyId=\"ui-components-codeeditor--display\"\n title=\"Code editor example\"\n height={280}\n/>\n\n## Usage\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\n\nexport const WorkspaceEditor = () => (\n <>\n <CodeEditorHeader title=\"workspace.json\" />\n <CodeEditor\n variant=\"with-header\"\n language=\"json\"\n defaultValue={JSON.stringify(\n { name: 'Acme', plan: 'Pro', seats: 12 },\n null,\n 2,\n )}\n height={160}\n />\n </>\n);\n```\n\n## Setup\n\nInstall the editor's optional peer dependencies:\n\n```bash\nyarn add @monaco-editor/react monaco-editor\n```\n\nThe editor loads your installed `monaco-editor` package rather than a copy from a CDN. Monaco runs language features such as validation and autocompletion in web workers, and creating those workers depends on your bundler. Before an editor mounts, define `MonacoEnvironment.getWorker` as described in [Monaco's ESM integration guide](https://github.com/microsoft/monaco-editor/blob/main/docs/integrate-esm.md). Without it, the editor still renders, but language features are unavailable.\n\nThe code editor does not run inside [front components](/developers/extend/apps/layout/front-components) yet.\n\n## Controlled content\n\n```tsx\nimport { useState } from 'react';\nimport { isDefined } from 'twenty-ui/utilities';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const PayloadEditor = () => {\n const [payload, setPayload] = useState('{\\n \"name\": \"Acme\"\\n}');\n\n return (\n <CodeEditor\n language=\"json\"\n value={payload}\n onChange={(value) => {\n if (isDefined(value)) {\n setPayload(value);\n }\n }}\n height={200}\n />\n );\n};\n```\n\n`CodeEditorProps` includes the installed Monaco React editor contract. `onChange(value, event)` receives the content (`string | undefined`) and the original `IModelContentChangedEvent`, including changed ranges, version and undo/redo details. Guard an undefined value at the boundary where your application requires a string.\n\n`beforeMount(monaco)` runs after the Twenty theme is defined and before editor creation. `onMount(editor, monaco)` receives the editor instance after the selected theme is applied. `onValidate(markers)` receives Monaco diagnostics unchanged. `overrideServices` passes through to editor creation.\n\nA Twenty `Loader` shows until Monaco loads. Pass `loading` to customize that content, or set `isLoading` to keep it visible while your own data loads. `isLoading` unmounts an existing editor and follows Monaco React's model disposal rules.\n\n## Models and values\n\nUse `defaultValue`, `defaultLanguage` and `defaultPath` to initialize an uncontrolled model, or `value`, `language` and `path` for updates. These props retain Monaco React's behavior, including its rules for choosing initial values and reusing an existing model URI. Changing `defaultValue` does not overwrite a model that already exists.\n\nChanging `path` selects or creates a model. `saveViewState` defaults to true and restores the model's cursor and scroll state when switching back. `line` reveals a line when the editor mounts or the prop changes. `keepCurrentModel` defaults to false; when true, the caller owns disposal of the retained model.\n\n```tsx\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const FileEditor = () => (\n <CodeEditor\n defaultPath=\"file:///workspace/settings.json\"\n defaultLanguage=\"json\"\n defaultValue={'{\\n \"name\": \"Acme\"\\n}'}\n saveViewState\n />\n);\n```\n\n## Native integration\n\n`ref` points to the outer Twenty group div, which uses `display: contents` by default. This keeps the Monaco section in the parent's sizing and flex layout. The outer div has no measurable layout box.\n\nUse `containerProps` for the outer div's native attributes, event handlers, class and style. Background, border, padding and dimensions require overriding its `display`. Prefer Monaco React's `wrapperProps` section for layout styles and a measurable native ref. `className` targets the editor-container div inside that section; use `onMount` for the Monaco editor instance.\n\nThe Monaco React section contains its own loading content until the editor is ready. During initial bundled Monaco configuration or `isLoading`, Twenty renders a separate loader without `wrapperProps` or `className`. The outer `containerProps` and `ref` remain available in these states.\n\n```tsx\nimport { useRef } from 'react';\nimport { CodeEditor } from 'twenty-ui/components/code-editor';\n\nexport const NamedEditor = () => {\n const containerRef = useRef<HTMLDivElement>(null);\n\n return (\n <CodeEditor\n ref={containerRef}\n containerProps={{ id: 'payload-editor' }}\n wrapperProps={{ 'data-editor-surface': 'payload' }}\n options={{ ariaLabel: 'Payload code' }}\n />\n );\n};\n```\n\n## Add a header\n\n```tsx\nimport { CodeEditor, CodeEditorHeader } from 'twenty-ui/components/code-editor';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype ScriptEditorProps = {\n script: string;\n onRun: () => void;\n};\n\nexport const ScriptEditor = ({ script, onRun }: ScriptEditorProps) => (\n <div>\n <CodeEditorHeader\n title=\"index.ts\"\n endElement={\n <Button size=\"sm\" onClick={onRun}>\n Run\n </Button>\n }\n />\n <CodeEditor language=\"typescript\" value={script} variant=\"with-header\" />\n </div>\n);\n```\n\n`variant=\"with-header\"` removes the editor's top border so it joins the header. Use `borderless` when the editor sits inside a surface that already has a border.\n\nThe header accepts node content in `title`, `startElement`, and `endElement`. Use fragments for multiple tabs or actions. Native props, `className`, `style`, and `ref` target its root div. Use `render` to replace that root, for example `render={<header />}`. The `title` prop supplies visible content; to set a native title attribute, pass it on the element supplied to `render`.\n\n## Size and appearance\n\nThe editor is 450px tall and 100% wide by default. `width` and `height` accept pixels or a CSS length.\n\nSizing follows this order:\n\n1. `resizable` starts from the rendered height, including CSS lengths, within the resize handle's 50px to 500px bounds. It adds a handle after Monaco mounts. Dragging or keyboard input then sets a pixel height. Changing `height` resets it within the same bounds.\n2. Otherwise, `autoHeight` uses Monaco's content height. The explicit or default height is used until content is measured.\n3. Otherwise, the explicit or default `height` applies.\n\nMonaco React enables `automaticLayout` by default. If you disable it in `options`, your application must call `editor.layout()` when the container changes size. Native `wrapperProps.style` is passed unchanged and can override the section's width or height.\n\nPass a localized `resizeLabel` to name the resize handle for screen readers.\n\nTwenty supplies font, formatting, scrollbar, minimap and padding defaults. `contentPadding=\"comfortable\"` also widens the gap between line numbers and code. Caller `options` replace the corresponding defaults, including the whole `padding` object and `lineDecorationsWidth`.\n\nAn explicit `theme` takes precedence over `options.theme`; otherwise the editor follows Twenty's light or dark theme. Define custom Monaco themes in `beforeMount`. Monaco themes are global, so changing one affects other Monaco editors on the same page. `transparentBackground` controls the Twenty wrapper appearance independently.\n\n## Validation\n\nMonaco reports its own diagnostics, such as JSON syntax errors, through `onValidate`. To add your own, return marker data from `setMarkers`. It runs on mount, model selection and every model content change, including controlled value updates, and replaces the custom markers for the current model.\n\n## Keyboard\n\nWhile the editor has focus, it stops keyboard events from propagating. React key handlers on parent components and document-level shortcuts do not receive keystrokes typed in the editor.\n\n## Props\n\n### CodeEditor\n\n<CodeEditorReference />\n\n### CodeEditorHeader\n\n<CodeEditorHeaderReference />\n\n<PageBanner illustration=\"dev-api\" />\n","api":{"name":"CodeEditorHeader","entryPoint":"twenty-ui/components/code-editor","slug":"components/code-editor/code-editor-header","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional CSS class applied to the root element."},{"name":"endElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content shown at the end of the header, such as actions. Use a fragment for multiple elements."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the rendered root element, a div by default."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replace the root div or compose it with another component. Native props and refs target the rendered root."},{"name":"startElement","type":"ReactNode","required":false,"defaultValue":null,"description":"Content shown at the start of the header, before the title, such as tabs. Use a fragment for multiple elements."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root element."},{"name":"title","type":"ReactNode","required":false,"defaultValue":null,"description":"Content shown after `startElement`. This is visible header content, not the native HTML title attribute."}]}},{"name":"ListItemButton","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: ListItemButton\ndescription: Native action buttons with the shared list row appearance.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ListItemButtonReference from '/snippets/ui/generated/components/navigation/list-item-button.mdx';\n\n## Overview\n\nUse `ListItemButton` for action rows and standalone selection buttons. It combines [ListItem](/ui/primitives/navigation/list-item) layout with a native button, including Enter and Space activation, focus, and disabled behavior. It defaults to `type=\"button\"`.\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--display\"\n title=\"ListItemButton example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\n\nexport const DuplicateAction = ({\n onDuplicate,\n}: {\n onDuplicate: () => void;\n}) => (\n <ListItemButton\n startIcon={<IconCopy />}\n description=\"Create a copy\"\n onClick={onDuplicate}\n >\n Duplicate\n </ListItemButton>\n);\n```\n\n## Actions and disabled state\n\nPass `onClick` and `disabled` directly. Disabled buttons use the matching row appearance, prevent activation, and leave the tab order.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { IconCopy } from 'twenty-ui/icon';\n\ntype DuplicateActionProps = {\n onDuplicate: () => void;\n disabled?: boolean;\n};\n\nexport const DuplicateAction = ({\n onDuplicate,\n disabled = false,\n}: DuplicateActionProps) => (\n <ListItemButton\n disabled={disabled}\n onClick={onDuplicate}\n startIcon={<IconCopy />}\n description=\"Create a copy\"\n >\n Duplicate\n </ListItemButton>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--disabled\"\n title=\"Disabled action row\"\n height={110}\n/>\n\nSet `focusableWhenDisabled` to keep a disabled button focusable. It uses `aria-disabled` and continues to block activation. Native button attributes, events, styles, class names, and an `HTMLButtonElement` ref reach the button. Events bubble normally; callers supply any `stopPropagation()` or `preventDefault()` policy.\n\n## Selection and visual slots\n\nYour application owns the independent `active`, `selected`, and `focused` states. Use `active` for the open or current row. Pair `selected` with the appropriate accessible state, such as `aria-pressed` for a toggle button. `focused` highlights the row without moving DOM focus. Indicators and shortcut hints are decorative; your application registers shortcuts and handles navigation.\n\n```tsx\nimport { useState } from 'react';\nimport { ListItemButton } from 'twenty-ui/components/navigation';\n\nexport const ShowArchivedToggle = () => {\n const [selected, setSelected] = useState(false);\n\n return (\n <ListItemButton\n aria-pressed={selected}\n selected={selected}\n indicator=\"check\"\n onClick={() => setSelected(!selected)}\n >\n Show archived records\n </ListItemButton>\n );\n};\n```\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--selected\"\n title=\"Selected action row\"\n height={110}\n/>\n\nUse `startIcon`, `endIcon`, `description`, and `descriptionPlacement` for supporting content. `color=\"danger\"` marks a destructive action. `shortcutJoinLabel` controls the text between sequential shortcuts, and `hasSubmenu` displays a submenu indicator.\n\n## Multiline supporting content\n\nSet `descriptionPlacement=\"below\"` to wrap supporting text beneath the label. The label retains its truncation behavior. Pass [Text](/ui/primitives/typography/text) with `truncate` or `lineClamp` as `description` when you need a shorter preview. The `inline` and `end` placements keep their existing appearance.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\ntype PlanningActionProps = {\n active?: boolean;\n disabled?: boolean;\n onOpen: () => void;\n};\n\nexport const PlanningAction = ({\n active = false,\n disabled = false,\n onOpen,\n}: PlanningActionProps) => (\n <ListItemButton\n active={active}\n disabled={disabled}\n descriptionPlacement=\"below\"\n description=\"Review the proposed timeline and confirm the next steps with the team.\"\n startIcon={<Avatar name=\"Alex Morgan\" size=\"md\" imageProps={{ alt: '' }} />}\n onClick={onOpen}\n >\n Quarterly planning\n </ListItemButton>\n);\n```\n\n`active` applies the current-row background. Set `selectionAppearance=\"accent\"` for an accent fill on selected rows with any description placement; the default preserves the existing indicator-based selection styling. `focused` applies the shared highlighted background; the focus-visible outline follows actual keyboard focus. These props do not add accessible state or move focus. Native button activation and disabled behavior remain unchanged.\n\n## Independent controls\n\nKeep independent buttons and checkboxes beside `ListItemButton` so each retains its own focus and activation. Do not nest them in its content or icon slots. The component has no `actions` slot. Use a `ListItem` with its default `div` root for [a row with independent controls](/ui/primitives/navigation/list-item#independent-controls), and supply disabled behavior and event propagation on each control.\n\n```tsx\nimport { ListItemButton } from 'twenty-ui/components/navigation';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype ContactActionsProps = {\n onOpen: () => void;\n onDetails: () => void;\n};\n\nexport const ContactActions = ({ onOpen, onDetails }: ContactActionsProps) => (\n <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>\n <ListItemButton onClick={onOpen} description=\"Account owner\">\n Alex Morgan\n </ListItemButton>\n <Button onClick={onDetails} aria-label=\"Open Alex Morgan's details\">\n Details\n </Button>\n </div>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-components-listitembutton--independent-action\"\n title=\"Sibling action controls\"\n height={110}\n/>\n\nUse `ListItem` for passive content, links, or custom semantic owners. Use the existing [Dropdown](/ui/components/navigation/dropdown), and [Select](/ui/primitives/input/select) item parts within their popup owners, which supply roles and keyboard navigation.\n\n## Props\n\n<ListItemButtonReference />\n\n<PageBanner illustration=\"page-cover-pointer\" />\n","api":{"name":"ListItemButton","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/list-item-button","props":[{"name":"active","type":"boolean","required":false,"defaultValue":null,"description":"Marks the open or current item independently of selection and focus. The caller supplies accessible state."},{"name":"color","type":"\"danger\" | \"neutral\"","required":false,"defaultValue":null,"description":"Color of the text and icons. `danger` marks a destructive action."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Supporting text, placed according to `descriptionPlacement`."},{"name":"descriptionPlacement","type":"\"below\" | \"end\" | \"inline\"","required":false,"defaultValue":null,"description":"Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables activation and applies the matching row appearance."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered after the content."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Keeps a disabled button focusable with aria-disabled while preventing activation."},{"name":"focused","type":"boolean","required":false,"defaultValue":null,"description":"Highlights the row without moving DOM focus."},{"name":"hasSubmenu","type":"boolean","required":false,"defaultValue":null,"description":"Displays a decorative submenu indicator."},{"name":"indicator","type":"\"check\" | \"checkbox\" | \"none\"","required":false,"defaultValue":null,"description":"Selection indicator: a check icon after the content or a checkbox before\nit."},{"name":"ref","type":"Ref<HTMLButtonElement>","required":false,"defaultValue":null,"description":"Ref to the native HTMLButtonElement."},{"name":"selected","type":"boolean","required":false,"defaultValue":null,"description":"Applies selected styling and a decorative indicator. The caller supplies selection state and accessible semantics."},{"name":"selectionAppearance","type":"\"accent\" | \"default\"","required":false,"defaultValue":null,"description":"Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Displays decorative shortcut hints. The caller registers the shortcuts."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Text between sequential shortcut steps. Defaults to `then`; pass an empty string to omit it."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Icon rendered before the content."}]}},{"name":"CountPager","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: CountPager\ndescription: Navigate a finite collection with previous and next controls and formatted position text.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CountPagerReference from '/snippets/ui/generated/components/navigation/count-pager.mdx';\n\n## Overview\n\n`CountPager` combines previous and next buttons with caller-formatted position text. Use it to move through a small collection such as review items or requests.\n\n<StoryEmbed\n storyId=\"ui-components-countpager--display\"\n title=\"Count pager example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { CountPager } from 'twenty-ui/components/navigation';\n\nexport const ReviewPager = () => {\n const [index, setIndex] = useState(0);\n\n return (\n <CountPager\n aria-label=\"Review item\"\n index={index}\n count={3}\n onIndexChange={setIndex}\n positionText={`${index + 1} of 3`}\n previousLabel=\"Previous item\"\n nextLabel=\"Next item\"\n />\n );\n};\n```\n\n## Controlled navigation\n\nSupply a zero-based `index`, the collection's `count`, and `onIndexChange`. Activating an available button requests the neighboring index. Your application updates the index and renders the corresponding content.\n\nPrevious is disabled on the first item, and Next is disabled on the last item. Both buttons are disabled for an empty or single-item collection, when `disabled` is set, or when the supplied index or count is invalid. Counts must be nonnegative integers, and the index must be an integer within the collection bounds.\n\nChanging props never calls `onIndexChange`. When items disappear or the collection changes, your application chooses the next active item. Data loading, stable item identities, draft preservation, and executing the displayed item remain with the application.\n\n## Position text and placement\n\n`positionText` is required and stays under application control. Format numbers, units, and translations before passing it to the pager. For an empty collection, supply a meaningful value such as `No items`; the component does not invent an empty-state label.\n\nThe default `positionPlacement=\"between\"` shows Previous, position text, and Next. Set `positionPlacement=\"start\"` to place the text before both buttons. The text then fills the available width so the actions align at the end of the row.\n\n```tsx\nimport { useState } from 'react';\nimport { CountPager } from 'twenty-ui/components/navigation';\n\nexport const RequestPager = () => {\n const [index, setIndex] = useState(0);\n\n return (\n <CountPager\n aria-label=\"Pending requests\"\n index={index}\n count={3}\n onIndexChange={setIndex}\n positionText={`Request ${index + 1} of 3`}\n previousLabel=\"Previous request\"\n nextLabel=\"Next request\"\n positionPlacement=\"start\"\n style={{ width: 280, maxWidth: '100%' }}\n />\n );\n};\n```\n\n## Accessibility and composition\n\nThe root defaults to a group. Supply a contextual accessible name with `aria-label` or `aria-labelledby`, plus `previousLabel` and `nextLabel` for the two icon buttons. Position text uses a polite live region so changes can be announced without moving focus.\n\nThe controls use native buttons with the shared [LightIconButton](/ui/components/input/light-icon-button) presentation. Tab moves between enabled controls, and Enter or Space activates the focused button. Disabled controls cannot navigate. Pager clicks do not submit a surrounding form.\n\nNative attributes, `className`, `style`, and `ref` target the root. Use `render` to compose a different root element while preserving the supplied props and ref. Keep the buttons and their interaction semantics intact.\n\n## Props\n\n<CountPagerReference />\n\n<PageBanner illustration=\"dashboards\" />\n","api":{"name":"CountPager","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/count-pager","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the root element."},{"name":"count","type":"number","required":true,"defaultValue":null,"description":"Number of items in the collection. Empty collections and invalid or noninteger counts disable navigation."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables both navigation buttons without changing the position text."},{"name":"index","type":"number","required":true,"defaultValue":null,"description":"Controlled zero-based item index. Navigation is disabled when the index is not an integer within the collection bounds."},{"name":"nextLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the Next button."},{"name":"onIndexChange","type":"(index: number) => void","required":true,"defaultValue":null,"description":"Requests the neighboring index after activating Previous or Next. Prop changes do not call this callback or select a replacement item."},{"name":"positionPlacement","type":"\"between\" | \"start\"","required":false,"defaultValue":"between","description":"Places the position text between the buttons or at the start of the row. Start placement lets the text fill the available width."},{"name":"positionText","type":"string","required":true,"defaultValue":null,"description":"Caller-formatted position text, announced politely when it changes. The caller also supplies text for empty collections."},{"name":"previousLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the Previous button."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the root element while preserving its props and contents."},{"name":"role","type":"AriaRole","required":false,"defaultValue":"group","description":"Root semantics. Defaults to a group; the caller supplies its accessible name."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root element."}]}},{"name":"TabButton","entryPoint":"twenty-ui/components/navigation","content":"---\ntitle: TabButton\ndescription: Present route links and actions alongside tabs with consistent styling.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport TabButtonReference from '/snippets/ui/generated/components/navigation/tab-button.mdx';\n\n## Overview\n\nUse `TabButton` for route links and actions such as adding a tab or opening an overflow menu. It shares the appearance of [Tabs](/ui/primitives/navigation/tabs) and uses [Button](/ui/primitives/input/button) for interaction.\n\n<StoryEmbed\n storyId=\"ui-components-tabbutton--display\"\n title=\"TabButton example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { TabButton } from 'twenty-ui/components/navigation';\nimport { IconSettings } from 'twenty-ui/icon';\n\nexport const GeneralAction = ({ onOpen }: { onOpen: () => void }) => (\n <TabButton startIcon={<IconSettings />} onClick={onOpen}>\n General\n </TabButton>\n);\n```\n\n## State and semantics\n\nYour application supplies `active` from its current route or menu state. This prop highlights the control. Set `aria-current=\"page\"` on the current route link. Route links and adjacent actions retain their link or button semantics, with no tab role, `aria-selected`, or panel relationship.\n\nUse `Tabs.Root`, `Tabs.List`, `Tabs.Tab`, `Tabs.Panel`, and optional `Tabs.Indicator` to switch between related content panels. Keep route and action controls outside `Tabs.List`.\n\n## Navigation\n\nSet `href` to render a native link. The current route owns its `active` appearance and `aria-current` value.\n\n```tsx\nimport { TabButton } from 'twenty-ui/components/navigation';\nimport { IconCreditCard } from 'twenty-ui/icon';\n\nexport const BillingLink = () => (\n <TabButton\n href=\"/billing\"\n active\n aria-current=\"page\"\n startIcon={<IconCreditCard />}\n >\n Billing\n </TabButton>\n);\n```\n\nFor client-side routing, supply your router link through `render`, set `nativeButton={false}` and `role=\"link\"`, and pass the resolved destination as `href`. Keep route state and history options on the router link. Custom wrappers must forward the supplied props and ref to their anchor.\n\n```tsx\nimport { TabButton } from 'twenty-ui/components/navigation';\n\nexport const ComposedBillingLink = () => (\n <TabButton\n nativeButton={false}\n role=\"link\"\n href=\"/billing\"\n render={<a />}\n aria-current=\"page\"\n active\n >\n Billing\n </TabButton>\n);\n```\n\nAn explicit `nativeButton` controls the interaction contract even when `href` is present. Match it to the actual rendered element. Disabled links retain their link role and block activation.\n\n## Actions\n\nWithout `href`, the control renders a native button with `type=\"button\"`. Native attributes, refs, styles, class names, and event handlers pass through. `render` accepts an element or a function receiving the Button props and state. Refs point to the actual rendered button or anchor, including refs supplied on a composed element.\n\n```tsx\nimport { useState } from 'react';\nimport { TabButton } from 'twenty-ui/components/navigation';\nimport { IconPlus } from 'twenty-ui/icon';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const AddTabAction = () => {\n const [count, setCount] = useState(1);\n\n return (\n <>\n <TabButton startIcon={<IconPlus />} onClick={() => setCount(count + 1)}>\n New Tab\n </TabButton>\n <Text role=\"status\">Tabs: {count}</Text>\n </>\n );\n};\n```\n\nUse `startIcon`, `endIcon`, and `badge` for supporting content. An avatar passed to an icon slot is decorative when the text names the destination. `size` retains the public Button size contract. An explicit size takes priority over a surrounding `ButtonGroup` size; otherwise the component defaults to `sm`.\n\n## Props\n\n<TabButtonReference />\n\n<PageBanner illustration=\"layout\" />\n","api":{"name":"TabButton","entryPoint":"twenty-ui/components/navigation","slug":"components/navigation/tab-button","props":[{"name":"active","type":"boolean","required":false,"defaultValue":"false","description":"Highlights the current destination or an action associated with the active tab. Does not change the control role."},{"name":"badge","type":"ReactNode","required":false,"defaultValue":null,"description":"Content following the label and trailing icon, such as a count."},{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"sm","description":"Padding of the tab content: sm or md. Explicit size takes precedence over the ButtonGroup size, then sm applies."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}},{"name":"AvatarGroup","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: AvatarGroup\ndescription: Overlapping avatars with a derived overflow indicator.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AvatarGroupReference from '/snippets/ui/generated/components/data-display/avatar-group.mdx';\n\n## Overview\n\n`AvatarGroup` receives rendered avatars and derives the hidden count. `maxVisible` counts actual avatars; the overflow indicator is additional. Eight supplied avatars with `maxVisible={3}` show three avatars and `+5`.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--display\"\n title=\"Eight avatars with three visible\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const TeamAvatars = () => (\n <AvatarGroup\n maxVisible={3}\n overflowShape=\"circle\"\n overlap=\"left\"\n overlapOffset=\"4px\"\n avatars={[\n 'Ada',\n 'Grace',\n 'Margaret',\n 'Annie',\n 'Mary',\n 'Dorothy',\n 'Katherine',\n 'Joan',\n ].map((name) => (\n <Avatar\n key={name}\n name={name}\n shape=\"circle\"\n imageProps={{ alt: name }}\n />\n ))}\n />\n);\n```\n\nSupply stable keys to keep surviving avatars mounted when the limit, total, or display order changes. Avatars are decorative by default. When the group is the only representation of its members, supply each member's name through `imageProps.alt` to label the image and default fallback. Keep avatars decorative when visible text or an owner label already supplies that identity.\n\n## Visual options\n\nCompare circle and square avatars at each size. The group keeps three visible members in this comparison.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--catalog\"\n title=\"Compare avatar shapes and sizes\"\n height={850}\n/>\n\n## Partially loaded collections\n\nUse `total` for the full collection size when only some avatars are loaded. Three supplied and visible avatars with `total={20}` show `+17`. Pass all loaded avatars and let the group apply `maxVisible`.\n\n```tsx\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const LoadedTeamAvatars = () => (\n <AvatarGroup\n maxVisible={3}\n total={20}\n avatars={['Ada', 'Grace', 'Margaret'].map((name) => (\n <Avatar key={name} name={name} imageProps={{ alt: name }} />\n ))}\n />\n);\n```\n\n`total` is floored and cannot be smaller than the supplied renderable avatar count. Nonfinite totals use the supplied count. The derived hidden count is always nonnegative.\n\n`maxVisible` defaults to `4`. Finite limits are floored and clamped to zero, `Infinity` shows all supplied avatars, and `NaN` shows none. Empty React nodes do not count as avatars. A zero limit can show only the overflow indicator. An empty group with a positive total can show that total in its indicator; an empty group with no hidden avatars renders nothing.\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--partially-loaded\"\n title=\"Three loaded members from a team of twenty\"\n height={100}\n/>\n\n## Custom overflow\n\n`renderOverflow` receives the same derived hidden count as the default `+N` indicator. It runs only when that count is positive. Return `null` to hide the indicator without changing which avatars are visible.\n\nUse an explicit control when the indicator performs an action. Its accessible name should explain the action and the count.\n\n```tsx\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype TeamAvatarsWithActionProps = { onShowAll: () => void };\n\nexport const TeamAvatarsWithAction = ({\n onShowAll,\n}: TeamAvatarsWithActionProps) => (\n <AvatarGroup\n maxVisible={3}\n total={20}\n avatars={['Ada', 'Grace', 'Margaret'].map((name) => (\n <Avatar key={name} name={name} imageProps={{ alt: name }} />\n ))}\n renderOverflow={(hiddenCount) => (\n <Button\n size=\"sm\"\n aria-label={`Show ${hiddenCount} more members`}\n onClick={onShowAll}\n >\n +{hiddenCount}\n </Button>\n )}\n />\n);\n```\n\n<StoryEmbed\n storyId=\"ui-data-display-avatargroup--custom-overflow\"\n title=\"Custom overflow button\"\n height={100}\n/>\n\n## Appearance\n\nLater avatars always render above earlier ones. `overlap` picks the physical margin, `left` or `right`, that carries the negative offset. `overlapOffset` sets that offset as a CSS length. `overflowShape` sets the shape of the default numeric indicator.\n\n## Root customization\n\nNative attributes, event handlers, `className`, and `style` reach the root. Its default element is a `div`, including when `onClick` is supplied. Use native interactive elements for actions, such as the overflow button above.\n\nThe root accepts a ref and `render`, which can be an element or a function. Custom components must forward the supplied props and ref to their native root. See [custom components](/ui/primitives/overview#custom-components) for composition requirements.\n\n```tsx\nimport { useRef } from 'react';\nimport { AvatarGroup } from 'twenty-ui/components/data-display';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\n\nexport const NamedTeamAvatars = () => {\n const groupRef = useRef<HTMLDivElement>(null);\n\n return (\n <AvatarGroup\n ref={groupRef}\n role=\"group\"\n aria-label=\"Project members\"\n style={{ marginBlock: 8 }}\n render={<div data-location=\"project-header\" />}\n avatars={['Ada', 'Grace', 'Margaret'].map((name) => (\n <Avatar key={name} name={name} imageProps={{ alt: name }} />\n ))}\n />\n );\n};\n```\n\n## Props\n\n`AvatarGroupProps` is exported from `twenty-ui/components/data-display`.\n\n<AvatarGroupReference />\n\n<PageBanner illustration=\"page-cover-users\" />\n","api":{"name":"AvatarGroup","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/avatar-group","props":[{"name":"avatars","type":"ReactNode[]","required":true,"defaultValue":null,"description":"Avatar elements in display order. Empty React nodes are ignored. Supply stable keys to preserve identity when reordering."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the group container."},{"name":"maxVisible","type":"number","required":false,"defaultValue":"4","description":"Maximum number of actual avatars to show, excluding the overflow indicator. Floored and clamped to zero; Infinity shows all avatars and NaN shows none."},{"name":"overflowShape","type":"\"circle\" | \"rounded-square\" | \"square\"","required":false,"defaultValue":"square","description":"Shape of the numeric overflow indicator."},{"name":"overlap","type":"\"left\" | \"right\"","required":false,"defaultValue":"right","description":"Physical margin, left or right, that carries the negative overlap offset. Later avatars always render above earlier ones."},{"name":"overlapOffset","type":"string","required":false,"defaultValue":"3px","description":"CSS length of the overlap between avatars."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the rendered root element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Element or render function for the root. Forward the supplied props and ref; the default element is a div."},{"name":"renderOverflow","type":"((hiddenCount: number) => ReactNode)","required":false,"defaultValue":null,"description":"Called with the derived hidden count when it is positive. Return a custom indicator, or null to hide it."},{"name":"total","type":"number","required":false,"defaultValue":null,"description":"Total collection size for partially loaded avatars. Floored and never smaller than the supplied renderable count; nonfinite values use the supplied count."}]}},{"name":"CommandBlock","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: CommandBlock\ndescription: Display command lines with an optional action.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CommandBlockReference from '/snippets/ui/generated/components/data-display/command-block.mdx';\n\n## Overview\n\n`CommandBlock` displays each supplied command with a prompt marker. It does not execute commands or provide copying automatically. Supply `actions` with any React node, such as a [Button](/ui/primitives/input/button), link or status. Command text uses `pre` and `code` semantics, preserves line breaks, and wraps within the available width. Prompt markers are decorative.\n\n<StoryEmbed\n storyId=\"ui-components-data-display-commandblock--display\"\n title=\"CommandBlock example\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { CommandBlock } from 'twenty-ui/components/data-display';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const InstallCommand = () => {\n const [copyLabel, setCopyLabel] = useState('Copy command');\n\n return (\n <CommandBlock\n commands={['yarn add twenty-ui']}\n actions={\n <Button\n onClick={async () => {\n try {\n await navigator.clipboard.writeText('yarn add twenty-ui');\n setCopyLabel('Copied');\n } catch {\n setCopyLabel('Select and copy the command');\n }\n }}\n >\n {copyLabel}\n </Button>\n }\n />\n );\n};\n```\n\nNative attributes, event handlers, classes, styles and refs target the outer `div`. Use `render` to compose another root, for example `render={<section aria-label=\"Installation commands\" />}`. `CommandBlockProps` is exported from `twenty-ui/components/data-display`.\n\nWhen migrating, replace `button` with `actions`.\n\n## Props\n\n<CommandBlockReference />\n\n<PageBanner illustration=\"card-page-cli\" />\n","api":{"name":"CommandBlock","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/command-block","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Content beside the command lines, such as a copy button, link or status."},{"name":"commands","type":"readonly string[]","required":true,"defaultValue":null,"description":"Command lines to display. The component prefixes each line with > and does not execute commands."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."}]}},{"name":"JsonTree","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: JsonTree\ndescription: Explore JSON values with expandable nodes and custom labels.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport JsonTreeReference from '/snippets/ui/generated/components/data-display/json-tree.mdx';\n\n## Overview\n\n`JsonTree` displays either a JSON `value` or an array of named `entries`. Pass all empty-value and expand/collapse labels so your application controls the text.\n\n<StoryEmbed\n storyId=\"ui-jsonvisualizer-jsontree--display\"\n title=\"Expandable record details\"\n height={320}\n/>\n\n## Usage\n\n```tsx\nimport { JsonTree } from 'twenty-ui/components/data-display';\n\nexport const RecordDetails = () => (\n <JsonTree\n value={{ name: 'Acme', active: true, contacts: [] }}\n emptyStringLabel=\"Empty text\"\n emptyArrayLabel=\"No items\"\n emptyObjectLabel=\"No properties\"\n arrowButtonCollapsedLabel=\"Expand node\"\n arrowButtonExpandedLabel=\"Collapse node\"\n />\n);\n```\n\nEach entry has an `id`, `label`, and JSON `value`. Use entries when display labels differ from stored keys. The default expands depths 0 and 1. Override `shouldExpandNodeInitially={({ depth }) => depth === 0}` to expand only the root; later expansion is owned by each node.\n\n`getNodeHighlighting(keyPath)` returns `blue`, `red`, `partial-blue`, or `undefined`. `onNodeValueClick` receives the displayed text: leaf values as strings, and the matching empty label for empty strings, arrays, and objects. The tree displays data and does not edit it.\n\nWhen `onNodeValueClick` is provided, values are native buttons named by their displayed text. Tab moves focus to a value; Enter, Space, or a pointer click activates it. Without the callback, values remain non-interactive text. Value buttons do not submit enclosing forms.\n\n## Props\n\n<JsonTreeReference />\n\n<PageBanner illustration=\"page-cover-hierarchy\" />\n","api":{"name":"JsonTree","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/json-tree","props":[{"name":"arrowButtonCollapsedLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible label for the expand control on a collapsed node."},{"name":"arrowButtonExpandedLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible label for the collapse control on an expanded node."},{"name":"emptyArrayLabel","type":"string","required":true,"defaultValue":null,"description":"Display text for an empty array."},{"name":"emptyObjectLabel","type":"string","required":true,"defaultValue":null,"description":"Display text for an empty object."},{"name":"emptyStringLabel","type":"string","required":true,"defaultValue":null,"description":"Display text for an empty string."},{"name":"entries","type":"JsonTreeEntry[]","required":false,"defaultValue":null,"description":"Named entries with stable id, label, and JSON value fields. Supply entries or value, not both."},{"name":"getNodeHighlighting","type":"GetJsonNodeHighlighting","required":false,"defaultValue":null,"description":"Returns blue, red, or partial-blue highlighting for a node key path."},{"name":"onNodeValueClick","type":"((valueAsString: string) => void)","required":false,"defaultValue":null,"description":"Called with the clicked value as displayed: leaf values as strings, and the empty label for empty strings, arrays, and objects."},{"name":"shouldExpandNodeInitially","type":"((params: ShouldExpandNodeInitiallyProps) => boolean)","required":false,"defaultValue":"({ depth }: ShouldExpandNodeInitiallyProps) =>\n depth <= 1","description":"Chooses initial expansion from the node keyPath and depth. The default expands the first two depths."},{"name":"value","type":"JsonValue","required":false,"defaultValue":null,"description":"JSON value to display. Supply value or entries, not both."}]}},{"name":"TintedIconTile","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: TintedIconTile\ndescription: An icon on a tinted background derived from a theme color.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport TintedIconTileReference from '/snippets/ui/generated/components/data-display/tinted-icon-tile.mdx';\n\n## Overview\n\nPass icon content through the lowercase `icon` node slot. The tile derives its background and inherited foreground color from the theme palette. Icon content is decorative. Keep a visible label beside it, or give the root `role=\"img\"` and an accessible name for a standalone labeled image.\n\n<StoryEmbed\n storyId=\"ui-components-data-display-tintedicontile--display\"\n title=\"Company icon on a tinted tile\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { TintedIconTile } from 'twenty-ui/components/data-display';\nimport { IconBuildingSkyscraper } from 'twenty-ui/icon';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const CompanyLabel = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>\n <TintedIconTile icon={<IconBuildingSkyscraper size={16} />} color=\"blue\" />\n <Text>Companies</Text>\n </Text>\n);\n```\n\n## Geometry and native composition\n\nThe tile defaults to 16px through the spacing token and uses the small border-radius token. Set icon dimensions and stroke on the node itself. Root `style` or `className` controls tile width, height, border, shape, and colors; explicit styles override palette defaults. Custom artwork should inherit `currentColor` when it uses the palette foreground.\n\n```tsx\nimport { TintedIconTile } from 'twenty-ui/components/data-display';\n\nexport const CustomCompanyTile = () => (\n <TintedIconTile\n icon={\n <svg width=\"20\" height=\"20\" viewBox=\"0 0 20 20\" fill=\"currentColor\">\n <path d=\"M2 2h16v16H2z\" />\n </svg>\n }\n color=\"blue\"\n role=\"img\"\n aria-label=\"Companies\"\n render={<span />}\n style={{ width: 32, height: 32 }}\n />\n);\n```\n\nNative attributes, events, `className`, `style`, and `ref` target the outer div. `render` replaces that target through Base UI composition while preserving the decorative icon content. Name the surrounding control when composing a tile into an action.\n\nReplace `Icon={CompanyIcon}` with `icon={<CompanyIcon size={16} />}`. Move the former `size` and `stroke` options to the icon node, and use root styles for custom tile dimensions.\n\n## Props\n\n<TintedIconTileReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n","api":{"name":"TintedIconTile","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/tinted-icon-tile","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the tile root."},{"name":"color","type":"string | null","required":false,"defaultValue":"gray","description":"Theme palette name used to derive the background and foreground shades. Invalid names use the default theme color."},{"name":"icon","type":"ReactNode","required":true,"defaultValue":null,"description":"Decorative icon content. The caller controls its dimensions and stroke."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the div root while preserving icon content and native props."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles override tile geometry and palette defaults."}]}},{"name":"StackIcon","entryPoint":"twenty-ui/components/data-display","content":"---\ntitle: StackIcon\ndescription: A 16px icon with a smaller item stacked on its bottom-right corner.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport StackIconReference from '/snippets/ui/generated/components/data-display/stack-icon.mdx';\n\n## Overview\n\nPass the main icon through the `icon` node slot and the stacked item through `stackedIcon`. The container is 16px wide and tall; the stacked item is positioned absolutely at 8px from the left and 7px from the top so it overflows the bottom-right corner. A 12px square avatar is the intended size for an application logo. Both nodes are decorative, so keep a visible label beside the icon.\n\nLeave room for the stacked item's overflow when placing neighboring content. The example uses a 12px gap between the icon container and its label.\n\n<StoryEmbed\n storyId=\"ui-components-data-display-stackicon--display\"\n title=\"Company icon with a stacked logo\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { StackIcon } from 'twenty-ui/components/data-display';\nimport { IconBuildingSkyscraper } from 'twenty-ui/icon';\nimport { Avatar } from 'twenty-ui/primitives/data-display';\nimport { Text } from 'twenty-ui/primitives/typography';\n\nexport const CompanyFieldLabel = () => (\n <Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>\n <StackIcon\n icon={<IconBuildingSkyscraper size={16} />}\n stackedIcon={\n <Avatar size=\"xs\" shape=\"square\" variant=\"outline\" name=\"Stripe\" />\n }\n />\n <Text>Companies</Text>\n </Text>\n);\n```\n\nNative attributes, events, `className`, `style`, and `ref` target the outer div. `render` replaces that target through Base UI composition while preserving both icon nodes.\n\n## Props\n\n<StackIconReference />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"StackIcon","entryPoint":"twenty-ui/components/data-display","slug":"components/data-display/stack-icon","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the container root."},{"name":"icon","type":"ReactNode","required":true,"defaultValue":null,"description":"Main icon content. The caller controls its dimensions and stroke."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the div root while preserving the icon content and native props."},{"name":"stackedIcon","type":"ReactNode","required":true,"defaultValue":null,"description":"Smaller content stacked on the bottom-right corner of the main icon, such as a 12px avatar."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the container root."}]}},{"name":"Callout","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Callout\ndescription: Feedback with node content, actions, and caller-owned dismissal.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport CalloutReference from '/snippets/ui/generated/components/feedback/callout.mdx';\n\n## Overview\n\n`Callout` combines title, description, icon, and action nodes. Use `status` for `neutral`, `info`, `success`, `warning`, or `error`. It defaults to `info` and supports the `soft` appearance. The status selects a gray, blue, green, orange, or red palette; `color` overrides that palette without changing the meaning.\n\n<StoryEmbed\n storyId=\"ui-feedback-callout--display\"\n title=\"Callout example\"\n height={230}\n/>\n\n## Usage\n\n```tsx\nimport { Callout } from 'twenty-ui/components/feedback';\n\nexport const WorkflowNotice = () => (\n <Callout\n status=\"neutral\"\n title=\"This form will appear in workflow runs.\"\n description=\"Because this workflow is not using a manual trigger, the form will not open on top of the interface. To fill it, open the corresponding workflow run and complete the form there.\"\n action={<Callout.Action>Learn more</Callout.Action>}\n />\n);\n```\n\n## Visual options\n\nCompare semantic statuses using the same content. Choose a status for the message meaning, and override color only when the surrounding design requires it.\n\n<StoryEmbed\n storyId=\"ui-feedback-callout--catalog\"\n title=\"Callout feedback statuses\"\n height={1010}\n/>\n\n## Dismissible notice\n\n```tsx\nimport { useState } from 'react';\nimport { Callout } from 'twenty-ui/components/feedback';\nimport { IconAlertTriangle } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const ImportNotice = ({ onReview }: { onReview: () => void }) => {\n const [isVisible, setIsVisible] = useState(true);\n\n return (\n <>\n {isVisible && (\n <Callout\n status=\"warning\"\n title=\"Some records need attention\"\n description=\"Review the missing email addresses before importing.\"\n icon={<IconAlertTriangle size={16} aria-hidden=\"true\" />}\n action={\n <Callout.Action onClick={onReview}>Review records</Callout.Action>\n }\n onDismiss={() => setIsVisible(false)}\n closeLabel=\"Dismiss import notice\"\n />\n )}\n <Button onClick={() => setIsVisible(true)}>Show notice</Button>\n </>\n );\n};\n```\n\n## Dismissal and labels\n\nPassing `onDismiss` exposes an accessible close button. Each pointer or keyboard activation calls it once. The callout remains rendered until its caller hides it. Omit `onDismiss` for a persistent message. `closeLabel` defaults to `Close`.\n\nYour application owns the content, actions, accessible names, and translations. Use `Callout.Action` for a small ghost button with regular font weight. It accepts Button props, including link attributes, disabled state, refs, and custom rendering; size and appearance are fixed. The action slot also accepts custom buttons, links, disabled controls, or multiple nodes. The default help icon is decorative; pass `icon={null}` to omit it or supply a node with appropriate accessible semantics. Twenty UI does not require an i18n provider.\n\n## Native integration\n\nNative attributes, `className`, `style`, and `ref` target the root `div`. Use `render` to compose a different root element or a callback receiving the root props and `{ status, variant, color }`. `title` and `description` are content slots. `fullWidth` removes the default 512px maximum width.\n\nThe component adds no live-region role or announcements. Supply native `role`, `aria-live`, and other accessible attributes when the surrounding workflow requires them.\n\n## Migration\n\nReplace the previous semantic `variant` with `status`, and constructor `Icon` with an `icon` node. Replace `{ label, onClick }` action objects with `Callout.Action` or custom controls. Replace `isClosable` and `onClose` with `onDismiss`, and conditionally render the callout in the caller when dismissal should hide it. Existing translated content and action labels stay in the application.\n\n## Props\n\n<CalloutReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Callout","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/callout","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional footer node. Use Callout.Action for the standard action or supply custom controls."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Additional class names merged onto the root."},{"name":"closeLabel","type":"string","required":false,"defaultValue":"Close","description":"Accessible name of the dismiss button. Defaults to `Close`."},{"name":"color","type":"\"blue\" | \"gray\" | \"green\" | \"orange\" | \"red\"","required":false,"defaultValue":"status palette","description":"Palette override: gray, blue, green, orange, or red. Defaults to the status palette."},{"name":"description","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional supporting content node. Empty slots are hidden."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Removes the default 512px maximum width."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":"decorative help icon","description":"Leading icon node. Defaults to a decorative help icon. Pass null to omit it."},{"name":"onDismiss","type":"(() => void)","required":false,"defaultValue":null,"description":"Shows a dismiss button and notifies the caller once per activation. The caller owns visibility."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or the element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CalloutState>","required":false,"defaultValue":null,"description":"Element or callback composition for the root. Receives status, variant, and color state."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"info","description":"Feedback meaning: neutral, info, success, warning, or error. Defaults to info."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles forwarded to the root."},{"name":"title","type":"ReactNode","required":true,"defaultValue":null,"description":"Main message node displayed beside the icon."},{"name":"variant","type":"\"soft\"","required":false,"defaultValue":"soft","description":"Supported appearance: soft."}],"parts":[{"name":"Action","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"color","type":"\"accent\" | \"danger\" | \"inherit\" | \"neutral\" | \"success\"","required":false,"defaultValue":null,"description":"Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"InlineBanner","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: InlineBanner\ndescription: Inline feedback with node content, icons, and actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport InlineBannerReference from '/snippets/ui/generated/components/feedback/inline-banner.mdx';\n\n## Overview\n\n`InlineBanner` composes [Banner](/ui/primitives/feedback/banner) with a rounded inline layout and a decorative information icon. It shares Banner's independent `status`, `variant`, `color`, `icon` and `action` contracts. Its default appearance is `soft` and its default status is `info`.\n\n<StoryEmbed\n storyId=\"ui-feedback-inlinebanner--display\"\n title=\"Inline banner with an action\"\n height={130}\n/>\n\n## Usage\n\n```tsx\nimport { InlineBanner } from 'twenty-ui/components/feedback';\n\nexport const ModelsBanner = ({ onConfigure }: { onConfigure: () => void }) => (\n <InlineBanner\n status=\"error\"\n action={\n <InlineBanner.Action onClick={onConfigure}>\n Configure models\n </InlineBanner.Action>\n }\n >\n No AI models are enabled.\n </InlineBanner>\n);\n```\n\nThe `standard` layout fills the available width. Plain string children truncate, with keyboard focus, pointer hover or touch revealing the full string in a tooltip. Rich node children render directly, so embedded links and controls retain their own semantics. Compose explicit typography when rich content needs truncation.\n\nUse `layout=\"compact\"` for wrapping content, closer spacing and a maximum content width of 512px. Add `fullWidth` to remove that cap and fill the available parent width, including padding and borders. It defaults to `false` and does not change the standard layout, which already fills its parent. It has no bottom margin. Layout is independent of `solid` or `soft` appearance. `embedded` removes the standard layout's bottom margin.\n\n```tsx\nimport { InlineBanner } from 'twenty-ui/components/feedback';\nimport { IconInfoCircle } from 'twenty-ui/icon';\n\nexport const ConnectionBanner = () => (\n <InlineBanner\n layout=\"compact\"\n status=\"warning\"\n color=\"blue\"\n icon={<IconInfoCircle aria-hidden=\"true\" />}\n action={\n <InlineBanner.Action href=\"/settings/accounts\">\n Connection settings\n </InlineBanner.Action>\n }\n >\n Connect your account to sync contacts.\n </InlineBanner>\n);\n```\n\n<StoryEmbed\n storyId=\"ui-feedback-inlinebanner--compact-link\"\n title=\"Compact banner with a destination link\"\n height={120}\n/>\n\n`InlineBanner.Action` provides a small outline button that inherits the banner’s displayed color, including explicit palette overrides and solid appearances. It supports Button interactions, links, refs and custom rendering. The `action` slot also accepts arbitrary controls.\n\nThe root target is a `div`. Native props, `className`, `style` and `ref` target that root; Base UI `render` can compose another element and receives resolved Banner state. `action` accepts any ReactNode, including multiple controls with their complete Button or link APIs. `icon={null}` removes the default icon.\n\nThe caller owns whether the banner is rendered and whether changes should be announced. Supply `role=\"status\"` and `aria-live=\"polite\"`, or an appropriate live-region wrapper, when needed. Status does not assign live-region semantics. Name action controls and mark decorative custom icons with `aria-hidden`.\n\n## Migration\n\nReplace `message` with `children`, `LeftIcon={Icon}` with `icon={<Icon />}`, and `button` configuration with an `action` node. Use `InlineBanner.Action` to keep action styling aligned with the banner. Replace `variant=\"compact\"` with `layout=\"compact\"`; standard is now the default layout. Use `status=\"error\"` for error meaning or `color=\"red\"` for a palette override.\n\n## Props\n\n<InlineBannerReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"InlineBanner","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/inline-banner","props":[{"name":"action","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trailing ReactNode. InlineBanner.Action supplies the shared banner action preset and inherits the resolved banner color; arbitrary controls are also accepted."},{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Caller-provided content. Standard plain strings truncate with a focusable tooltip; rich nodes render directly. Compact content wraps."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged onto the root div or composed element."},{"name":"color","type":"\"blue\" | \"gray\" | \"green\" | \"orange\" | \"red\"","required":false,"defaultValue":"status palette","description":"Gray, blue, green, orange or red palette override. An omitted color follows status."},{"name":"embedded","type":"boolean","required":false,"defaultValue":"false","description":"Removes the standard bottom margin. Compact layouts have no bottom margin."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":"false","description":"Fills the available parent width, including padding and borders, and removes the compact layout's 512px maximum. Defaults to false; standard layout already fills its parent."},{"name":"icon","type":"ReactNode","required":false,"defaultValue":"decorative information icon","description":"Leading ReactNode. Defaults to a decorative information icon. Pass null to omit it."},{"name":"layout","type":"\"compact\" | \"standard\"","required":false,"defaultValue":"standard","description":"Standard full-width layout or compact wrapping layout with a 512px maximum content width. Defaults to standard."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div, or to the DOM element supplied through render."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, BannerState>","required":false,"defaultValue":null,"description":"Base UI root element or render callback, receiving native props/ref and resolved Banner state."},{"name":"status","type":"\"error\" | \"info\" | \"neutral\" | \"success\" | \"warning\"","required":false,"defaultValue":"info","description":"Feedback meaning: neutral, info, success, warning or error. Defaults to info. Roles and announcements remain caller-owned."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root div or composed element."},{"name":"variant","type":"\"soft\" | \"solid\"","required":false,"defaultValue":"soft","description":"Solid or soft appearance, independently of status and layout. Defaults to soft."}],"parts":[{"name":"Action","props":[{"name":"className","type":"string | ((state: ButtonState) => string | undefined)","required":false,"defaultValue":null,"description":"CSS class applied to the element, or a function that\nreturns a class based on the component's state."},{"name":"elevated","type":"boolean","required":false,"defaultValue":null,"description":"Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors."},{"name":"endIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed after the label."},{"name":"focusableWhenDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Whether the button should be focusable when disabled."},{"name":"fullWidth","type":"boolean","required":false,"defaultValue":null,"description":"Expands the button to fill its container width."},{"name":"href","type":"string","required":false,"defaultValue":null,"description":"Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract."},{"name":"loading","type":"boolean","required":false,"defaultValue":null,"description":"Shows a loading indicator and disables activation."},{"name":"loadingPosition","type":"\"center\" | \"end\" | \"start\"","required":false,"defaultValue":null,"description":"Where the loading indicator appears. `center` hides the content while preserving its layout space; `start` and `end` keep children and the opposite icon visible and replace the corresponding icon with the spinner."},{"name":"nativeButton","type":"boolean","required":false,"defaultValue":"true","description":"Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>","required":false,"defaultValue":null,"description":"Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role=\"link\"` for a custom navigation anchor. Router integration belongs to the caller."},{"name":"role","type":"AriaRole","required":false,"defaultValue":null,"description":"Role of the root element. Use `link` for custom navigation renderers."},{"name":"shortcut","type":"ShortcutDefinition","required":false,"defaultValue":null,"description":"Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens."},{"name":"shortcutJoinLabel","type":"string","required":false,"defaultValue":null,"description":"Localized text between sequence steps. Defaults to then."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Decorative content displayed before the label."},{"name":"style","type":"CSSProperties | ((state: ButtonState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."}]}]}},{"name":"ToastProvider","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Toast\ndescription: Display status messages with optional details, actions, and progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ToastReference from '/snippets/ui/generated/components/feedback/toast.mdx';\nimport ToastProviderReference from '/snippets/ui/generated/components/feedback/toast-provider.mdx';\nimport ToasterReference from '/snippets/ui/generated/components/feedback/toaster.mdx';\n\n## Overview\n\n`Toast` renders one notification. Your application controls when it appears, its position, and when it is removed.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--display\"\n title=\"Toast example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SavedNotification = () => {\n const [isOpen, setIsOpen] = useState(true);\n\n return (\n <>\n <Button onClick={() => setIsOpen(true)}>Show notification</Button>\n {isOpen && (\n <Toast status=\"success\" progress={100} onClose={() => setIsOpen(false)}>\n Changes saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n## Visual options\n\nCompare neutral, success, error, information, and warning feedback with the same message and progress.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--catalog\"\n title=\"Toast feedback statuses\"\n height={530}\n/>\n\nFor application notifications, wrap the application in `ToastProvider`, mount a `Toaster` inside it, and use `useToast()` from descendants. Each provider owns an independent notification store, countdowns, and dismissal lifecycle. Multiple Toasters can mirror the same provider.\n\n## Application notifications\n\n```tsx\nimport { useState } from 'react';\n\nimport {\n ToastProvider,\n Toaster,\n useToast,\n} from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst SaveNotificationButton = () => {\n const { enqueueToast } = useToast();\n\n return (\n <Button\n onClick={() =>\n enqueueToast({\n children: 'Record saved',\n status: 'success',\n })\n }\n >\n Add saved notification\n </Button>\n );\n};\n\nexport const Notifications = () => {\n const [limit, setLimit] = useState(3);\n\n return (\n <ToastProvider limit={limit}>\n <SaveNotificationButton />\n <Button onClick={() => setLimit(1)}>Keep one notification</Button>\n <Button onClick={() => setLimit(3)}>Keep three notifications</Button>\n <Toaster />\n </ToastProvider>\n );\n};\n```\n\n`enqueueToast` accepts Toast props and an optional `dedupeKey`, and returns the notification ID. A matching visible key returns the existing ID without adding another notification. `updateToast({ id, ...changes })` patches that live notification. `closeToast(id)` dismisses one notification; `closeToast()` dismisses all visible notifications in the provider.\n\nThe provider defaults to three visible notifications. `limit` must be a positive integer and can change while the provider is mounted. Lowering it or adding above it dismisses the oldest visible notifications first. Increasing it leaves existing notifications unchanged and does not restore dismissed notifications. Configuration changes preserve the store, surviving IDs, order, and remaining countdown time.\n\n## Provider lifecycle\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--documentation\"\n title=\"Shared notification lifecycle\"\n height={430}\n/>\n\nMultiple Toasters inside a provider render the same notifications. Updates and dismissal apply to every mirror, and each notification has one shared countdown. Hover or focus inside any mirror pauses it; it resumes after all mirrors release both. Mounting another Toaster does not restart the countdown or create another callback lifecycle. Use separate providers for independent queues.\n\nFor provider notifications, expiry, the close button, `closeToast`, and limit eviction call the latest `onClose` once. The notification is already dismissed when the callback runs, so updates and repeated close requests for that ID have no effect. `onCancel` remains a separate action callback and does not dismiss automatically.\n\nDismissed notifications are inert during exit animations. Their entries are removed after all rendered mirrors finish their exit work or unmount. Unmounting the last Toaster clears dismissed entries and freezes the remaining time for visible notifications. Remounting a Toaster resumes that time. Unmounting the provider discards its notifications and cancels countdown and exit work without calling `onClose`. Captured `enqueueToast`, `updateToast`, and `closeToast` operations from that provider have no effect after it unmounts.\n\n`getToastProps` adapts each notification’s content and presentation. Set `duration` and `progress` in `enqueueToast` or `updateToast` so every mirror shares the same timing configuration. Existing timing overrides through `getToastProps` remain supported when all mirrors return the same duration and progress for a notification. The provider retains the ID, dismissal handler, and shared countdown.\n\n`container` selects a Toaster’s portal destination. When omitted, it uses the surrounding theme container or `document.body`. An explicit element renders there; `null` defers rendering. Visible notifications remain queued, with their countdowns paused while no Toaster is rendered. Portals retain the surrounding theme and direction. Set `aria-label` on each Toaster to localize its default region name, \"Notifications\", and give mirrored regions appropriate names.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--portal-documentation\"\n title=\"Scoped notification portal\"\n height={430}\n/>\n\n## Update a live notification\n\nUse the ID returned by `enqueueToast` to update content, feedback status, actions, or callbacks in place. Updates preserve the notification's ID and position. Unknown or dismissed IDs have no effect, including while the dismissal animation runs. Each `useToast()` call targets its closest provider.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster--updates-documentation\"\n title=\"Update a live notification\"\n height={380}\n/>\n\n```tsx\nimport { useToast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveButtonProps = {\n saveRecord: () => Promise<void>;\n onViewRecord: () => void;\n};\n\nexport const SaveButton = ({ saveRecord, onViewRecord }: SaveButtonProps) => {\n const { enqueueToast, updateToast } = useToast();\n\n const save = async () => {\n const id = enqueueToast({\n children: 'Saving record',\n status: 'info',\n progress: 0,\n });\n\n try {\n await saveRecord();\n updateToast({\n id,\n children: 'Record saved',\n status: 'success',\n progress: undefined,\n action: <Button onClick={onViewRecord}>View record</Button>,\n });\n } catch {\n updateToast({\n id,\n children: 'Record could not be saved',\n status: 'error',\n progress: undefined,\n });\n }\n };\n\n return <Button onClick={save}>Save record</Button>;\n};\n```\n\n`ToastUpdate` requires `id` and accepts partial Toast options. Omitted fields keep their current values. Explicit `undefined` clears an optional field or restores its component default, such as `progress: undefined` or `status: undefined`. Pass `null` to remove a content slot, including `description`, `icon`, or `action`. Setting `cancelLabel: null` hides the cancel control while preserving its callback. Callback changes take effect on the existing notification. `dedupeKey` belongs to enqueueing and cannot be updated.\n\n## Dismissal timing\n\nThe countdown defaults to 6,000 milliseconds. It pauses while the pointer is over the toast or keyboard focus is inside it, and resumes only after both leave. With multiple Toasters, pause state is shared across their mirrors. The visual countdown follows the remaining dismissal time. Automatic dismissal also works when reduced motion disables the animation.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-timing--documentation\"\n title=\"Toast timing controls\"\n height={480}\n/>\n\n| Operation | Countdown behavior |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Update content, status, actions, or callbacks | Preserve the remaining time. Repeated updates do not extend it. |\n| Supply `duration` to `updateToast` | Start a fresh duration, including when the value is unchanged. `duration: undefined` restores the default and restarts it. |\n| Change a standalone `Toast`'s `duration` prop | Start a fresh duration. Rendering the same value again keeps the remaining time. |\n| Set `duration: 0` | Keep the toast open until it is dismissed. |\n| Supply `progress` | Stop the countdown while progress is present. |\n| Remove `progress` | Start a fresh duration, or keep it open when its duration is zero. |\n| Update while hovered or focused | Apply the same rules, keeping the resulting countdown paused until both pointer and focus leave. |\n\nFor example, `updateToast({ id, children: 'Still saving' })` preserves the remaining time, while `updateToast({ id, duration: 6000 })` gives the reader another six seconds. These rules apply to the existing notification without changing its ID or position.\n\n## Dismissible notification\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveNotification = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <>\n <Button onClick={() => setVisible(true)}>Show saved notification</Button>\n {visible && (\n <Toast\n status=\"success\"\n description=\"Your changes are available to your team.\"\n duration={6000}\n onClose={() => setVisible(false)}\n >\n Record saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n`onClose` is called once by the close button or when the countdown completes. Remove the toast in that callback. Use `duration={0}` for a notification that stays open until dismissal.\n\n## Progress and cancellation\n\n```tsx\nimport { Toast } from 'twenty-ui/components/feedback';\n\ntype ImportProgressProps = { progress: number; onCancel: () => void };\n\nexport const ImportProgress = ({ progress, onCancel }: ImportProgressProps) => (\n <Toast\n status=\"info\"\n progress={progress}\n description=\"You can continue working while the import runs.\"\n onCancel={onCancel}\n cancelLabel=\"Cancel import\"\n >\n Importing records: {progress}%\n </Toast>\n);\n```\n\nPassing `progress` supplies a percentage and disables the countdown. Remove it after the operation finishes to start a fresh duration. Cancellation invokes `onCancel`; the parent owns cancellation and removal. `cancelLabel` accepts a React node for the button content. Children, `description`, `icon`, and `action` also accept caller-owned React nodes. Use Twenty UI controls for interactive actions and provide their accessible names.\n\n## Appearance and announcements\n\n`status` accepts `neutral`, `info`, `success`, `warning`, or `error` and defaults to `neutral`. It expresses feedback meaning and selects the icon and theme palette. Toast has one supported appearance, so it exposes no appearance `variant` or palette `color` option. Use `icon` to replace the icon, `icon={null}` to omit it, and `iconLabel` when the default icon needs its own accessible name.\n\nThe default role is `status` with polite announcements. Use `role=\"alert\"` for urgent feedback. Set `cancelLabel` and `closeLabel` to localize the controls, and allow enough time to read the content or interact with its actions.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, styles, class names, event handlers, and refs target the root. Use `render` to compose another element or component while retaining those props and the ref. Toaster portals inherit the surrounding theme and text direction.\n\n<ToastReference />\n\n### ToastProvider\n\n<ToastProviderReference />\n\n### Toaster\n\nNative div attributes, styles, class names, and refs target the notification region.\n\n<ToasterReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"ToastProvider","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/toast-provider","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Application content and any Toasters sharing this provider’s independent notification store and lifecycle."},{"name":"limit","type":"number","required":false,"defaultValue":"3","description":"Reactive maximum number of visible toasts, defaulting to three. Must be a positive integer. Lowering it or adding above it dismisses the oldest visible notifications and calls their onClose once. Surviving IDs, order, and countdowns are preserved."}]}},{"name":"Toaster","entryPoint":"twenty-ui/components/feedback","content":"---\ntitle: Toast\ndescription: Display status messages with optional details, actions, and progress.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\n\nimport ToastReference from '/snippets/ui/generated/components/feedback/toast.mdx';\nimport ToastProviderReference from '/snippets/ui/generated/components/feedback/toast-provider.mdx';\nimport ToasterReference from '/snippets/ui/generated/components/feedback/toaster.mdx';\n\n## Overview\n\n`Toast` renders one notification. Your application controls when it appears, its position, and when it is removed.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--display\"\n title=\"Toast example\"\n height={120}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SavedNotification = () => {\n const [isOpen, setIsOpen] = useState(true);\n\n return (\n <>\n <Button onClick={() => setIsOpen(true)}>Show notification</Button>\n {isOpen && (\n <Toast status=\"success\" progress={100} onClose={() => setIsOpen(false)}>\n Changes saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n## Visual options\n\nCompare neutral, success, error, information, and warning feedback with the same message and progress.\n\n<StoryEmbed\n storyId=\"ui-feedback-toast--catalog\"\n title=\"Toast feedback statuses\"\n height={530}\n/>\n\nFor application notifications, wrap the application in `ToastProvider`, mount a `Toaster` inside it, and use `useToast()` from descendants. Each provider owns an independent notification store, countdowns, and dismissal lifecycle. Multiple Toasters can mirror the same provider.\n\n## Application notifications\n\n```tsx\nimport { useState } from 'react';\n\nimport {\n ToastProvider,\n Toaster,\n useToast,\n} from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nconst SaveNotificationButton = () => {\n const { enqueueToast } = useToast();\n\n return (\n <Button\n onClick={() =>\n enqueueToast({\n children: 'Record saved',\n status: 'success',\n })\n }\n >\n Add saved notification\n </Button>\n );\n};\n\nexport const Notifications = () => {\n const [limit, setLimit] = useState(3);\n\n return (\n <ToastProvider limit={limit}>\n <SaveNotificationButton />\n <Button onClick={() => setLimit(1)}>Keep one notification</Button>\n <Button onClick={() => setLimit(3)}>Keep three notifications</Button>\n <Toaster />\n </ToastProvider>\n );\n};\n```\n\n`enqueueToast` accepts Toast props and an optional `dedupeKey`, and returns the notification ID. A matching visible key returns the existing ID without adding another notification. `updateToast({ id, ...changes })` patches that live notification. `closeToast(id)` dismisses one notification; `closeToast()` dismisses all visible notifications in the provider.\n\nThe provider defaults to three visible notifications. `limit` must be a positive integer and can change while the provider is mounted. Lowering it or adding above it dismisses the oldest visible notifications first. Increasing it leaves existing notifications unchanged and does not restore dismissed notifications. Configuration changes preserve the store, surviving IDs, order, and remaining countdown time.\n\n## Provider lifecycle\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--documentation\"\n title=\"Shared notification lifecycle\"\n height={430}\n/>\n\nMultiple Toasters inside a provider render the same notifications. Updates and dismissal apply to every mirror, and each notification has one shared countdown. Hover or focus inside any mirror pauses it; it resumes after all mirrors release both. Mounting another Toaster does not restart the countdown or create another callback lifecycle. Use separate providers for independent queues.\n\nFor provider notifications, expiry, the close button, `closeToast`, and limit eviction call the latest `onClose` once. The notification is already dismissed when the callback runs, so updates and repeated close requests for that ID have no effect. `onCancel` remains a separate action callback and does not dismiss automatically.\n\nDismissed notifications are inert during exit animations. Their entries are removed after all rendered mirrors finish their exit work or unmount. Unmounting the last Toaster clears dismissed entries and freezes the remaining time for visible notifications. Remounting a Toaster resumes that time. Unmounting the provider discards its notifications and cancels countdown and exit work without calling `onClose`. Captured `enqueueToast`, `updateToast`, and `closeToast` operations from that provider have no effect after it unmounts.\n\n`getToastProps` adapts each notification’s content and presentation. Set `duration` and `progress` in `enqueueToast` or `updateToast` so every mirror shares the same timing configuration. Existing timing overrides through `getToastProps` remain supported when all mirrors return the same duration and progress for a notification. The provider retains the ID, dismissal handler, and shared countdown.\n\n`container` selects a Toaster’s portal destination. When omitted, it uses the surrounding theme container or `document.body`. An explicit element renders there; `null` defers rendering. Visible notifications remain queued, with their countdowns paused while no Toaster is rendered. Portals retain the surrounding theme and direction. Set `aria-label` on each Toaster to localize its default region name, \"Notifications\", and give mirrored regions appropriate names.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-lifecycle--portal-documentation\"\n title=\"Scoped notification portal\"\n height={430}\n/>\n\n## Update a live notification\n\nUse the ID returned by `enqueueToast` to update content, feedback status, actions, or callbacks in place. Updates preserve the notification's ID and position. Unknown or dismissed IDs have no effect, including while the dismissal animation runs. Each `useToast()` call targets its closest provider.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster--updates-documentation\"\n title=\"Update a live notification\"\n height={380}\n/>\n\n```tsx\nimport { useToast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\ntype SaveButtonProps = {\n saveRecord: () => Promise<void>;\n onViewRecord: () => void;\n};\n\nexport const SaveButton = ({ saveRecord, onViewRecord }: SaveButtonProps) => {\n const { enqueueToast, updateToast } = useToast();\n\n const save = async () => {\n const id = enqueueToast({\n children: 'Saving record',\n status: 'info',\n progress: 0,\n });\n\n try {\n await saveRecord();\n updateToast({\n id,\n children: 'Record saved',\n status: 'success',\n progress: undefined,\n action: <Button onClick={onViewRecord}>View record</Button>,\n });\n } catch {\n updateToast({\n id,\n children: 'Record could not be saved',\n status: 'error',\n progress: undefined,\n });\n }\n };\n\n return <Button onClick={save}>Save record</Button>;\n};\n```\n\n`ToastUpdate` requires `id` and accepts partial Toast options. Omitted fields keep their current values. Explicit `undefined` clears an optional field or restores its component default, such as `progress: undefined` or `status: undefined`. Pass `null` to remove a content slot, including `description`, `icon`, or `action`. Setting `cancelLabel: null` hides the cancel control while preserving its callback. Callback changes take effect on the existing notification. `dedupeKey` belongs to enqueueing and cannot be updated.\n\n## Dismissal timing\n\nThe countdown defaults to 6,000 milliseconds. It pauses while the pointer is over the toast or keyboard focus is inside it, and resumes only after both leave. With multiple Toasters, pause state is shared across their mirrors. The visual countdown follows the remaining dismissal time. Automatic dismissal also works when reduced motion disables the animation.\n\n<StoryEmbed\n storyId=\"ui-feedback-toaster-timing--documentation\"\n title=\"Toast timing controls\"\n height={480}\n/>\n\n| Operation | Countdown behavior |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Update content, status, actions, or callbacks | Preserve the remaining time. Repeated updates do not extend it. |\n| Supply `duration` to `updateToast` | Start a fresh duration, including when the value is unchanged. `duration: undefined` restores the default and restarts it. |\n| Change a standalone `Toast`'s `duration` prop | Start a fresh duration. Rendering the same value again keeps the remaining time. |\n| Set `duration: 0` | Keep the toast open until it is dismissed. |\n| Supply `progress` | Stop the countdown while progress is present. |\n| Remove `progress` | Start a fresh duration, or keep it open when its duration is zero. |\n| Update while hovered or focused | Apply the same rules, keeping the resulting countdown paused until both pointer and focus leave. |\n\nFor example, `updateToast({ id, children: 'Still saving' })` preserves the remaining time, while `updateToast({ id, duration: 6000 })` gives the reader another six seconds. These rules apply to the existing notification without changing its ID or position.\n\n## Dismissible notification\n\n```tsx\nimport { useState } from 'react';\nimport { Toast } from 'twenty-ui/components/feedback';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const SaveNotification = () => {\n const [visible, setVisible] = useState(false);\n\n return (\n <>\n <Button onClick={() => setVisible(true)}>Show saved notification</Button>\n {visible && (\n <Toast\n status=\"success\"\n description=\"Your changes are available to your team.\"\n duration={6000}\n onClose={() => setVisible(false)}\n >\n Record saved\n </Toast>\n )}\n </>\n );\n};\n```\n\n`onClose` is called once by the close button or when the countdown completes. Remove the toast in that callback. Use `duration={0}` for a notification that stays open until dismissal.\n\n## Progress and cancellation\n\n```tsx\nimport { Toast } from 'twenty-ui/components/feedback';\n\ntype ImportProgressProps = { progress: number; onCancel: () => void };\n\nexport const ImportProgress = ({ progress, onCancel }: ImportProgressProps) => (\n <Toast\n status=\"info\"\n progress={progress}\n description=\"You can continue working while the import runs.\"\n onCancel={onCancel}\n cancelLabel=\"Cancel import\"\n >\n Importing records: {progress}%\n </Toast>\n);\n```\n\nPassing `progress` supplies a percentage and disables the countdown. Remove it after the operation finishes to start a fresh duration. Cancellation invokes `onCancel`; the parent owns cancellation and removal. `cancelLabel` accepts a React node for the button content. Children, `description`, `icon`, and `action` also accept caller-owned React nodes. Use Twenty UI controls for interactive actions and provide their accessible names.\n\n## Appearance and announcements\n\n`status` accepts `neutral`, `info`, `success`, `warning`, or `error` and defaults to `neutral`. It expresses feedback meaning and selects the icon and theme palette. Toast has one supported appearance, so it exposes no appearance `variant` or palette `color` option. Use `icon` to replace the icon, `icon={null}` to omit it, and `iconLabel` when the default icon needs its own accessible name.\n\nThe default role is `status` with polite announcements. Use `role=\"alert\"` for urgent feedback. Set `cancelLabel` and `closeLabel` to localize the controls, and allow enough time to read the content or interact with its actions.\n\n## Props\n\nThe reference is generated from the public component types. Native attributes, styles, class names, event handlers, and refs target the root. Use `render` to compose another element or component while retaining those props and the ref. Toaster portals inherit the surrounding theme and text direction.\n\n<ToastReference />\n\n### ToastProvider\n\n<ToastProviderReference />\n\n### Toaster\n\nNative div attributes, styles, class names, and refs target the notification region.\n\n<ToasterReference />\n\n<PageBanner illustration=\"card-page-messaging-channels\" />\n","api":{"name":"Toaster","entryPoint":"twenty-ui/components/feedback","slug":"components/feedback/toaster","props":[{"name":"container","type":"HTMLElement | null","required":false,"defaultValue":null,"description":"Portal destination. Omit to use the theme container or document.body; null defers rendering. The provider retains visible notifications and pauses their countdowns while no Toaster is rendered."},{"name":"getToastProps","type":"((toast: ToastNotification) => Partial<Omit<ToastProps, \"ref\" | \"id\" | \"onClose\">>)","required":false,"defaultValue":null,"description":"Adapts notification content and presentation. The provider owns id, dismissal, and the shared countdown. Set timing through enqueueToast or updateToast; duration and progress overrides must match across Toasters sharing a provider."},{"name":"render","type":"RenderProp<Record<string, unknown>>","required":false,"defaultValue":null,"description":"Custom root element composed through Base UI."}]}},{"name":"FormFieldRow","entryPoint":"twenty-ui/components/input","content":"---\ntitle: FormFieldRow\ndescription: Align a field label, content and trailing controls in a shared row.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport FormFieldRowReference from '/snippets/ui/generated/components/input/form-field-row.mdx';\n\n## Overview\n\n`FormFieldRow` lays out a field label, optional decorative icon, field content and trailing controls. Use it for composer fields or other aligned field groups. Your application owns field values, validation, permissions and persistence.\n\n<StoryEmbed\n storyId=\"ui-input-formfieldrow--display\"\n title=\"Form field row\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { FormFieldRow, LightButton } from 'twenty-ui/components/input';\nimport { Input } from 'twenty-ui/primitives/input';\n\nexport const SubjectField = () => {\n const [subject, setSubject] = useState('Project update');\n\n return (\n <FormFieldRow\n label=\"Subject\"\n hasDivider={false}\n trailing={\n <LightButton size=\"sm\" onClick={() => setSubject('')}>\n Clear\n </LightButton>\n }\n >\n <Input\n variant=\"plain\"\n aria-label=\"Subject\"\n value={subject}\n onValueChange={setSubject}\n />\n </FormFieldRow>\n );\n};\n```\n\n## Layout and labels\n\n`labelWidth` defaults to 80 pixels and accepts a CSS width. Use the same value on sibling rows to align their labels. The label column is capped at 40% of the row, and content can wrap in narrow layouts. `startIcon` is decorative; the caller supplies its dimensions. Set `hasDivider={false}` on a final row when the surrounding surface provides its border.\n\nThe root is a group named by `label`. Supply `aria-label` or `aria-labelledby` when the visible label is omitted, and label each nested input separately. The row does not move focus or disable nested controls. Those controls retain their own keyboard behavior and focus styling.\n\n`contentPaddingInline` defaults to the `--t-spacing-2` theme token, which is 8 pixels in the standard theme, and accepts a CSS padding value. Numeric values use pixels. Set `contentPaddingInline={0}` to align recipient chips and an input with the row inset when there is no visible label.\n\n<StoryEmbed\n storyId=\"ui-input-formfieldrow--without-label\"\n title=\"Recipient row without a visible label\"\n height={110}\n/>\n\n## Events and customization\n\nNative attributes, event handlers, `className`, `style`, `ref` and `render` apply to the group root. Forward supplied props and ref when replacing the root through `render`. An `onClick` handler shows a pointer cursor. The caller owns click-to-focus behavior and guards events from nested controls or portals when needed. `isHoverable` independently enables a neutral hover background.\n\n`trailingProps` applies native attributes, handlers and ref to the existing trailing wrapper. Its `className` is merged with the shared layout class. Use its `onClick` handler to stop a trailing action from triggering a row click handler. The wrapper exists only when `trailing` has renderable content.\n\n## Props\n\n<FormFieldRowReference />\n\n<PageBanner illustration=\"page-cover-input\" />\n","api":{"name":"FormFieldRow","entryPoint":"twenty-ui/components/input","slug":"components/input/form-field-row","props":[{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Field content, such as plain inputs, recipient chips, selectors or toggles. The caller owns input labels, state and click-to-focus behavior."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the group root."},{"name":"contentPaddingInline","type":"PaddingInline<string | number>","required":false,"defaultValue":"var(--t-spacing-2)","description":"Inline padding around the field content, defaulting to the --t-spacing-2 theme token (8 pixels in the standard theme). Numbers use pixels; CSS padding values are also supported. Set 0 to align content with the row inset when no visible label is present."},{"name":"hasDivider","type":"boolean","required":false,"defaultValue":"true","description":"Shows a decorative bottom divider. Set false on the final row when the surrounding surface supplies its own border."},{"name":"isHoverable","type":"boolean","required":false,"defaultValue":"false","description":"Enables a neutral hover background independently of click handlers. Keyboard focus remains on nested controls without changing the row background."},{"name":"label","type":"string","required":false,"defaultValue":null,"description":"Optional visible field label and default group name. Supply aria-label or aria-labelledby when the label is omitted. Label each nested input separately."},{"name":"labelWidth","type":"Width<string | number>","required":false,"defaultValue":"80","description":"Preferred label column width, capped at 40% of the row. Numbers use pixels; use the same width for aligned sibling rows."},{"name":"onClick","type":"MouseEventHandler<HTMLDivElement>","required":false,"defaultValue":null,"description":"Native group click handler. Providing a handler shows a pointer cursor; the caller guards nested-control and portaled events as needed."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref forwarded to the group root div."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Customizes the group root. Forward its props and ref."},{"name":"startIcon","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional decorative icon before the label. The caller controls icon dimensions."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the group root."},{"name":"trailing","type":"ReactNode","required":false,"defaultValue":null,"description":"Optional trailing content. Nested controls retain their own keyboard focus and event behavior."},{"name":"trailingProps","type":"Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, \"children\">","required":false,"defaultValue":null,"description":"Native props, event handlers and ref applied to the trailing content wrapper. The wrapper is rendered only when trailing content is present; className is merged with the shared layout class."}]}},{"name":"ImageInput","entryPoint":"twenty-ui/components/input","content":"---\ntitle: ImageInput\ndescription: Image selection, preview, and caller-owned upload actions.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport ImageInputReference from '/snippets/ui/generated/components/input/image-input.mdx';\n\n## Overview\n\n`ImageInput` combines an image preview, a native file picker, and upload, remove, or abort actions. `onFileSelect` fires when a file is selected. Your application validates and uploads the file, owns upload progress and cancellation, and supplies the preview URL through `src`.\n\n<StoryEmbed\n storyId=\"ui-input-imageinput--display\"\n title=\"Choose, preview, and remove an image\"\n height={140}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { ImageInput } from 'twenty-ui/components/input';\n\nexport const WorkspaceImage = () => {\n const [preview, setPreview] = useState<{\n src?: string;\n reader?: FileReader;\n }>({});\n\n return (\n <ImageInput\n helperText=\"Choose a square image for your workspace.\"\n src={preview.src}\n onFileSelect={(file) => {\n const reader = new FileReader();\n setPreview((current) => ({ src: current.src, reader }));\n reader.onload = () => {\n setPreview((current) => {\n if (current.reader !== reader) {\n return current;\n }\n\n return { src: reader.result?.toString() };\n });\n };\n reader.readAsDataURL(file);\n }}\n onRemove={() => setPreview({})}\n />\n );\n};\n```\n\nThe example keeps the current preview while reading a replacement and ignores reads from removed or superseded selections.\n\n## Selection and preview\n\nThe preview and Upload button open the same native file picker. `onFileSelect` receives the selected `File`; it does not start an upload itself. Canceling or returning an empty selection leaves the current image unchanged. The file input clears after selection so the same file can be selected again, and the callback's `File` remains usable.\n\nFront components support native selection and readable `File` contents. The SDK-built React and Preact flows are verified in Chromium with pointer, Enter and Space activation. The picker opens only from a trusted click inside the component. Worker-created object URLs assigned to an image `src` support previews.\n\n`accept` defaults to `image/*` and filters the file picker. Validate allowed formats, dimensions, and size in your application. This callback-driven selector does not retain a file for native form submission. Its action buttons use `type=\"button\"`, so they do not submit a surrounding form.\n\nAn empty or failed image shows a placeholder. Changing `src` retries the preview, including after an earlier image failed to load. Removal calls `onRemove`; update `src` after your application removes the image. The application owns local preview URLs and revokes worker-created object URLs when they are no longer needed. The renderer owns cleanup of its host preview URLs.\n\n## Root and file input props\n\n`className`, `style`, and `ref` apply to the root div. The default root ref receives an `HTMLDivElement`; use `inputRef` for the hidden file input. Use `render={<div ... />}` to supply native root attributes or event handlers. Keep that root non-interactive, since the module already contains buttons. `dir` applies to both the root and file input; use `dir=\"rtl\"` for right-to-left layout.\n\nNative file input attributes are top-level props, including `accept`, `capture`, `name`, `id`, `title`, `form`, `required`, accessible attributes, data attributes, and event handlers. They apply to the hidden input. `inputRef` receives its `HTMLInputElement`. The control always uses `type=\"file\"`, accepts one file, and resets its value after every selection. `children`, `dangerouslySetInnerHTML`, `type`, `multiple`, `value`, `defaultValue`, and `hidden` cannot be customized.\n\nNative `required` validation still sees an empty input after selection because the input resets. Validate completed uploads in your application.\n\n`onChange` receives the native change event while the input still contains the selected file. The input then resets before `onFileSelect` fires. Native event props follow React's input contract. `onAbort` is the upload abort action.\n\n## Uploading and disabled states\n\n`isUploading` marks the root busy and makes selection and removal unavailable. Controls that were available stay focusable, so keyboard focus is not lost when an upload starts. Supply `onAbort` to replace Upload with Abort during an upload. Abort works before the first image URL exists. The application owns cancellation and sets `isUploading` back to `false` when the upload ends.\n\n`disabled` disables every action. Selection requires `onFileSelect`. Removal requires both `onRemove` and a nonempty `src`.\n\n<StoryEmbed\n storyId=\"ui-input-imageinput--uploading\"\n title=\"Image upload with an abort action\"\n height={140}\n/>\n\n## Labels, instructions, and errors\n\nSupply localized `uploadLabel`, `removeLabel`, and `abortLabel` strings. They default to `Upload`, `Remove`, and `Abort`. The upload label also names the preview button and the hidden file input. Native accessible attributes can provide a different file input name. `aria-describedby` also describes the selection buttons and combines with the application's helper and error text.\n\n`helperText` and `errorMessage` belong to the application. Both describe the selection controls, and errors are announced as alerts. There are no built-in file limits or product instructions.\n\n<StoryEmbed\n storyId=\"ui-input-imageinput--with-error\"\n title=\"Image input with instructions and an error\"\n height={160}\n/>\n\n## Migration\n\nReplace `onUpload` with `onFileSelect`. Keep `accept` as a top-level prop. The callback still receives a `File`; keep existing validation and upload code in your application.\n\n```tsx\nimport { ImageInput } from 'twenty-ui/components/input';\n\nexport const WorkspaceImageSelector = ({\n uploadImage,\n}: {\n uploadImage: (file: File) => void;\n}) => <ImageInput onFileSelect={uploadImage} accept=\"image/png, image/jpeg\" />;\n```\n\n## Props\n\n<ImageInputReference />\n\n<PageBanner illustration=\"page-cover-image\" />\n","api":{"name":"ImageInput","entryPoint":"twenty-ui/components/input","slug":"components/input/image-input","props":[{"name":"abortLabel","type":"string","required":false,"defaultValue":"Abort","description":"Label for the Abort action."},{"name":"accept","type":"string","required":false,"defaultValue":"image/*","description":"Native file picker filter. Defaults to image/*. The caller validates allowed formats."},{"name":"aria-describedby","type":"string","required":false,"defaultValue":null,"description":"Accessible description references for the hidden file input and selection buttons, combined with helperText and errorMessage."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name of the hidden file input. Defaults to uploadLabel."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"Accessible name reference for the hidden file input."},{"name":"capture","type":"boolean | \"user\" | \"environment\"","required":false,"defaultValue":null,"description":"Native device capture hint for the file picker."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the root element."},{"name":"dir","type":"string","required":false,"defaultValue":null,"description":"Text direction applied to both the root and hidden file input."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables file selection, removal, and abort actions."},{"name":"errorMessage","type":"string | null","required":false,"defaultValue":null,"description":"Application error, displayed as an alert and associated with the selection controls."},{"name":"form","type":"string","required":false,"defaultValue":null,"description":"Native form identifier associated with the hidden file input."},{"name":"helperText","type":"string","required":false,"defaultValue":null,"description":"Application instructions, associated with the selection controls."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Native identifier of the hidden file input."},{"name":"inputRef","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the hidden single-file HTMLInputElement."},{"name":"isUploading","type":"boolean","required":false,"defaultValue":"false","description":"Marks the module busy. Selection and removal controls that would otherwise be enabled stay focusable but unavailable. Shows Abort when onAbort is supplied."},{"name":"name","type":"string","required":false,"defaultValue":null,"description":"Native name of the hidden file input."},{"name":"onAbort","type":"(() => void)","required":false,"defaultValue":null,"description":"Shows an abort action while uploading. It can cancel the first upload before a src exists."},{"name":"onChange","type":"ChangeEventHandler<HTMLInputElement, HTMLInputElement>","required":false,"defaultValue":null,"description":"Native file input change event, fired while the selected file is present and before the input resets. The input does not retain a file for form submission."},{"name":"onFileSelect","type":"((file: File) => void)","required":false,"defaultValue":null,"description":"Fires when a file is selected and receives its usable File after the input resets. Empty and canceled selections do not call it. Selection is disabled when omitted. The caller owns validation and uploading."},{"name":"onRemove","type":"(() => void)","required":false,"defaultValue":null,"description":"Requests removal of the current image. Removal is disabled without this callback or a nonempty src."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root div element."},{"name":"removeLabel","type":"string","required":false,"defaultValue":"Remove","description":"Label for the Remove action."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Custom root element or render function. Supply root native attributes here and keep a non-interactive root."},{"name":"required","type":"boolean","required":false,"defaultValue":null,"description":"Native file input requirement. The input resets after selection, so the caller validates completed uploads."},{"name":"src","type":"string | null","required":false,"defaultValue":null,"description":"Resolved image URL. Empty or failed images show the image placeholder."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline style applied to the root element."},{"name":"title","type":"string","required":false,"defaultValue":null,"description":"Native title of the hidden file input."},{"name":"uploadLabel","type":"string","required":false,"defaultValue":"Upload","description":"Label for the preview, Upload action, and hidden file input."}]}},{"name":"DatePicker","entryPoint":"twenty-ui/components/input","content":"---\ntitle: DatePicker\ndescription: Share the existing calendar engine while browsing months independently from the selected date.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport DatePickerReference from '/snippets/ui/generated/components/input/date-picker.mdx';\n\n## Overview\n\n`DatePicker` shares the `react-datepicker` calendar engine used by Twenty's date and date-time inputs. It provides date-only values and independent control over the selected date and viewed month.\n\n<StoryEmbed\n storyId=\"ui-components-datepicker--display\"\n title=\"DatePicker example\"\n height={330}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { DatePicker } from 'twenty-ui/components/input';\n\nexport const ChooseDate = () => {\n const [value, setValue] = useState<string | null>('2026-10-07');\n const [viewedMonth, setViewedMonth] = useState('2026-10');\n\n return (\n <DatePicker\n aria-label=\"Choose a date\"\n value={value}\n onValueChange={setValue}\n viewedMonth={viewedMonth}\n onViewedMonthChange={setViewedMonth}\n weekStart={1}\n weekdayLabels={['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']}\n locale=\"en-US\"\n previousMonthLabel=\"Previous month\"\n nextMonthLabel=\"Next month\"\n monthLabel=\"Month\"\n yearLabel=\"Year\"\n />\n );\n};\n```\n\n## Selection and browsing\n\nChanging the month or year calls `onViewedMonthChange` and leaves `value` unchanged. Choosing an available day calls `onValueChange` when the selected date changes.\n\nUse `onValueSelect` to commit a date or close a product picker. It receives the canonical `YYYY-MM-DD` date even when the user chooses the already-selected day. Keep closing behavior in the application adapter.\n\nUpdate each controlled prop in its matching callback. Prop changes do not select a replacement date. The default header provides month and year selectors and previous and next buttons; its year selector lists up to 100 years before and after the viewed year.\n\n## Date values and localization\n\nPass canonical Gregorian date-only strings: `YYYY-MM-DD` for `value` and highlighted range bounds, and `YYYY-MM` for `viewedMonth`. Set `value={null}` for no selection. These values contain no time or timezone. Supported years are 0001 through 9999.\n\n`locale` formats the default month/year header and full weekday titles when custom `weekdayLabels` are supplied. Day labels and the underlying calendar retain the existing `react-datepicker` locale behavior.\n\n`weekStart` sets the first column, using 0 for Sunday through 6 for Saturday. Use `weekdayLabels` for seven short visible labels in Sunday-first order, regardless of `weekStart`. The calendar engine supplies weekday names when this prop is omitted.\n\nCurrent-day presentation follows the calendar engine's browser-clock behavior. Product adapters own timezone conversion, initial date fallbacks, member preferences, and scheduling data.\n\n## Existing calendar behavior\n\nDay rendering, accessibility markup, keyboard date navigation, and unavailable-date handling use `react-datepicker`. Visible days from neighboring months remain selectable when available.\n\nSet `isDateUnavailable` to prevent selection of dates according to your application's policy. The callback receives a canonical `YYYY-MM-DD` string. Set `disabled` to disable date selection and the default header controls.\n\n`isKeyboardNavigationDisabled` defaults to `false`. Existing product input adapters can set it to preserve their keyboard behavior. Header controls keep their native keyboard interaction.\n\n## Highlighted ranges and read-only views\n\nPass `highlightedRange={{ start: '2026-10-05', end: '2026-10-11' }}` to highlight an inclusive date range. The application computes the range; highlighting does not select multiple dates or change `value`.\n\nUse `readOnly` to display a computed range or selected date while allowing month and year browsing. Use `isGridHidden` for a month-only navigator that retains the same header.\n\n## Custom headers\n\nUse `renderHeader` to compose an existing product header with date inputs, time inputs, or application-specific controls. Its `DatePickerHeaderProps` argument provides these values and actions:\n\n| Property | Purpose |\n| --- | --- |\n| `viewedMonth` | Current `YYYY-MM` month. |\n| `onPreviousMonth`, `onNextMonth` | Browse to the adjacent month. |\n| `onMonthChange` | Browse to a month number from 1 through 12. |\n| `onYearChange` | Browse to the supplied year. |\n| `isPreviousMonthDisabled`, `isNextMonthDisabled` | Whether each adjacent-month action is unavailable. |\n\nThese header actions change the viewed month and leave the selected date unchanged.\n\n```tsx\nimport { useState } from 'react';\nimport { DatePicker } from 'twenty-ui/components/input';\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const CalendarWithProductHeader = () => {\n const [value, setValue] = useState<string | null>('2026-10-07');\n const [viewedMonth, setViewedMonth] = useState('2026-10');\n\n return (\n <DatePicker\n aria-label=\"Choose a date\"\n value={value}\n onValueChange={setValue}\n viewedMonth={viewedMonth}\n onViewedMonthChange={setViewedMonth}\n weekStart={1}\n locale=\"en-US\"\n previousMonthLabel=\"Previous month\"\n nextMonthLabel=\"Next month\"\n monthLabel=\"Month\"\n yearLabel=\"Year\"\n renderHeader={({\n viewedMonth: month,\n onPreviousMonth,\n onNextMonth,\n isPreviousMonthDisabled,\n isNextMonthDisabled,\n }) => (\n <Text\n style={{\n display: 'flex',\n alignItems: 'center',\n gap: themeCssVariables.spacing[2],\n }}\n >\n <Button size=\"sm\" disabled={isPreviousMonthDisabled} onClick={onPreviousMonth}>\n Previous month\n </Button>\n <Text>{month}</Text>\n <Button size=\"sm\" disabled={isNextMonthDisabled} onClick={onNextMonth}>\n Next month\n </Button>\n </Text>\n )}\n />\n );\n};\n```\n\n## Composition and product adapters\n\nSupply a group name with `aria-label` or `aria-labelledby`. Native attributes, `className`, `style`, and `ref` apply to the root. Use `render` to compose a different root while preserving the supplied props and ref.\n\nPass `loadingFallback` to preserve a product loading surface while the calendar engine loads. The default fallback is a 300px-high `Skeleton`.\n\nFor the default header, `portalContainer` mounts selector popups in a host-provided container. `onNavigationOpenChange` receives `{ open, control }` for `month` or `year`, with `open: true` when opening starts and `open: false` after closing completes. Hosts can retain their popup and focus handling through dismissal. Custom headers own their popup integration.\n\nKeep product headers, text inputs, time editing, timezone conversion, clear actions, and relative-filter computation in `twenty-front`. Date, date-time, and month-only adapters can compose this shared calendar engine with `highlightedRange`, `readOnly`, and `isGridHidden` as needed.\n\n## Props\n\n<DatePickerReference />\n\n<PageBanner illustration=\"calendar-emails\" />\n","api":{"name":"DatePicker","entryPoint":"twenty-ui/components/input","slug":"components/input/date-picker","props":[{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name of the calendar group."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element that labels the calendar group."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the root element."},{"name":"disabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables date selection and the default header controls."},{"name":"highlightedRange","type":"{ start: string; end: string; }","required":false,"defaultValue":null,"description":"Inclusive YYYY-MM-DD start and end dates to highlight. The application computes the range independently from the selected date."},{"name":"isDateUnavailable","type":"((date: string) => boolean)","required":false,"defaultValue":null,"description":"Returns whether a canonical YYYY-MM-DD date cannot be selected. The calendar engine handles unavailable-date presentation and navigation."},{"name":"isGridHidden","type":"boolean","required":false,"defaultValue":"false","description":"Hides weekday and date rows while retaining the header for a month-only navigator."},{"name":"isKeyboardNavigationDisabled","type":"boolean","required":false,"defaultValue":"false","description":"Disables keyboard date navigation in the calendar engine for compatibility with existing input wrappers. Header controls retain their native keyboard behavior."},{"name":"loadingFallback","type":"ReactNode","required":false,"defaultValue":"300px-high Skeleton","description":"Custom Suspense fallback while the calendar engine loads. Defaults to a 300px-high Skeleton."},{"name":"locale","type":"string","required":true,"defaultValue":null,"description":"Locale for the default month/year header and custom weekday titles. Engine day labels retain their existing locale behavior; values remain Gregorian date-only strings."},{"name":"monthLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default month selector."},{"name":"nextMonthLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default next-month button."},{"name":"onNavigationOpenChange","type":"((args: { open: boolean; control: \"month\" | \"year\"; }) => void)","required":false,"defaultValue":null,"description":"Reports { open, control } when a default month or year popup starts opening, and when it finishes closing or its selector unmounts. Header arrow actions do not call this callback."},{"name":"onValueChange","type":"(date: string) => void","required":true,"defaultValue":null,"description":"Called when choosing an available day changes the selected date. Month and year browsing does not select another date."},{"name":"onValueSelect","type":"((date: string) => void)","required":false,"defaultValue":null,"description":"Called with the selected YYYY-MM-DD date after choosing an available day, including the already-selected day. Use it to commit or close a product picker."},{"name":"onViewedMonthChange","type":"(month: string) => void","required":true,"defaultValue":null,"description":"Requests the month shown by calendar navigation without changing the selected date."},{"name":"portalContainer","type":"HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null","required":false,"defaultValue":null,"description":"Mount container for the default month and year selector popups. Accepts the shared Select portal container contract."},{"name":"previousMonthLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default previous-month button."},{"name":"readOnly","type":"boolean","required":false,"defaultValue":"false","description":"Prevents date selection while allowing month and year browsing and displaying the selected date or highlighted range."},{"name":"ref","type":"Ref<HTMLDivElement>","required":false,"defaultValue":null,"description":"Ref to the root element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Composes the root element while preserving its props and contents."},{"name":"renderHeader","type":"((props: DatePickerHeaderProps) => ReactNode)","required":false,"defaultValue":null,"description":"Renders a product header with the viewed month, previous/next actions, month numbers from 1 through 12, year change actions, and navigation-disabled states. Header actions only browse months."},{"name":"role","type":"AriaRole","required":false,"defaultValue":"group","description":"Root semantics. Defaults to a group; the caller supplies its accessible name."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root element."},{"name":"value","type":"string | null","required":true,"defaultValue":null,"description":"Controlled selected Gregorian date in YYYY-MM-DD form, or null for no selection."},{"name":"viewedMonth","type":"string","required":true,"defaultValue":null,"description":"Controlled Gregorian month in YYYY-MM form. It is independent from the selected date."},{"name":"weekdayLabels","type":"readonly [string, string, string, string, string, string, string]","required":false,"defaultValue":null,"description":"Optional short weekday labels in Sunday-first order. The calendar engine supplies weekday names when omitted."},{"name":"weekStart","type":"0 | 1 | 2 | 3 | 4 | 5 | 6","required":true,"defaultValue":null,"description":"First weekday column: 0 for Sunday through 6 for Saturday."},{"name":"yearLabel","type":"string","required":true,"defaultValue":null,"description":"Accessible name of the default year selector."}]}},{"name":"SearchInput","entryPoint":"twenty-ui/components/input","content":"---\ntitle: SearchInput\ndescription: Controlled search text with optional actions, such as a filter popup.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport SearchInputReference from '/snippets/ui/generated/components/input/search-input.mdx';\n\n## Overview\n\n`SearchInput` supplies a search icon and text input. `onValueChange` receives the new string; `onChange` receives the native React change event. Filtering, fetching, and debouncing belong to your application.\n\n<StoryEmbed\n storyId=\"ui-input-searchinput--display\"\n title=\"SearchInput example\"\n height={110}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { SearchInput } from 'twenty-ui/components/input';\n\nexport const RecordSearch = () => {\n const [value, setValue] = useState('');\n\n return (\n <SearchInput\n value={value}\n onValueChange={setValue}\n placeholder=\"Search...\"\n />\n );\n};\n```\n\nUse `aria-label` or `aria-labelledby` for an accessible name.\n\nNative input props, `className`, `style`, and `ref` apply to the input itself. The shared `InputGroup` owns the search adornment and focus treatment. The wrapper that lays out the field and its actions takes no props; place `SearchInput` in your own container to size or position it. Use `size=\"sm\"` for a compact search field.\n\n## Actions\n\n`actions` renders controls after the search field. Compose a filter popup with a [Dropdown](/ui/components/navigation/dropdown) whose trigger is an `IconButton`, and give that button an accessible name.\n\n```tsx\nimport { useState } from 'react';\nimport { IconButton, SearchInput } from 'twenty-ui/components/input';\nimport { Dropdown } from 'twenty-ui/components/navigation';\nimport { SettingsRow } from 'twenty-ui/components/settings';\nimport { IconFilter } from 'twenty-ui/icon';\n\nexport const FilteredPeopleSearch = () => {\n const [search, setSearch] = useState('');\n const [includeInactive, setIncludeInactive] = useState(false);\n\n return (\n <SearchInput\n aria-label=\"Search people\"\n placeholder=\"Name or email\"\n value={search}\n onValueChange={setSearch}\n actions={\n <Dropdown.Root type=\"panel\">\n <Dropdown.Trigger\n render={\n <IconButton aria-label=\"Filter people\">\n <IconFilter />\n </IconButton>\n }\n />\n <Dropdown.Content align=\"end\">\n <Dropdown.Section>\n <SettingsRow\n checked={includeInactive}\n onCheckedChange={setIncludeInactive}\n >\n Include inactive people\n </SettingsRow>\n </Dropdown.Section>\n </Dropdown.Content>\n </Dropdown.Root>\n }\n />\n );\n};\n```\n\n`disabled` disables only the text input; disable action controls separately. With `size=\"sm\"`, pass `size=\"sm\"` to the action controls as well.\n\n<StoryEmbed\n storyId=\"ui-input-searchinput--with-filter\"\n title=\"SearchInput with a filter popup\"\n height={320}\n/>\n\n## Props\n\n<SearchInputReference />\n\n<PageBanner illustration=\"page-cover-search\" />\n","api":{"name":"SearchInput","entryPoint":"twenty-ui/components/input","slug":"components/input/search-input","props":[{"name":"actions","type":"ReactNode","required":false,"defaultValue":null,"description":"Controls rendered after the search field, such as a filter Dropdown. Set their size and accessible names on the controls."},{"name":"aria-label","type":"string","required":false,"defaultValue":null,"description":"Accessible name when aria-labelledby is absent."},{"name":"aria-labelledby","type":"string","required":false,"defaultValue":null,"description":"ID of the element that labels the input. Takes precedence over aria-label."},{"name":"autoFocus","type":"boolean","required":false,"defaultValue":null,"description":"Focuses the input when mounted."},{"name":"className","type":"string | ((state: InputState) => string | undefined)","required":false,"defaultValue":null,"description":"Class applied to the input."},{"name":"defaultValue","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"The default value of the input. Use when uncontrolled."},{"name":"disabled","type":"boolean","required":false,"defaultValue":null,"description":"Disables the text input. Controls in actions keep their own state."},{"name":"hasFocusRing","type":"boolean","required":false,"defaultValue":"false","description":"Shows the group focus border. Defaults to false for all search inputs. Set true to opt in. Error styling remains visible."},{"name":"id","type":"string","required":false,"defaultValue":null,"description":"Input ID, generated when omitted."},{"name":"onChange","type":"((event: BaseUIEvent<ChangeEvent<HTMLInputElement, HTMLInputElement>>) => void)","required":false,"defaultValue":null,"description":"Native input change event handler."},{"name":"onValueChange","type":"((value: string, eventDetails: { reason: \"none\"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)","required":false,"defaultValue":null,"description":"Called with the new text. The application owns filtering."},{"name":"placeholder","type":"string","required":false,"defaultValue":null,"description":"Hint shown when the input is empty. Also used as the accessible name if no explicit label is supplied."},{"name":"ref","type":"Ref<HTMLInputElement>","required":false,"defaultValue":null,"description":"Ref to the native input element."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, InputState>","required":false,"defaultValue":null,"description":"Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."},{"name":"size","type":"\"md\" | \"sm\"","required":false,"defaultValue":"md","description":"Visual size of the input group."},{"name":"style","type":"CSSProperties | ((state: InputState) => CSSProperties | undefined)","required":false,"defaultValue":null,"description":"Style applied to the element, or a function that\nreturns a style object based on the component's state."},{"name":"textAlign","type":"\"end\" | \"start\"","required":false,"defaultValue":null,"description":"Aligns text to the logical start or end of the input. Follows the text direction."},{"name":"value","type":"string | number | readonly string[]","required":false,"defaultValue":null,"description":"Current search text."}]}},{"name":"AnimatedIconCrossfade","entryPoint":"twenty-ui/components/layout","content":"---\ntitle: AnimatedIconCrossfade\ndescription: Crossfade between two icons as application state changes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';\nimport AnimatedIconCrossfadeReference from '/snippets/ui/generated/components/layout/animated-icon-crossfade.mdx';\n\n## Overview\n\n`AnimatedIconCrossfade` crossfades between `activeIcon` and `inactiveIcon` node content according to `isActive`. It does not own the action or state. Compose it inside a labeled [Button](/ui/primitives/input/button).\n\n<StoryEmbed\n storyId=\"ui-components-layout-animatediconcrossfade--display\"\n title=\"AnimatedIconCrossfade example\"\n height={100}\n/>\n\n## Usage\n\n```tsx\nimport { useState } from 'react';\nimport { AnimatedIconCrossfade } from 'twenty-ui/components/layout';\nimport { IconPencil, IconX } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const EditToggle = () => {\n const [isEditing, setIsEditing] = useState(false);\n\n return (\n <Button\n size=\"sm\"\n aria-expanded={isEditing}\n onClick={() => setIsEditing(!isEditing)}\n startIcon={\n <AnimatedIconCrossfade\n isActive={isEditing}\n activeIcon={<IconX size={14} />}\n inactiveIcon={<IconPencil size={14} />}\n />\n }\n >\n Edit actions\n </Button>\n );\n};\n```\n\nBoth nodes stay mounted as `isActive` changes, preserving their local state. The layers animate opacity and scale, and disable transitions for reduced motion. Both layers are decorative; keep the accessible action name on the surrounding control. For a standalone labeled image, set `role=\"img\"` and `aria-label` on the root.\n\nNative attributes, events, `className`, `style`, and `ref` target an inline span, which can sit inside a button. `render` replaces that target through Base UI composition. The root dimensions default to the small icon theme token. Size each icon node explicitly, and use root width and height styles for larger artwork.\n\nReplace `ActiveIcon` and `InactiveIcon` constructors with lowercase `activeIcon` and `inactiveIcon` nodes. Move the former `size` option to the node dimensions and root styles.\n\n## Props\n\n<AnimatedIconCrossfadeReference />\n\n<PageBanner illustration=\"card-page-sync-recovery\" />\n","api":{"name":"AnimatedIconCrossfade","entryPoint":"twenty-ui/components/layout","slug":"components/layout/animated-icon-crossfade","props":[{"name":"activeIcon","type":"ReactNode","required":true,"defaultValue":null,"description":"Decorative node content for the active state."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"CSS class applied to the inline span root."},{"name":"inactiveIcon","type":"ReactNode","required":true,"defaultValue":null,"description":"Decorative node content for the inactive state."},{"name":"isActive","type":"boolean","required":true,"defaultValue":null,"description":"Shows activeIcon when true and inactiveIcon otherwise."},{"name":"render","type":"ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>","required":false,"defaultValue":null,"description":"Replaces the span root while preserving both transition layers."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Inline styles applied to the root, including width and height."}]}},{"name":"ThemeProvider","entryPoint":"twenty-ui/theme","content":"---\ntitle: Theming\ndescription: Use Twenty UI theme tokens and scope theme overrides to part of your application.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ThemeProviderReference from '/snippets/ui/generated/theme/theme-provider.mdx';\n\n## Overview\n\nTwenty UI components read public CSS custom properties prefixed with `--t-`. Prefer semantic tokens such as `background.secondary` and `font.color.primary` when styling your own components; these values adapt to the active palette.\n\n## Use tokens in styles\n\n`themeCssVariables` maps token paths to CSS variable references. Use it for values that CSS resolves:\n\n```tsx\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const Summary = () => (\n <section\n style={{\n background: themeCssVariables.background.secondary,\n color: themeCssVariables.font.color.primary,\n padding: themeCssVariables.spacing[4],\n borderRadius: themeCssVariables.border.radius.md,\n }}\n >\n Three tasks are due today.\n </section>\n);\n```\n\nThe equivalent CSS uses variables directly:\n\n```css\n.summary {\n background: var(--t-background-secondary);\n color: var(--t-font-color-primary);\n padding: var(--t-spacing-4);\n border-radius: var(--t-border-radius-md);\n}\n```\n\n## Read resolved values\n\n`useTheme()` reads the active provider's computed tokens. Use it when a component expects a JavaScript number, such as an icon size. The provider needs the theme stylesheet to be loaded in the browser to resolve CSS variables.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { useTheme } from 'twenty-ui/theme';\n\nexport const CompleteIcon = () => {\n const theme = useTheme();\n\n return <IconCheck size={theme.icon.size.md} aria-hidden />;\n};\n```\n\nEvery entry in `themeCssVariables` is a CSS reference string, including numeric tokens. Do not perform arithmetic on those strings. On the server, resolved browser values are unavailable; see [Server rendering](/ui/ssr).\n\n## Scope an override\n\nPass `applyToRoot={false}` to apply a theme to a subtree. Override public CSS variables by their full name:\n\n```tsx\nimport { type ReactNode } from 'react';\nimport { ThemeProvider } from 'twenty-ui/theme';\n\nexport const EmbeddedPanel = ({ children }: { children: ReactNode }) => (\n <ThemeProvider\n colorScheme=\"light\"\n applyToRoot={false}\n overrides={{ '--t-background-secondary': '#f4f6ff' }}\n >\n {children}\n </ThemeProvider>\n);\n```\n\nA scoped provider adds a wrapper with `display: contents`; it does not create a layout box. It also supplies a container for components that support themed portals. Portals created by other libraries need their own container configuration.\n\nVariables prefixed with `--tw-` are private component details. Use public props and `--t-` tokens instead of depending on those variables.\n\nSee the [token reference](/ui/tokens) for the available names and palette values.\n\n## Explicit values and scale\n\nThe `theme` prop supplies resolved JavaScript theme values instead of reading computed styles. It also flows to nested providers unless they supply another explicit theme. This changes values read by hooks; load the appropriate stylesheet and use CSS overrides to style components.\n\n`scale` writes `--t-scale-user` on the document root. It only affects interfaces whose CSS consumes that variable and is ignored by scoped providers. `className` applies to a scoped wrapper; passing it alone does not create a wrapper. `overrides` creates a scope even when `applyToRoot` remains true.\n\n## ThemeProvider props\n\n<ThemeProviderReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n","api":{"name":"ThemeProvider","entryPoint":"twenty-ui/theme","slug":"theme/theme-provider","props":[{"name":"applyToRoot","type":"boolean","required":false,"defaultValue":"true","description":"Applies the color-scheme class to the document root. Set false for a scoped wrapper."},{"name":"children","type":"ReactNode","required":true,"defaultValue":null,"description":"Components that share this theme."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to a scoped wrapper; no wrapper is created for className alone."},{"name":"colorScheme","type":"\"dark\" | \"light\"","required":true,"defaultValue":null,"description":"Explicit light or dark palette; load its stylesheet before rendering."},{"name":"overrides","type":"ThemeOverrides","required":false,"defaultValue":null,"description":"CSS custom-property overrides. Supplying them creates a scoped wrapper."},{"name":"scale","type":"number","required":false,"defaultValue":null,"description":"Root interface scale stored in --t-scale-user. Ignored for scoped providers; application CSS must consume the variable."},{"name":"theme","type":"ThemeType | typeof THEME_LIGHT","required":false,"defaultValue":null,"description":"Explicit resolved theme values, bypassing computed-style token resolution."}]}},{"name":"Icon","entryPoint":"twenty-ui/icon/provider","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"Icon","entryPoint":"twenty-ui/icon/provider","slug":"icon/icon","props":[{"name":"aria-hidden","type":"boolean","required":false,"defaultValue":null,"description":"Hides a decorative icon from assistive technology."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class forwarded to the resolved icon."},{"name":"color","type":"string","required":false,"defaultValue":null,"description":"Color forwarded to the resolved icon."},{"name":"name","type":"string","required":true,"defaultValue":null,"description":"Icon name resolved through IconsProvider. Unknown names fall back to Icon123."},{"name":"size","type":"string | number","required":false,"defaultValue":null,"description":"Width and height forwarded to the resolved icon."},{"name":"stroke","type":"string | number","required":false,"defaultValue":null,"description":"Stroke width forwarded to the resolved icon."},{"name":"style","type":"CSSProperties","required":false,"defaultValue":null,"description":"Styles forwarded to the resolved icon."}]}},{"name":"IconsProvider","entryPoint":"twenty-ui/icon/provider","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"IconsProvider","entryPoint":"twenty-ui/icon/provider","slug":"icon/icons-provider","props":[{"name":"children","type":"Element","required":true,"defaultValue":null,"description":"One React element containing consumers of Icon or useIcons. Loads the complete icon map asynchronously."}]}},{"name":"IllustrationIconWrapper","entryPoint":"twenty-ui/icon","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"IllustrationIconWrapper","entryPoint":"twenty-ui/icon","slug":"icon/illustration-icon-wrapper","props":[{"name":"children","type":"ReactNode","required":false,"defaultValue":null,"description":"Illustration content to center inside the wrapper."},{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class merged with the illustration wrapper styling."}]}},{"name":"ThinkingOrbitLoaderIcon","entryPoint":"twenty-ui/icon","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n","api":{"name":"ThinkingOrbitLoaderIcon","entryPoint":"twenty-ui/icon","slug":"icon/thinking-orbit-loader-icon","props":[{"name":"className","type":"string","required":false,"defaultValue":null,"description":"Class applied to the SVG. The icon is always hidden from assistive technology."},{"name":"size","type":"string | number","required":false,"defaultValue":"14","description":"Width and height in pixels."}]}},{"name":"ComponentStorybookLayout","entryPoint":"twenty-ui/testing","content":"---\ntitle: Storybook helpers\ndescription: Present component previews and variant catalogs with twenty-ui/testing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ComponentStorybookLayoutReference from '/snippets/ui/generated/testing/component-storybook-layout.mdx';\nimport GroupedCatalogReference from '/snippets/ui/generated/testing/grouped-catalog.mdx';\n\n## Overview\n\n`twenty-ui/testing` exposes Storybook decorators, preview layout helpers, and media-query overrides. Configure styles and a [ThemeProvider](/ui/theming) in your Storybook preview before rendering themed components.\n\n## Story roles\n\nStart each component guide with a `Display` story showing one representative, usable example. Follow it with Usage code that reproduces the preview using public imports. Compound components demonstrate their parts together. Providers and accessibility helpers demonstrate their effect in context.\n\nAdd a `Catalog` when a labeled comparison helps readers choose between visual options. Group variants, sizes, colors, and states separately; use a matrix only when comparing two dimensions together is useful. A simple component can use one alternative example. Dialogs, menus, and other interactive components usually need focused examples for each workflow.\n\nPreserve comprehensive screenshot coverage in separate `VisualRegression` stories, including dark themes and variant matrices. Tag those stories with `!autodocs` and keep them out of the component guides.\n\nName other stories after what they demonstrate, such as `Controlled`, `WithValidation`, or `MultipleSelection`. Keep interaction checks in separate stories with `play` functions. The display and other documentation previews remain usable by the reader without automated actions.\n\n## ComponentDecorator\n\n`ComponentDecorator` wraps a story in `ComponentStorybookLayout`. Set `parameters.container.width` and `parameters.container.height` in pixels. It also reads the story's `inverted` and `accent` args to choose an optional background.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentDecorator } from 'twenty-ui/testing';\n\nconst meta = {\n component: Button,\n decorators: [ComponentDecorator],\n parameters: { container: { width: 240, height: 100 } },\n};\n\nexport default meta;\n\nexport const Display = { args: { children: 'Save changes' } };\n```\n\n## GroupedCatalog\n\n`GroupedCatalog` gives curated catalogs a shared layout for headings, wrapping rows, and spacing. Each group has a `label` and an `examples` array. Every example needs a unique `label` within its group; it can carry any other data used by `renderExample`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { GroupedCatalog } from 'twenty-ui/testing';\n\nconst groups = [\n {\n label: 'Variants',\n examples: [\n { label: 'Solid', variant: 'solid' as const },\n { label: 'Outline', variant: 'outline' as const },\n ],\n },\n];\n\nexport const ButtonCatalog = () => (\n <GroupedCatalog\n groups={groups}\n renderExample={({ label, variant }) => (\n <>\n <Text>{label}</Text>\n <Button variant={variant}>Save changes</Button>\n </>\n )}\n />\n);\n```\n\n<GroupedCatalogReference />\n\n## CatalogDecorator\n\n`CatalogDecorator` renders combinations of up to four dimensions from `parameters.catalog.dimensions`. Each dimension has a `name`, `values`, a `props(value)` mapper, and an optional `labels(value)` formatter. The mapper returns the props for that cell. `parameters.catalog.options.elementContainer` accepts `width`, `style`, and `className`.\n\n```tsx\nimport { Button, type ButtonVariant } from 'twenty-ui/primitives/input';\nimport { CatalogDecorator } from 'twenty-ui/testing';\n\nconst meta = { component: Button };\nexport default meta;\n\nexport const VisualRegression = {\n tags: ['!autodocs'],\n args: { children: 'Save changes' },\n decorators: [CatalogDecorator],\n parameters: {\n catalog: {\n dimensions: [\n {\n name: 'variant',\n values: ['outline', 'solid', 'ghost'],\n props: (variant: ButtonVariant) => ({ variant }),\n },\n ],\n },\n },\n};\n```\n\n## ComponentStorybookLayout\n\nUse the layout directly when composing a preview outside a decorator. It accepts one child element.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentStorybookLayout } from 'twenty-ui/testing';\n\nexport const ButtonPreview = () => (\n <ComponentStorybookLayout width={240} height={100}>\n <Button>Save changes</Button>\n </ComponentStorybookLayout>\n);\n```\n\n<ComponentStorybookLayoutReference />\n\n## Media query overrides\n\nUse `overrideMediaQueryMatches` in a story's `beforeEach` to force responsive hook results. Return its cleanup function to restore `window.matchMedia` after the story:\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { overrideMediaQueryMatches } from 'twenty-ui/testing';\nimport { MOBILE_MEDIA_QUERY, useIsMobile } from 'twenty-ui/utilities';\n\nconst ResponsiveAction = () => {\n const isMobile = useIsMobile();\n\n return <Button fullWidth={isMobile}>Save changes</Button>;\n};\n\nconst meta = { component: ResponsiveAction };\nexport default meta;\n\nexport const Mobile = {\n beforeEach: () => overrideMediaQueryMatches({ [MOBILE_MEDIA_QUERY]: true }),\n};\n```\n\nQueries omitted from the override retain their native behavior. Override `TOUCH_DEVICE_MEDIA_QUERY` separately when an example depends on touch input. These overrides control `matchMedia` results; use a Storybook viewport to change CSS media queries and the preview width.\n\n## Documentation previews\n\nStories embedded in the documentation must be presentational and have no `play` function. Keep interaction tests in separate stories. Share explicit `args`, `render`, `decorators`, and `parameters` when needed, rather than spreading an interaction story into a preview. The documentation embed check rejects stories marked with Storybook's `play-fn` tag, including inherited play functions.\n\nEach component guide's first embed must reference a story exported as `Display`. Give every embed a descriptive title for its iframe and enough height to show the example. The shared preview supplies light and dark tabs and a link to Storybook, where readers can use controls to explore props.\n\nRun `npx nx check:ui-stories twenty-docs` to check the required display, preview titles, references, and presentation rules. Run `npx nx check:ui twenty-docs` to validate the generated API references and typecheck copyable examples.\n\n<PageBanner illustration=\"card-page-testing\" />\n","api":{"name":"ComponentStorybookLayout","entryPoint":"twenty-ui/testing","slug":"testing/component-storybook-layout","props":[{"name":"backgroundColor","type":"string","required":false,"defaultValue":null,"description":"Background color override."},{"name":"children","type":"Element","required":true,"defaultValue":null,"description":"The component preview element."},{"name":"height","type":"number","required":false,"defaultValue":null,"description":"Container height in pixels. Defaults to fit-content."},{"name":"width","type":"number","required":false,"defaultValue":null,"description":"Container width in pixels. When omitted, the container has a 300px minimum width."}]}},{"name":"GroupedCatalog","entryPoint":"twenty-ui/testing","content":"---\ntitle: Storybook helpers\ndescription: Present component previews and variant catalogs with twenty-ui/testing.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ComponentStorybookLayoutReference from '/snippets/ui/generated/testing/component-storybook-layout.mdx';\nimport GroupedCatalogReference from '/snippets/ui/generated/testing/grouped-catalog.mdx';\n\n## Overview\n\n`twenty-ui/testing` exposes Storybook decorators, preview layout helpers, and media-query overrides. Configure styles and a [ThemeProvider](/ui/theming) in your Storybook preview before rendering themed components.\n\n## Story roles\n\nStart each component guide with a `Display` story showing one representative, usable example. Follow it with Usage code that reproduces the preview using public imports. Compound components demonstrate their parts together. Providers and accessibility helpers demonstrate their effect in context.\n\nAdd a `Catalog` when a labeled comparison helps readers choose between visual options. Group variants, sizes, colors, and states separately; use a matrix only when comparing two dimensions together is useful. A simple component can use one alternative example. Dialogs, menus, and other interactive components usually need focused examples for each workflow.\n\nPreserve comprehensive screenshot coverage in separate `VisualRegression` stories, including dark themes and variant matrices. Tag those stories with `!autodocs` and keep them out of the component guides.\n\nName other stories after what they demonstrate, such as `Controlled`, `WithValidation`, or `MultipleSelection`. Keep interaction checks in separate stories with `play` functions. The display and other documentation previews remain usable by the reader without automated actions.\n\n## ComponentDecorator\n\n`ComponentDecorator` wraps a story in `ComponentStorybookLayout`. Set `parameters.container.width` and `parameters.container.height` in pixels. It also reads the story's `inverted` and `accent` args to choose an optional background.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentDecorator } from 'twenty-ui/testing';\n\nconst meta = {\n component: Button,\n decorators: [ComponentDecorator],\n parameters: { container: { width: 240, height: 100 } },\n};\n\nexport default meta;\n\nexport const Display = { args: { children: 'Save changes' } };\n```\n\n## GroupedCatalog\n\n`GroupedCatalog` gives curated catalogs a shared layout for headings, wrapping rows, and spacing. Each group has a `label` and an `examples` array. Every example needs a unique `label` within its group; it can carry any other data used by `renderExample`.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { Text } from 'twenty-ui/primitives/typography';\nimport { GroupedCatalog } from 'twenty-ui/testing';\n\nconst groups = [\n {\n label: 'Variants',\n examples: [\n { label: 'Solid', variant: 'solid' as const },\n { label: 'Outline', variant: 'outline' as const },\n ],\n },\n];\n\nexport const ButtonCatalog = () => (\n <GroupedCatalog\n groups={groups}\n renderExample={({ label, variant }) => (\n <>\n <Text>{label}</Text>\n <Button variant={variant}>Save changes</Button>\n </>\n )}\n />\n);\n```\n\n<GroupedCatalogReference />\n\n## CatalogDecorator\n\n`CatalogDecorator` renders combinations of up to four dimensions from `parameters.catalog.dimensions`. Each dimension has a `name`, `values`, a `props(value)` mapper, and an optional `labels(value)` formatter. The mapper returns the props for that cell. `parameters.catalog.options.elementContainer` accepts `width`, `style`, and `className`.\n\n```tsx\nimport { Button, type ButtonVariant } from 'twenty-ui/primitives/input';\nimport { CatalogDecorator } from 'twenty-ui/testing';\n\nconst meta = { component: Button };\nexport default meta;\n\nexport const VisualRegression = {\n tags: ['!autodocs'],\n args: { children: 'Save changes' },\n decorators: [CatalogDecorator],\n parameters: {\n catalog: {\n dimensions: [\n {\n name: 'variant',\n values: ['outline', 'solid', 'ghost'],\n props: (variant: ButtonVariant) => ({ variant }),\n },\n ],\n },\n },\n};\n```\n\n## ComponentStorybookLayout\n\nUse the layout directly when composing a preview outside a decorator. It accepts one child element.\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { ComponentStorybookLayout } from 'twenty-ui/testing';\n\nexport const ButtonPreview = () => (\n <ComponentStorybookLayout width={240} height={100}>\n <Button>Save changes</Button>\n </ComponentStorybookLayout>\n);\n```\n\n<ComponentStorybookLayoutReference />\n\n## Media query overrides\n\nUse `overrideMediaQueryMatches` in a story's `beforeEach` to force responsive hook results. Return its cleanup function to restore `window.matchMedia` after the story:\n\n```tsx\nimport { Button } from 'twenty-ui/primitives/input';\nimport { overrideMediaQueryMatches } from 'twenty-ui/testing';\nimport { MOBILE_MEDIA_QUERY, useIsMobile } from 'twenty-ui/utilities';\n\nconst ResponsiveAction = () => {\n const isMobile = useIsMobile();\n\n return <Button fullWidth={isMobile}>Save changes</Button>;\n};\n\nconst meta = { component: ResponsiveAction };\nexport default meta;\n\nexport const Mobile = {\n beforeEach: () => overrideMediaQueryMatches({ [MOBILE_MEDIA_QUERY]: true }),\n};\n```\n\nQueries omitted from the override retain their native behavior. Override `TOUCH_DEVICE_MEDIA_QUERY` separately when an example depends on touch input. These overrides control `matchMedia` results; use a Storybook viewport to change CSS media queries and the preview width.\n\n## Documentation previews\n\nStories embedded in the documentation must be presentational and have no `play` function. Keep interaction tests in separate stories. Share explicit `args`, `render`, `decorators`, and `parameters` when needed, rather than spreading an interaction story into a preview. The documentation embed check rejects stories marked with Storybook's `play-fn` tag, including inherited play functions.\n\nEach component guide's first embed must reference a story exported as `Display`. Give every embed a descriptive title for its iframe and enough height to show the example. The shared preview supplies light and dark tabs and a link to Storybook, where readers can use controls to explore props.\n\nRun `npx nx check:ui-stories twenty-docs` to check the required display, preview titles, references, and presentation rules. Run `npx nx check:ui twenty-docs` to validate the generated API references and typecheck copyable examples.\n\n<PageBanner illustration=\"card-page-testing\" />\n","api":{"name":"GroupedCatalog","entryPoint":"twenty-ui/testing","slug":"testing/grouped-catalog","props":[{"name":"groups","type":"{ label: string; examples: CatalogExample[]; }[]","required":true,"defaultValue":null,"description":"Labeled groups of examples. Each example has a unique label within its group and can include additional data for the renderer."},{"name":"renderExample","type":"(example: CatalogExample) => ReactNode","required":true,"defaultValue":null,"description":"Renders one example, including its visible label or accessible name. The layout supplies the surrounding cell and spacing."}]}},{"name":"getting-started","content":"---\ntitle: Getting started\ndescription: Install Twenty UI in a React application and use its components and themes.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\n## Overview\n\nTwenty UI is Twenty's open-source React UI library. It provides foundational primitives, shared components, icons, and theme tokens with prebuilt CSS, so your application does not need a CSS-in-JS compiler.\n\n## Install\n\nFor an existing React application, install the library. React 19 is required.\n\n```bash\nyarn add twenty-ui\n```\n\nThe [code editor](/ui/components/code-editor/code-editor) has a separate entry point, `twenty-ui/components/code-editor`. Other components do not require Monaco. To use the code editor, install its optional peer dependencies and configure Monaco workers for your bundler before mounting it:\n\n```bash\nyarn add @monaco-editor/react monaco-editor\n```\n\nIf you are building a Twenty app, follow [Using Twenty UI components](/developers/extend/apps/layout/front-components#using-twenty-ui-components). The front component renderer supplies the workspace theme and has a different setup from a standalone browser application. Keep `twenty-ui`, `twenty-sdk`, and `twenty-client-sdk` on the same version.\n\n## Load styles and provide a theme\n\nImport the component stylesheet and a theme stylesheet once at your application entry point. `ThemeProvider` applies the active theme class and makes theme values available to components.\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\nimport { ThemeProvider } from 'twenty-ui/theme';\n\nimport 'twenty-ui/style.css';\nimport 'twenty-ui/theme-light.css';\n\nexport const App = () => (\n <ThemeProvider colorScheme=\"light\">\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input name=\"email\" type=\"email\" placeholder=\"[email protected]\" />\n <Field.Description>Use your work email address.</Field.Description>\n </Field.Root>\n </ThemeProvider>\n);\n```\n\nThe component stylesheet includes a global reset. Review its effect when adding Twenty UI to an existing application.\n\n## Override styles\n\nTwenty UI puts component styles and the reset in the `twenty-ui` cascade layer. Styles you write outside a layer, such as a `className`, a CSS module, or a CSS-in-JS rule, override those layered rules regardless of selector specificity or import order. Theme stylesheets and the optional editor's global Monaco rules remain unlayered.\n\nGlobal element resets in your application are unlayered too, so they would override Twenty UI components. Declare a layer for them before Twenty UI's stylesheet loads:\n\n```css\n@layer reset, twenty-ui;\n\n@layer reset {\n button {\n font: inherit;\n }\n}\n```\n\nWith Tailwind CSS v4, place Twenty UI between Tailwind's base and utility layers:\n\n```css\n@layer theme, base, twenty-ui, components, utilities;\n```\n\n## Choose an entry point\n\nImport components from their public subpath to keep imports focused:\n\nPrimitives are foundational controls, including compound controls such as Select,\nPopover, and AlertDialog. Shared components combine primitives into recurring\ndesign presets and reusable app building blocks. Both receive data and callbacks\nfrom the application.\n\nUse [MainButton](/ui/components/input/main-button) for prominent actions and\n[LightButton](/ui/components/input/light-button) for lightweight actions. Both\ncome from `twenty-ui/components/input` and share the foundational\n[Button](/ui/primitives/input/button) interaction contract. Routing and page\nlayout remain in the application.\n\nEach primitive and shared component family has a matching public entry point, such as\n`twenty-ui/primitives/input` and `twenty-ui/components/settings`. The aggregate\n`twenty-ui/primitives` and `twenty-ui/components` entries export their respective families.\nThe root `twenty-ui` entry re-exports primitives, shared components, icons, theme tokens,\nand utilities. Assets, testing helpers, and the optional code editor have separate entry points.\n\n| Import | Contents |\n| ------------------------------------ | ------------------------------------------------------------------- |\n| `twenty-ui/assets` | Logos and static assets |\n| `twenty-ui/components` | All shared component families except the optional editor |\n| `twenty-ui/components/data-display` | Avatar groups, command blocks, JSON trees, metrics, and icon tiles |\n| `twenty-ui/components/feedback` | Callouts, inline banners, and notifications |\n| `twenty-ui/components/input` | Button presets, specialized inputs, pickers, and segmented controls |\n| `twenty-ui/components/layout` | Sections, overflowing lists, and icon transitions |\n| `twenty-ui/components/navigation` | Dropdowns, menu compositions, and tab actions |\n| `twenty-ui/components/settings` | Settings rows with labeled controls |\n| `twenty-ui/components/code-editor` | Code editor, editor header, and editor theme helpers |\n| `twenty-ui/primitives` | All primitive families |\n| `twenty-ui/primitives/accessibility` | Hidden elements and keyboard interaction helpers |\n| `twenty-ui/primitives/data-display` | Avatars, badges, chips, tags, color samples, and status indicators |\n| `twenty-ui/primitives/feedback` | Banners, progress indicators, loaders, and skeletons |\n| `twenty-ui/primitives/input` | Buttons and form controls |\n| `twenty-ui/primitives/layout` | Expansion, separators, direction, and resizing |\n| `twenty-ui/primitives/navigation` | Breadcrumbs, list items, and tabs |\n| `twenty-ui/primitives/surfaces` | Cards, dialogs, popovers, and tooltips |\n| `twenty-ui/primitives/typography` | Text, headings, shortcuts, and overflowing text |\n| `twenty-ui/icon` | [Icons and dynamic lookup](/ui/icons) |\n| `twenty-ui/testing` | [Storybook decorators and layouts](/ui/testing) |\n| `twenty-ui/theme` | Theme provider, hooks, and CSS variable references |\n| `twenty-ui/utilities` | Hooks and shared utilities |\n\nImport individual icons, such as `IconCheck`, from `twenty-ui/icon`. The dynamic icon provider includes the full icon catalog, so reserve it for interfaces that need to look up icons at runtime.\n\n## Responsive hooks\n\nImport `useIsMobile`, `useIsTouchDevice`, and `useMediaQuery` from `twenty-ui/utilities`.\n\n| Hook | Query | Use |\n| ---------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |\n| `useIsMobile()` | `MOBILE_MEDIA_QUERY`, up to and including `MOBILE_VIEWPORT` | Choose a compact layout. |\n| `useIsTouchDevice()` | `TOUCH_DEVICE_MEDIA_QUERY`, `(hover: none) and (pointer: coarse)` | Choose touch interaction behavior independently of width. |\n| `useMediaQuery(query)` | Any media query supported by `window.matchMedia` | Subscribe to a custom media query. |\n\nThe query constants come from `twenty-ui/utilities`; `MOBILE_VIEWPORT` comes from `twenty-ui/theme`. Subscriptions share one `MediaQueryList` per query and update when its match changes. Hooks return `false` during server rendering, the first hydration render, and when `window.matchMedia` is unavailable.\n\nIn a [Twenty front component](/developers/extend/apps/layout/front-components#current-limitations), width queries follow the widget's box. `useIsMobile` therefore follows the widget width, while `useIsTouchDevice` follows the device's primary input. Use [story overrides](/ui/testing#media-query-overrides) to exercise these states in Storybook.\n\n## Continue\n\n- [Theming](/ui/theming): use semantic tokens and scoped overrides.\n- [Dark mode](/ui/dark-mode): switch between light and dark palettes.\n\n## Browse the library\n\n- [Primitives](/ui/primitives/overview): foundational controls grouped by family, with usage examples and API references.\n- [Components](/ui/components/overview): shared design presets and reusable app building blocks composed from primitives.\n\n<PageBanner illustration=\"card-page-ui-library\" />\n"},{"name":"theming","content":"---\ntitle: Theming\ndescription: Use Twenty UI theme tokens and scope theme overrides to part of your application.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport ThemeProviderReference from '/snippets/ui/generated/theme/theme-provider.mdx';\n\n## Overview\n\nTwenty UI components read public CSS custom properties prefixed with `--t-`. Prefer semantic tokens such as `background.secondary` and `font.color.primary` when styling your own components; these values adapt to the active palette.\n\n## Use tokens in styles\n\n`themeCssVariables` maps token paths to CSS variable references. Use it for values that CSS resolves:\n\n```tsx\nimport { themeCssVariables } from 'twenty-ui/theme';\n\nexport const Summary = () => (\n <section\n style={{\n background: themeCssVariables.background.secondary,\n color: themeCssVariables.font.color.primary,\n padding: themeCssVariables.spacing[4],\n borderRadius: themeCssVariables.border.radius.md,\n }}\n >\n Three tasks are due today.\n </section>\n);\n```\n\nThe equivalent CSS uses variables directly:\n\n```css\n.summary {\n background: var(--t-background-secondary);\n color: var(--t-font-color-primary);\n padding: var(--t-spacing-4);\n border-radius: var(--t-border-radius-md);\n}\n```\n\n## Read resolved values\n\n`useTheme()` reads the active provider's computed tokens. Use it when a component expects a JavaScript number, such as an icon size. The provider needs the theme stylesheet to be loaded in the browser to resolve CSS variables.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { useTheme } from 'twenty-ui/theme';\n\nexport const CompleteIcon = () => {\n const theme = useTheme();\n\n return <IconCheck size={theme.icon.size.md} aria-hidden />;\n};\n```\n\nEvery entry in `themeCssVariables` is a CSS reference string, including numeric tokens. Do not perform arithmetic on those strings. On the server, resolved browser values are unavailable; see [Server rendering](/ui/ssr).\n\n## Scope an override\n\nPass `applyToRoot={false}` to apply a theme to a subtree. Override public CSS variables by their full name:\n\n```tsx\nimport { type ReactNode } from 'react';\nimport { ThemeProvider } from 'twenty-ui/theme';\n\nexport const EmbeddedPanel = ({ children }: { children: ReactNode }) => (\n <ThemeProvider\n colorScheme=\"light\"\n applyToRoot={false}\n overrides={{ '--t-background-secondary': '#f4f6ff' }}\n >\n {children}\n </ThemeProvider>\n);\n```\n\nA scoped provider adds a wrapper with `display: contents`; it does not create a layout box. It also supplies a container for components that support themed portals. Portals created by other libraries need their own container configuration.\n\nVariables prefixed with `--tw-` are private component details. Use public props and `--t-` tokens instead of depending on those variables.\n\nSee the [token reference](/ui/tokens) for the available names and palette values.\n\n## Explicit values and scale\n\nThe `theme` prop supplies resolved JavaScript theme values instead of reading computed styles. It also flows to nested providers unless they supply another explicit theme. This changes values read by hooks; load the appropriate stylesheet and use CSS overrides to style components.\n\n`scale` writes `--t-scale-user` on the document root. It only affects interfaces whose CSS consumes that variable and is ignored by scoped providers. `className` applies to a scoped wrapper; passing it alone does not create a wrapper. `overrides` creates a scope even when `applyToRoot` remains true.\n\n## ThemeProvider props\n\n<ThemeProviderReference />\n\n<PageBanner illustration=\"page-cover-palette\" />\n"},{"name":"icons","content":"---\ntitle: Icons\ndescription: Named icons, dynamic lookup, illustration wrappers, and their supported props.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\nimport IconReference from '/snippets/ui/generated/icon/icon.mdx';\nimport IconsProviderReference from '/snippets/ui/generated/icon/icons-provider.mdx';\nimport IllustrationIconWrapperReference from '/snippets/ui/generated/icon/illustration-icon-wrapper.mdx';\nimport ThinkingOrbitLoaderIconReference from '/snippets/ui/generated/icon/thinking-orbit-loader-icon.mdx';\nimport IconCatalog from '/snippets/ui/generated/icon/catalog.mdx';\n\n## Overview\n\nImport named icons from `twenty-ui/icon`. Use the surrounding control or visible text to communicate meaning. Decorative icons should be hidden from assistive technology.\n\n```tsx\nimport { IconCheck } from 'twenty-ui/icon';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const CompleteButton = () => (\n <Button startIcon={<IconCheck />}>Complete task</Button>\n);\n```\n\nButton icon slots already size their icon and hide it from assistive technology, so the icon needs no extra props there.\n\n## Supported props\n\nTabler icons accept `size` (number or CSS length), `stroke` (stroke width), `color`, and native SVG attributes and refs. Custom brand and illustration icons accept only the props listed in the generated catalog below. Their sizing defaults vary; pass `size` for a consistent result. Brand colors can be fixed by the artwork, so a color override is available only where listed.\n\nCustom icons that do not accept accessible attributes need a wrapper with the appropriate label or `aria-hidden`. `className` and `style` are also available only where listed. Import a specific icon when possible to avoid loading the dynamic catalog.\n\nExported icons keep their requested width in flex layouts, including inside buttons. Let adjacent text truncate or let the parent wrap or scroll when space is limited. Where an icon supports `className` or `style`, you can explicitly override `flex-shrink` for a layout that needs it. Illustration containers also preserve their width.\n\n## Dynamic icon names\n\nUse `IconsProvider` and `Icon` from `twenty-ui/icon/provider` when names are chosen at runtime. The provider loads the complete icon map asynchronously; bundles built without code splitting, such as front components, include the whole map. `twenty-ui/icon` does not include the provider, so importing named icons never pulls in the map. Before loading completes, and for unknown names, `Icon` renders `Icon123`. The dynamic map differs from the named export catalog; do not assume every brand or illustration export can be resolved by name.\n\n```tsx\nimport { Icon, IconsProvider } from 'twenty-ui/icon/provider';\nimport { Button } from 'twenty-ui/primitives/input';\n\nexport const DynamicAction = ({ iconName }: { iconName: string }) => (\n <IconsProvider>\n <Button startIcon={<Icon name={iconName} />}>Open record</Button>\n </IconsProvider>\n);\n```\n\n`useIcons()` exposes `getIcon(name, customDefaultIcon)` and `getIcons()` inside the same provider. `getIcons()` initially returns an empty map. `getIcon` uses the named fallback when it exists, then `Icon123`. The provider accepts one child element; use a fragment for multiple children.\n\n### Icon props\n\n<IconReference />\n\n### IconsProvider props\n\n<IconsProviderReference />\n\n## Illustration wrapper\n\n`IllustrationIconWrapper` supplies the illustration container styling and forwards native div attributes, children, styles, and refs. Every `IllustrationIcon*` export already renders inside it, so use the wrapper only to frame your own illustration content.\n\n```tsx\nimport { IconCalendarEvent, IllustrationIconWrapper } from 'twenty-ui/icon';\n\nexport const CalendarIllustration = () => (\n <IllustrationIconWrapper role=\"img\" aria-label=\"Calendar event\">\n <IconCalendarEvent size={32} />\n </IllustrationIconWrapper>\n);\n```\n\n<IllustrationIconWrapperReference />\n\n## Animated loader icon\n\n`ThinkingOrbitLoaderIcon` animates continuously while mounted. It is decorative and always hidden from assistive technology. Show loading text separately and mount or remove the icon according to application state.\n\n<ThinkingOrbitLoaderIconReference />\n\n## Named icon catalog\n\nThis catalog is generated from the public `twenty-ui/icon` exports and groups icons by the props they accept.\n\n<IconCatalog />\n\n<PageBanner illustration=\"section-ui-components\" />\n"},{"name":"accessibility","content":"---\ntitle: Accessibility\ndescription: Label controls, preserve keyboard behavior, and test accessible Twenty UI interfaces.\n---\n\nimport { PageBanner } from \"/snippets/page-banner.mdx\"\n\n## Overview\n\nMigrated interactive components use Base UI primitives for semantics and keyboard behavior. Your application still supplies meaningful labels, descriptions, error messages, and focus order.\n\n## Label every control\n\nUse `Field.Label` with an input to associate a visible label with the control. `Field.Description` supplies supporting text:\n\n```tsx\nimport { Field, Input } from 'twenty-ui/primitives/input';\n\nexport const EmailField = () => (\n <Field.Root>\n <Field.Label>Email</Field.Label>\n <Input type=\"email\" name=\"email\" required />\n <Field.Description>\n We send account updates to this address.\n </Field.Description>\n <Field.Error>Enter a valid email address.</Field.Error>\n </Field.Root>\n);\n```\n\nUse [VisuallyHidden](/ui/primitives/accessibility/visually-hidden) when supporting text should remain available to assistive technology without being displayed.\n\nPlaceholders supplement labels; they do not replace them. For a control without visible text, supply an accessible name using `aria-label` or `aria-labelledby`.\n\n## Preserve native behavior\n\nUse the component's state and change props, such as `checked` and `onCheckedChange` on `Switch`. Keep focus indicators visible. When using `render` to replace an element, preserve the ref, event handlers, and attributes the component passes to it.\n\nA disabled control cannot be changed and is generally excluded from keyboard navigation and form submission. A read-only control retains its value and may remain focusable; choose the state that matches the interaction you intend.\n\n## Test the complete interface\n\nCheck keyboard navigation, labels, error announcements, focus movement in overlays, and zoom in the context where the component is used. Verify contrast in both palettes and after applying custom token overrides.\n\nTwenty UI's stories contain interaction and automated accessibility checks. Some stories still defer color-contrast checks, so those checks do not establish full accessibility conformance for an application.\n\n<PageBanner illustration=\"page-cover-accessibility\" />\n"}]}
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool.ts
index 8f9b0338d9f..1d52769f5da 100644
--- a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool.ts
@@ -5,7 +5,6 @@ import {
PermissionFlagType,
VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION,
} from 'twenty-shared/constants';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { z } from 'zod';
import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
@@ -37,7 +36,6 @@ const createValidationRuleInputSchema = z.object({
name: 'create_validation_rule',
category: ToolCategory.METADATA,
requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
- requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
icon: 'IconSettings',
description:
'Create a validation rule on an object. An invalid expression is rejected with the reason. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), they mean that rule: update it with update_validation_rule instead of creating another one.',
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool.ts
index fe4801d1025..f0d4a3c2352 100644
--- a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool.ts
@@ -2,7 +2,6 @@
import { ToolCategory } from 'twenty-shared/ai';
import { PermissionFlagType } from 'twenty-shared/constants';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { z } from 'zod';
import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
@@ -22,7 +21,6 @@ const getValidationRulesInputSchema = z.object({
name: 'get_validation_rules',
category: ToolCategory.METADATA,
requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
- requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
icon: 'IconSettings',
description:
'List the validation rules of an object: conditions a record must meet to be saved.',
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool.ts
index 08d4e7d423f..da66ce71732 100644
--- a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool.ts
@@ -5,7 +5,6 @@ import {
PermissionFlagType,
VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION,
} from 'twenty-shared/constants';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { z } from 'zod';
import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
@@ -41,7 +40,6 @@ const updateValidationRuleInputSchema = z.object({
name: 'update_validation_rule',
category: ToolCategory.METADATA,
requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
- requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
icon: 'IconSettings',
description:
'Update a validation rule. Only the provided properties change. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), requests about a rule are about that one. An active rule rejects an invalid expression with the reason; an inactive rule only checks it when activated, so check it first with validate_validation_rule_expression. Keep the rule inactive unless the user asks to activate it.',
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool.ts
index 45c5b53f6f5..4f6849e06fa 100644
--- a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool.ts
@@ -5,7 +5,6 @@ import {
PermissionFlagType,
VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION,
} from 'twenty-shared/constants';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { z } from 'zod';
import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
@@ -27,7 +26,6 @@ const validateValidationRuleExpressionInputSchema = z.object({
name: 'validate_validation_rule_expression',
category: ToolCategory.METADATA,
requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
- requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
icon: 'IconSettings',
description:
'Check a validation rule expression against an object without saving anything. An invalid expression is rejected with the reason.',
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.resolver.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.resolver.ts
index 21d63f82323..81a774a1aa9 100644
--- a/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.resolver.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.resolver.ts
@@ -9,7 +9,6 @@ import {
import { Args, Mutation, Query } from '@nestjs/graphql';
import { PermissionFlagType } from 'twenty-shared/constants';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { MetadataResolver } from 'src/engine/api/graphql/graphql-config/decorators/metadata-resolver.decorator';
import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
@@ -17,7 +16,6 @@ import { AuthGraphqlApiExceptionFilter } from 'src/engine/core-modules/auth/filt
import { ResolverValidationPipe } from 'src/engine/core-modules/graphql/pipes/resolver-validation.pipe';
import { WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';
import { AuthWorkspace } from 'src/engine/decorators/auth/auth-workspace.decorator';
-import { FeatureFlagGuard } from 'src/engine/guards/feature-flag.guard';
import { NoPermissionGuard } from 'src/engine/guards/no-permission.guard';
import { SettingsPermissionGuard } from 'src/engine/guards/settings-permission.guard';
import { AuthPrincipalGuard } from 'src/engine/guards/auth-principal.guard';
@@ -52,10 +50,7 @@ export class ValidationRuleResolver {
constructor(private readonly validationRuleService: ValidationRuleService) {}
@Query(() => [ValidationRuleDTO])
- @UseGuards(
- FeatureFlagGuard(FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED),
- NoPermissionGuard,
- )
+ @UseGuards(NoPermissionGuard)
async validationRules(
@Args('objectMetadataId', { type: () => UUIDScalarType })
objectMetadataId: string,
@@ -68,10 +63,7 @@ export class ValidationRuleResolver {
}
@Query(() => [ValidationRuleDTO])
- @UseGuards(
- FeatureFlagGuard(FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED),
- NoPermissionGuard,
- )
+ @UseGuards(NoPermissionGuard)
async validationRulesReadingField(
@Args('fieldMetadataId', { type: () => UUIDScalarType })
fieldMetadataId: string,
@@ -84,10 +76,7 @@ export class ValidationRuleResolver {
}
@Mutation(() => ValidationRuleDTO)
- @UseGuards(
- FeatureFlagGuard(FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED),
- SettingsPermissionGuard(PermissionFlagType.DATA_MODEL),
- )
+ @UseGuards(SettingsPermissionGuard(PermissionFlagType.DATA_MODEL))
async createValidationRule(
@Args('input') input: CreateValidationRuleInput,
@AuthWorkspace() workspace: WorkspaceEntity,
@@ -99,10 +88,7 @@ export class ValidationRuleResolver {
}
@Mutation(() => ValidationRuleDTO)
- @UseGuards(
- FeatureFlagGuard(FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED),
- SettingsPermissionGuard(PermissionFlagType.DATA_MODEL),
- )
+ @UseGuards(SettingsPermissionGuard(PermissionFlagType.DATA_MODEL))
async updateValidationRule(
@Args('input') input: UpdateValidationRuleInput,
@AuthWorkspace() workspace: WorkspaceEntity,
@@ -114,10 +100,7 @@ export class ValidationRuleResolver {
}
@Mutation(() => ValidationRuleDTO)
- @UseGuards(
- FeatureFlagGuard(FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED),
- SettingsPermissionGuard(PermissionFlagType.DATA_MODEL),
- )
+ @UseGuards(SettingsPermissionGuard(PermissionFlagType.DATA_MODEL))
async deleteValidationRule(
@Args('id', { type: () => UUIDScalarType }) id: string,
@AuthWorkspace() workspace: WorkspaceEntity,
diff --git a/packages/twenty-server/src/engine/twenty-orm/__tests__/workspace-orm.manager.spec.ts b/packages/twenty-server/src/engine/twenty-orm/__tests__/workspace-orm.manager.spec.ts
index a720963a64f..9769ea55d1c 100644
--- a/packages/twenty-server/src/engine/twenty-orm/__tests__/workspace-orm.manager.spec.ts
+++ b/packages/twenty-server/src/engine/twenty-orm/__tests__/workspace-orm.manager.spec.ts
@@ -19,7 +19,7 @@ describe('workspace context sharing enforcement', () => {
{ provide: WorkspaceDataSourceService, useValue: {} },
{
provide: EnterprisePlanService,
- useValue: { isValid: jest.fn().mockReturnValue(true) },
+ useValue: { isValid: jest.fn().mockReturnValue(false) },
},
{
provide: TwentyConfigService,
@@ -33,6 +33,7 @@ describe('workspace context sharing enforcement', () => {
flatRowLevelPermissionPredicateMaps:
createEmptyFlatEntityMaps(),
featureFlagsMap: {},
+ billingEntitlements: {},
}),
},
},
diff --git a/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/is-validation-rule-enforcement-enabled.util.spec.ts b/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/is-validation-rule-enforcement-enabled.util.spec.ts
index c69975ec603..66d872dfc09 100644
--- a/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/is-validation-rule-enforcement-enabled.util.spec.ts
+++ b/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/is-validation-rule-enforcement-enabled.util.spec.ts
@@ -1,17 +1,12 @@
/* @license Enterprise */
-import { FeatureFlagKey } from 'twenty-shared/types';
-
import { BillingEntitlementKey } from 'src/engine/core-modules/billing/enums/billing-entitlement-key.enum';
import { isValidationRuleEnforcementEnabled } from 'src/engine/twenty-orm/utils/is-validation-rule-enforcement-enabled.util';
-const FLAG_ON = { [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED]: true };
-
describe('isValidationRuleEnforcementEnabled', () => {
it('enforces rules on an Organization plan workspace', () => {
expect(
isValidationRuleEnforcementEnabled({
- featureFlagsMap: FLAG_ON,
billingEntitlements: { [BillingEntitlementKey.VALIDATION_RULES]: true },
hasValidEnterprisePlan: true,
isBillingEnabled: true,
@@ -22,7 +17,6 @@ describe('isValidationRuleEnforcementEnabled', () => {
it('enforces rules on a self-hosted instance with a valid Organization key', () => {
expect(
isValidationRuleEnforcementEnabled({
- featureFlagsMap: FLAG_ON,
billingEntitlements: {},
hasValidEnterprisePlan: true,
isBillingEnabled: false,
@@ -34,7 +28,6 @@ describe('isValidationRuleEnforcementEnabled', () => {
[
'the workspace plan does not include them',
{
- featureFlagsMap: FLAG_ON,
billingEntitlements: {
[BillingEntitlementKey.VALIDATION_RULES]: false,
},
@@ -45,21 +38,11 @@ describe('isValidationRuleEnforcementEnabled', () => {
[
'the Organization key is not valid',
{
- featureFlagsMap: FLAG_ON,
billingEntitlements: {},
hasValidEnterprisePlan: false,
isBillingEnabled: false,
},
],
- [
- 'the feature flag is off',
- {
- featureFlagsMap: {},
- billingEntitlements: { [BillingEntitlementKey.VALIDATION_RULES]: true },
- hasValidEnterprisePlan: true,
- isBillingEnabled: true,
- },
- ],
])('stops enforcing rules when %s', (_label, input) => {
expect(isValidationRuleEnforcementEnabled(input)).toBe(false);
});
diff --git a/packages/twenty-server/src/engine/twenty-orm/utils/is-validation-rule-enforcement-enabled.util.ts b/packages/twenty-server/src/engine/twenty-orm/utils/is-validation-rule-enforcement-enabled.util.ts
index e4a599a6861..b3ae683c960 100644
--- a/packages/twenty-server/src/engine/twenty-orm/utils/is-validation-rule-enforcement-enabled.util.ts
+++ b/packages/twenty-server/src/engine/twenty-orm/utils/is-validation-rule-enforcement-enabled.util.ts
@@ -1,23 +1,18 @@
/* @license Enterprise */
-import { FeatureFlagKey } from 'twenty-shared/types';
-
import { BillingEntitlementKey } from 'src/engine/core-modules/billing/enums/billing-entitlement-key.enum';
import { type BillingEntitlements } from 'src/engine/core-modules/billing/types/billing-entitlements.type';
import { isEntitlementActive } from 'src/engine/core-modules/billing/utils/is-entitlement-active.util';
export const isValidationRuleEnforcementEnabled = ({
- featureFlagsMap,
billingEntitlements,
hasValidEnterprisePlan,
isBillingEnabled,
}: {
- featureFlagsMap: Partial<Record<FeatureFlagKey, boolean>>;
billingEntitlements: BillingEntitlements;
hasValidEnterprisePlan: boolean;
isBillingEnabled: boolean;
}): boolean =>
- featureFlagsMap[FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED] === true &&
isEntitlementActive({
key: BillingEntitlementKey.VALIDATION_RULES,
hasValidEnterprisePlan,
diff --git a/packages/twenty-server/src/engine/twenty-orm/workspace-orm.manager.ts b/packages/twenty-server/src/engine/twenty-orm/workspace-orm.manager.ts
index 17e561ba5dd..0e4ebcc8fd1 100644
--- a/packages/twenty-server/src/engine/twenty-orm/workspace-orm.manager.ts
+++ b/packages/twenty-server/src/engine/twenty-orm/workspace-orm.manager.ts
@@ -179,7 +179,6 @@ export class WorkspaceOrmManager {
});
const flatValidationRuleMaps = isValidationRuleEnforcementEnabled({
- featureFlagsMap,
billingEntitlements,
hasValidEnterprisePlan: this.enterprisePlanService.isValid(),
isBillingEnabled: this.twentyConfigService.get('IS_BILLING_ENABLED'),
diff --git a/packages/twenty-server/src/engine/workspace-manager/dev-seeder/core/utils/seed-feature-flags.util.ts b/packages/twenty-server/src/engine/workspace-manager/dev-seeder/core/utils/seed-feature-flags.util.ts
index 3b92e19e9c5..109da49f9b7 100644
--- a/packages/twenty-server/src/engine/workspace-manager/dev-seeder/core/utils/seed-feature-flags.util.ts
+++ b/packages/twenty-server/src/engine/workspace-manager/dev-seeder/core/utils/seed-feature-flags.util.ts
@@ -4,7 +4,6 @@ import { type QueryRunner } from 'typeorm';
const tableName = 'featureFlag';
const DEFAULT_SEEDED_FEATURE_FLAGS: Partial<Record<FeatureFlagKey, boolean>> = {
- [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED]: true,
[FeatureFlagKey.IS_RECORD_LEVEL_SHARING_ENABLED]: false,
[FeatureFlagKey.IS_CALENDAR_EVENT_SHARED_ACROSS_CHANNELS_ENABLED]: true,
[FeatureFlagKey.IS_AI_CHAT_INBOX_ENABLED]: true,
diff --git a/packages/twenty-server/test/integration/ai/suites/mcp-metadata-tools.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp-metadata-tools.integration-spec.ts
index 35d03a45d7b..019344dd3c7 100644
--- a/packages/twenty-server/test/integration/ai/suites/mcp-metadata-tools.integration-spec.ts
+++ b/packages/twenty-server/test/integration/ai/suites/mcp-metadata-tools.integration-spec.ts
@@ -3,11 +3,9 @@ import { getMcpToolCatalog } from 'test/integration/graphql/suites/application-r
import { deleteOneObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/delete-one-object-metadata.util';
import { findManyObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/find-many-object-metadata.util';
import { updateOneObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/update-one-object-metadata.util';
-import { updateFeatureFlag } from 'test/integration/metadata/suites/utils/update-feature-flag.util';
import { waitForDeferredWorkspaceMigrationActionsOrThrow } from 'test/integration/utils/wait-for-deferred-workspace-migration-actions-or-throw.util';
import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
import { ToolCategory } from 'twenty-shared/ai';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
@@ -588,49 +586,4 @@ describe('MCP metadata tools (integration)', () => {
});
});
});
-
- describe('with IS_RECORD_CREATION_FORM_ENABLED off', () => {
- beforeAll(async () => {
- await updateFeatureFlag({
- featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: false,
- expectToFail: false,
- });
- });
-
- // The flag is seeded on
- afterAll(async () => {
- await updateFeatureFlag({
- featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: true,
- expectToFail: false,
- });
- });
-
- it('should list the object and field tools only', async () => {
- const catalog = await getMcpToolCatalog({ token: API_KEY_ACCESS_TOKEN });
-
- expect(catalog[ToolCategory.METADATA].map(({ name }) => name)).toEqual(
- OBJECT_AND_FIELD_TOOL_NAMES,
- );
- });
-
- it('should still run an object tool', async () => {
- expect(await findObjectOrThrow('company')).toMatchObject({
- nameSingular: 'company',
- });
- });
-
- it.each(VALIDATION_RULE_TOOL_NAMES)(
- 'should refuse %s',
- async (toolName) => {
- expect(
- await runFailingMetadataTool({ toolName, toolArguments: {} }),
- ).toMatchObject({
- success: false,
- message: `Tool "${toolName}" not found`,
- });
- },
- );
- });
});
diff --git a/packages/twenty-server/test/integration/endpoint-permissions/__snapshots__/endpoint-permission-declarations.integration-spec.ts.snap b/packages/twenty-server/test/integration/endpoint-permissions/__snapshots__/endpoint-permission-declarations.integration-spec.ts.snap
index 8a4e0881ee9..574589bdbb7 100644
--- a/packages/twenty-server/test/integration/endpoint-permissions/__snapshots__/endpoint-permission-declarations.integration-spec.ts.snap
+++ b/packages/twenty-server/test/integration/endpoint-permissions/__snapshots__/endpoint-permission-declarations.integration-spec.ts.snap
@@ -606,11 +606,11 @@ exports[`endpoint permission declarations should match the auth principals, perm
"UserSessionResolver.currentUserSessions {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":false,"application":{"withAgent":false,"withUser":false,"withoutUser":false},"oauthClient":{"withUser":false,"withoutUser":false},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":true}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
"UserSessionResolver.revokeAllOtherUserSessions {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":false,"application":{"withAgent":false,"withUser":false,"withoutUser":false},"oauthClient":{"withUser":false,"withoutUser":false},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":true}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
"UserSessionResolver.revokeUserSession {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":false,"application":{"withAgent":false,"withUser":false,"withoutUser":false},"oauthClient":{"withUser":false,"withoutUser":false},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":true}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
- "ValidationRuleResolver.createValidationRule {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":["IS_RECORD_CREATION_FORM_ENABLED"],"requiredPermissionFlags":["DATA_MODEL"]}",
- "ValidationRuleResolver.deleteValidationRule {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":["IS_RECORD_CREATION_FORM_ENABLED"],"requiredPermissionFlags":["DATA_MODEL"]}",
- "ValidationRuleResolver.updateValidationRule {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":["IS_RECORD_CREATION_FORM_ENABLED"],"requiredPermissionFlags":["DATA_MODEL"]}",
- "ValidationRuleResolver.validationRules {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":["IS_RECORD_CREATION_FORM_ENABLED"],"requiredPermissionFlags":[]}",
- "ValidationRuleResolver.validationRulesReadingField {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":["IS_RECORD_CREATION_FORM_ENABLED"],"requiredPermissionFlags":[]}",
+ "ValidationRuleResolver.createValidationRule {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":["DATA_MODEL"]}",
+ "ValidationRuleResolver.deleteValidationRule {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":["DATA_MODEL"]}",
+ "ValidationRuleResolver.updateValidationRule {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":["DATA_MODEL"]}",
+ "ValidationRuleResolver.validationRules {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
+ "ValidationRuleResolver.validationRulesReadingField {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
"ViewController.create {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
"ViewController.delete {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
"ViewController.findMany {"applicationTarget":null,"authPrincipalGuards":[{"apiKey":true,"application":{"withAgent":false,"withUser":true,"withoutUser":true},"oauthClient":{"withUser":true,"withoutUser":true},"userSession":{"impersonated":true,"playground":true,"standard":true,"workspaceAgnostic":false}}],"requiredFeatureFlags":[],"requiredPermissionFlags":[]}",
diff --git a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-application-sync.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-application-sync.integration-spec.ts
index c95451bfd85..4e6f077d344 100644
--- a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-application-sync.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-application-sync.integration-spec.ts
@@ -7,14 +7,13 @@ import { setupApplicationForSync } from 'test/integration/metadata/suites/applic
import { syncApplication } from 'test/integration/metadata/suites/application/utils/sync-application.util';
import { uninstallApplication } from 'test/integration/metadata/suites/application/utils/uninstall-application.util';
import { findManyObjectMetadataWithIndexes } from 'test/integration/metadata/suites/object-metadata/utils/find-many-object-metadata-with-indexes.util';
-import { updateFeatureFlag } from 'test/integration/metadata/suites/utils/update-feature-flag.util';
import {
createValidationRule,
findValidationRules,
} from 'test/integration/metadata/suites/validation-rule/utils/validation-rule-api.util';
import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
import { type FieldManifest } from 'twenty-shared/application';
-import { FeatureFlagKey, FieldMetadataType } from 'twenty-shared/types';
+import { FieldMetadataType } from 'twenty-shared/types';
import { v4 as uuidv4 } from 'uuid';
const TEST_APP_ID = uuidv4();
@@ -80,12 +79,6 @@ describe('Validation rules across application syncs', () => {
let validationRuleId: string;
beforeAll(async () => {
- await updateFeatureFlag({
- featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: true,
- expectToFail: false,
- });
-
await setupApplicationForSync({
applicationUniversalIdentifier: TEST_APP_ID,
name: 'Validation Rule Sync App',
diff --git a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-enforcement.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-enforcement.integration-spec.ts
index 46ae06d6144..d037a67b054 100644
--- a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-enforcement.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-enforcement.integration-spec.ts
@@ -1,12 +1,10 @@
/* @license Enterprise */
import gql from 'graphql-tag';
-import { FeatureFlagKey } from 'twenty-shared/types';
import { makeGraphqlApiRequest } from 'test/integration/graphql/utils/make-graphql-api-request.util';
import { findManyObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/find-many-object-metadata.util';
import { makeMetadataApiRequest } from 'test/integration/metadata/suites/utils/make-metadata-api-request.util';
-import { updateFeatureFlag } from 'test/integration/metadata/suites/utils/update-feature-flag.util';
import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
const CUSTOMER_NEEDS_AMOUNT_EXPRESSION =
@@ -54,12 +52,6 @@ describe('Validation rules should be enforced on record writes', () => {
const createdOpportunityIds: string[] = [];
beforeAll(async () => {
- await updateFeatureFlag({
- featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: true,
- expectToFail: false,
- });
-
const { objects } = await findManyObjectMetadata({
expectToFail: false,
input: { filter: {}, paging: { first: 1000 } },
diff --git a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-field-lifecycle.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-field-lifecycle.integration-spec.ts
index 4a948fdd599..72f887cd976 100644
--- a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-field-lifecycle.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-field-lifecycle.integration-spec.ts
@@ -6,7 +6,6 @@ import { updateOneFieldMetadata } from 'test/integration/metadata/suites/field-m
import { createOneObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/create-one-object-metadata.util';
import { deleteOneObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/delete-one-object-metadata.util';
import { updateOneObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/update-one-object-metadata.util';
-import { updateFeatureFlag } from 'test/integration/metadata/suites/utils/update-feature-flag.util';
import {
createValidationRule,
deleteValidationRule,
@@ -16,7 +15,7 @@ import {
} from 'test/integration/metadata/suites/validation-rule/utils/validation-rule-api.util';
import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
import { STANDARD_OBJECTS } from 'twenty-shared/metadata';
-import { FeatureFlagKey, FieldMetadataType } from 'twenty-shared/types';
+import { FieldMetadataType } from 'twenty-shared/types';
import { SEED_APPLE_WORKSPACE_ID } from 'src/engine/workspace-manager/dev-seeder/core/constants/seeder-workspaces.constant';
@@ -33,12 +32,6 @@ describe('Validation rules should follow the fields they read', () => {
);
beforeAll(async () => {
- await updateFeatureFlag({
- featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: true,
- expectToFail: false,
- });
-
const {
data: {
createOneObject: { id },
diff --git a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-metadata.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-metadata.integration-spec.ts
index f529b971ce6..b2f0ac33eda 100644
--- a/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-metadata.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/validation-rule/validation-rule-metadata.integration-spec.ts
@@ -1,7 +1,6 @@
/* @license Enterprise */
import { findManyObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/find-many-object-metadata.util';
-import { updateFeatureFlag } from 'test/integration/metadata/suites/utils/update-feature-flag.util';
import {
createValidationRule,
deleteValidationRule,
@@ -9,7 +8,6 @@ import {
updateValidationRule,
} from 'test/integration/metadata/suites/validation-rule/utils/validation-rule-api.util';
import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
-import { FeatureFlagKey } from 'twenty-shared/types';
describe('Validation rule metadata', () => {
let companyObjectMetadataId: string;
@@ -26,12 +24,6 @@ describe('Validation rule metadata', () => {
};
beforeAll(async () => {
- await updateFeatureFlag({
- featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- value: true,
- expectToFail: false,
- });
-
const { objects } = await findManyObjectMetadata({
expectToFail: false,
input: { filter: {}, paging: { first: 1000 } },
diff --git a/packages/twenty-shared/src/types/FeatureFlagKey.ts b/packages/twenty-shared/src/types/FeatureFlagKey.ts
index 43649959e44..23f2e012b1e 100644
--- a/packages/twenty-shared/src/types/FeatureFlagKey.ts
+++ b/packages/twenty-shared/src/types/FeatureFlagKey.ts
@@ -2,7 +2,6 @@ export enum FeatureFlagKey {
IS_AI_CHAT_COMPONENT_BUILDER_ENABLED = 'IS_AI_CHAT_COMPONENT_BUILDER_ENABLED',
IS_CONFIGURABLE_SEARCH_FIELDS_ENABLED = 'IS_CONFIGURABLE_SEARCH_FIELDS_ENABLED',
IS_REST_METADATA_API_NEW_FORMAT_DIRECT = 'IS_REST_METADATA_API_NEW_FORMAT_DIRECT',
- IS_RECORD_CREATION_FORM_ENABLED = 'IS_RECORD_CREATION_FORM_ENABLED',
IS_RECORD_LEVEL_SHARING_ENABLED = 'IS_RECORD_LEVEL_SHARING_ENABLED',
IS_CALENDAR_EVENT_SHARED_ACROSS_CHANNELS_ENABLED = 'IS_CALENDAR_EVENT_SHARED_ACROSS_CHANNELS_ENABLED',
IS_AI_CHAT_INBOX_ENABLED = 'IS_AI_CHAT_INBOX_ENABLED',