Skip to content

The open alternative to Salesforce, designed for AI.

Expose the selected records filter to front components (#27404)

Charles Bochetb2a48824c94e
diff --git a/packages/twenty-agent-skills/references/develop-app/front-components.md b/packages/twenty-agent-skills/references/develop-app/front-components.md
index 477c3b7ee62..0e4b60186b0 100644
--- a/packages/twenty-agent-skills/references/develop-app/front-components.md
+++ b/packages/twenty-agent-skills/references/develop-app/front-components.md
@@ -48,6 +48,7 @@ Prefer Twenty UI icons from `twenty-ui/icon` when one exists. Use inline SVG onl
For record-page components, read selection from front component context:
- Use `useSelectedRecordIds()` for single, bulk, or empty selection; derive one id only when the array length is 1.
+- Under Select all, `useSelectedRecordIds()` is empty. Use `useSelectedRecordsFilter()` for bulk commands: it returns a filter matching exactly the selection in every case; query records with it or pass it to a logic function.
- Use `useSelectedObjectMetadata()` from `twenty-sdk/front-component` to identify the object for a record-page widget, a custom timeline row, an object-scoped command, or a front component opened in the side panel with an object (from a command, or through `openSidePanelPage` with an `objectNameSingular`). It returns `{ id, nameSingular, namePlural }` or `null`. The `id` is the workspace's object-metadata UUID, and the names are metadata names such as `person` and `people`, not display labels.
Object metadata belongs to the front component's own context, so a side panel can expose a different object from the main page. It can be available even when no records are selected and updates when that context changes. The hook returns `null` when no object context is supplied, when the object cannot be resolved, or when an older host does not provide object metadata. Use it to select object-specific templates or configuration without searching every object for a record ID.
diff --git a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx
index 64d52b8d3df..583632a0863 100644
--- a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx
@@ -460,6 +460,7 @@ Available hooks:
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `useUserId()` | `string` or `null` | The current user's ID |
| `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |
+| `useSelectedRecordsFilter()` | `RecordGqlOperationFilter` or `null` | Filter matching exactly the selected records, including under Select all |
| `useSelectedObjectMetadata()` | `FrontComponentSelectedObjectMetadata` or `null` | The object metadata associated with this front component's record context |
| `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead |
| `useFrontComponentId()` | `string` | This component instance's ID |
@@ -749,6 +750,36 @@ export default defineCommandMenuItem({
});
```
+#### Select all
+
+When the user selects all records of a view, `useSelectedRecordIds()` returns an empty array: the selection is defined by the view's filters, search and unticked rows, and can hold far more records than fit in memory. `useSelectedRecordsFilter()` returns a filter matching exactly the selected records in every case, so query with it instead of listing IDs:
+
+```tsx
+import { Command, useSelectedRecordsFilter } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const MarkExported = () => {
+ const selectedRecordsFilter = useSelectedRecordsFilter();
+
+ const execute = async () => {
+ if (selectedRecordsFilter === null) {
+ return;
+ }
+
+ await new CoreApiClient().mutation({
+ updateTasks: {
+ __args: { filter: selectedRecordsFilter, data: { exported: true } },
+ id: true,
+ },
+ });
+ };
+
+ return <Command execute={execute} />;
+};
+```
+
+For large selections, pass the filter to a [logic function](/developers/extend/apps/logic/logic-functions) and process the records there, page by page.
+
## Public assets
Front components can access files from the app's `public/` directory using `getPublicAssetUrl`:
diff --git a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsx b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsx
index 3350745a79f..64753afecc2 100644
--- a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsx
+++ b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsx
@@ -32,6 +32,7 @@ export const HeadlessFrontComponentRendererEngineCommand = () => {
frontComponentId={context.frontComponentId}
commandMenuItemId={commandMenuItemId}
selectedRecordIds={selectedRecordIds}
+ selectedRecordsFilter={context.graphqlFilter}
objectNameSingular={context.objectMetadataItem?.nameSingular}
/>
</Suspense>
diff --git a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsx b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsx
index e435cfabb26..772762637c7 100644
--- a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsx
+++ b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsx
@@ -4,6 +4,7 @@ import { HeadlessFrontComponentRendererEngineCommand } from '@/command-menu-item
import { CommandComponentInstanceContext } from '@/command-menu-item/engine-command/states/contexts/CommandComponentInstanceContext';
import { type HeadlessFrontComponentCommandContextApi } from '@/command-menu-item/engine-command/types/HeadlessCommandContextApi';
import { type EnrichedObjectMetadataItem } from '@/object-metadata/types/EnrichedObjectMetadataItem';
+import { type RecordGqlOperationFilter } from 'twenty-shared/types';
let mockHeadlessCommandContextApi: HeadlessFrontComponentCommandContextApi;
@@ -19,15 +20,17 @@ jest.mock('@/front-components/components/FrontComponentRenderer', () => ({
frontComponentId,
commandMenuItemId,
selectedRecordIds,
+ selectedRecordsFilter,
objectNameSingular,
}: {
frontComponentId: string;
commandMenuItemId?: string;
selectedRecordIds?: string[];
+ selectedRecordsFilter?: RecordGqlOperationFilter | null;
objectNameSingular?: string;
}) => (
<div data-testid="front-component">
- {`${frontComponentId}:${commandMenuItemId}:${objectNameSingular ?? 'no object'}:${selectedRecordIds?.join(',') || 'no records'}`}
+ {`${frontComponentId}:${commandMenuItemId}:${objectNameSingular ?? 'no object'}:${selectedRecordIds?.join(',') || 'no records'}:${JSON.stringify(selectedRecordsFilter ?? null)}`}
</div>
),
}));
@@ -35,14 +38,17 @@ jest.mock('@/front-components/components/FrontComponentRenderer', () => ({
const renderHeadlessFrontComponentCommand = ({
objectMetadataItem,
selectedRecordIds,
+ graphqlFilter = null,
}: {
objectMetadataItem: EnrichedObjectMetadataItem | null;
selectedRecordIds: string[];
+ graphqlFilter?: RecordGqlOperationFilter | null;
}) => {
mockHeadlessCommandContextApi = {
frontComponentId: 'front-component-id',
objectMetadataItem,
selectedRecords: selectedRecordIds.map((id) => ({ id })),
+ graphqlFilter,
} as HeadlessFrontComponentCommandContextApi;
render(
@@ -64,7 +70,7 @@ describe('HeadlessFrontComponentRendererEngineCommand', () => {
});
expect(await screen.findByTestId('front-component')).toHaveTextContent(
- 'front-component-id:command-menu-item-id:company:record-1,record-2',
+ 'front-component-id:command-menu-item-id:company:record-1,record-2:null',
);
});
@@ -75,7 +81,28 @@ describe('HeadlessFrontComponentRendererEngineCommand', () => {
});
expect(await screen.findByTestId('front-component')).toHaveTextContent(
- 'front-component-id:command-menu-item-id:no object:no records',
+ 'front-component-id:command-menu-item-id:no object:no records:null',
+ );
+ });
+
+ it('hands the component the filter matching a Select all selection', async () => {
+ const selectAllFilter: RecordGqlOperationFilter = {
+ and: [
+ { name: { ilike: '%acme%' } },
+ { not: { id: { in: ['record-3'] } } },
+ ],
+ };
+
+ renderHeadlessFrontComponentCommand({
+ objectMetadataItem: {
+ nameSingular: 'company',
+ } as EnrichedObjectMetadataItem,
+ selectedRecordIds: [],
+ graphqlFilter: selectAllFilter,
+ });
+
+ expect(await screen.findByTestId('front-component')).toHaveTextContent(
+ `front-component-id:command-menu-item-id:company:no records:${JSON.stringify(selectAllFilter)}`,
);
});
});
diff --git a/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsx b/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsx
index 0d58a255a4c..e421f85ce39 100644
--- a/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsx
+++ b/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsx
@@ -16,6 +16,7 @@ import { t } from '@lingui/core/macro';
import { type ReactNode, useCallback, useMemo, useState } from 'react';
import { FrontComponentRenderer as SharedFrontComponentRenderer } from 'twenty-front-component-renderer';
import { type FrontComponentToolCall } from 'twenty-sdk/front-component';
+import { type RecordGqlOperationFilter } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
import { useToast } from 'twenty-ui/components/feedback';
import { useThemeColorScheme } from 'twenty-ui/theme';
@@ -30,6 +31,7 @@ type FrontComponentRendererProps = {
frontComponentId: string;
commandMenuItemId?: string;
selectedRecordIds?: string[];
+ selectedRecordsFilter?: RecordGqlOperationFilter | null;
objectNameSingular?: string;
timelineActivityId?: string;
toolCall?: FrontComponentToolCall;
@@ -45,6 +47,7 @@ type FrontComponentRendererContentProps = {
frontComponent: ResolvedFrontComponent;
commandMenuItemId?: string;
selectedRecordIds?: string[];
+ selectedRecordsFilter?: RecordGqlOperationFilter | null;
objectNameSingular?: string;
timelineActivityId?: string;
toolCall?: FrontComponentToolCall;
@@ -56,6 +59,7 @@ export const FrontComponentRenderer = ({
frontComponentId,
commandMenuItemId,
selectedRecordIds,
+ selectedRecordsFilter,
objectNameSingular,
timelineActivityId,
toolCall,
@@ -85,6 +89,7 @@ export const FrontComponentRenderer = ({
frontComponent={frontComponent}
commandMenuItemId={commandMenuItemId}
selectedRecordIds={selectedRecordIds}
+ selectedRecordsFilter={selectedRecordsFilter}
objectNameSingular={objectNameSingular}
timelineActivityId={timelineActivityId}
toolCall={toolCall}
@@ -100,6 +105,7 @@ const FrontComponentRendererContent = ({
frontComponent,
commandMenuItemId,
selectedRecordIds,
+ selectedRecordsFilter,
objectNameSingular,
timelineActivityId,
toolCall,
@@ -127,6 +133,7 @@ const FrontComponentRendererContent = ({
applicationId,
commandMenuItemId,
selectedRecordIds,
+ selectedRecordsFilter,
objectNameSingular,
timelineActivityId,
toolCall,
diff --git a/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx b/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx
index f9036146854..20414a28b85 100644
--- a/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx
+++ b/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx
@@ -253,6 +253,7 @@ describe('useFrontComponentExecutionContext', () => {
userId: 'user-123',
recordId: 'record-456',
selectedRecordIds: ['record-456'],
+ selectedRecordsFilter: null,
selectedObjectMetadata: null,
timelineActivityId: null,
colorScheme: 'light',
@@ -260,6 +261,25 @@ describe('useFrontComponentExecutionContext', () => {
});
});
+ it('should pass the selected records filter through', () => {
+ const selectedRecordsFilter = {
+ and: [
+ { name: { ilike: '%acme%' } },
+ { not: { id: { in: ['record-3'] } } },
+ ],
+ };
+
+ const { result } = renderUseFrontComponentExecutionContext({
+ frontComponentId: FRONT_COMPONENT_ID,
+ selectedRecordIds: [],
+ selectedRecordsFilter,
+ });
+
+ expect(result.current.executionContext.selectedRecordsFilter).toEqual(
+ selectedRecordsFilter,
+ );
+ });
+
it('should return null recordId when multiple selectedRecordIds provided', () => {
const { result } = renderUseFrontComponentExecutionContext({
frontComponentId: FRONT_COMPONENT_ID,
@@ -271,6 +291,7 @@ describe('useFrontComponentExecutionContext', () => {
userId: 'user-123',
recordId: null,
selectedRecordIds: ['record-1', 'record-2', 'record-3'],
+ selectedRecordsFilter: null,
selectedObjectMetadata: null,
timelineActivityId: null,
colorScheme: 'light',
diff --git a/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts b/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts
index 7a758254f79..e1a319fab02 100644
--- a/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts
+++ b/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts
@@ -23,6 +23,7 @@ import {
OpenRecordIn,
SidePanelPages,
type EnqueueSnackbarParams,
+ type RecordGqlOperationFilter,
} from 'twenty-shared/types';
import { serializePlainTextAsAdvancedTextEditorDocument } from '@/advanced-text-editor/utils/serializePlainTextAsAdvancedTextEditorDocument';
@@ -122,6 +123,7 @@ export const useFrontComponentExecutionContext = ({
applicationId,
commandMenuItemId,
selectedRecordIds,
+ selectedRecordsFilter,
objectNameSingular,
timelineActivityId,
toolCall,
@@ -131,6 +133,7 @@ export const useFrontComponentExecutionContext = ({
applicationId: string;
commandMenuItemId?: string;
selectedRecordIds?: string[];
+ selectedRecordsFilter?: RecordGqlOperationFilter | null;
objectNameSingular?: string;
timelineActivityId?: string;
toolCall?: FrontComponentToolCall;
@@ -436,6 +439,7 @@ export const useFrontComponentExecutionContext = ({
userId: currentUser?.id ?? null,
recordId: selectedRecordIds?.length === 1 ? selectedRecordIds[0] : null,
selectedRecordIds: selectedRecordIds ?? [],
+ selectedRecordsFilter: selectedRecordsFilter ?? null,
selectedObjectMetadata: isDefined(selectedObjectMetadataItem)
? {
id: selectedObjectMetadataItem.id,
diff --git a/packages/twenty-sdk/CHANGELOG.md b/packages/twenty-sdk/CHANGELOG.md
index f846d439b6b..516b178dee6 100644
--- a/packages/twenty-sdk/CHANGELOG.md
+++ b/packages/twenty-sdk/CHANGELOG.md
@@ -32,6 +32,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
### Added
+- **`useSelectedRecordsFilter` in `twenty-sdk/front-component`.** Returns a record filter matching exactly the records the user selected, or `null` when there is no selection context. Under Select all, `useSelectedRecordIds()` is empty because the selection is defined by the view's filters, search and unticked rows; query the records with this filter, or pass it to a logic function. Twenty servers that predate it return `null`.
+
+ ```tsx
+ import { useSelectedRecordsFilter } from 'twenty-sdk/front-component';
+
+ const selectedRecordsFilter = useSelectedRecordsFilter();
+ ```
+
- **`enqueueJobs` in `twenty-sdk/logic-function`.** Enqueues one run per payload of a single logic function in one call (up to 200 payloads per batch). `retryLimit` and `delayMs` apply to every run in the batch.
```ts
diff --git a/packages/twenty-sdk/src/sdk/front-component/hooks/__tests__/useSelectedRecordsFilter.spec.tsx b/packages/twenty-sdk/src/sdk/front-component/hooks/__tests__/useSelectedRecordsFilter.spec.tsx
new file mode 100644
index 00000000000..372033e5efb
--- /dev/null
+++ b/packages/twenty-sdk/src/sdk/front-component/hooks/__tests__/useSelectedRecordsFilter.spec.tsx
@@ -0,0 +1,61 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { type RecordGqlOperationFilter } from 'twenty-shared/types';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { FRONT_COMPONENT_CONTEXT_KEY } from '@/sdk/front-component/constants/front-component-context-key';
+import { useSelectedRecordsFilter } from '@/sdk/front-component/hooks/useSelectedRecordsFilter';
+import { type FrontComponentExecutionContext } from '@/sdk/front-component/types/FrontComponentExecutionContext';
+
+const EXECUTION_CONTEXT: FrontComponentExecutionContext = {
+ frontComponentId: 'front-component-id',
+ userId: 'user-id',
+ recordId: null,
+ selectedRecordIds: [],
+ timelineActivityId: null,
+ colorScheme: 'light',
+};
+
+const renderUseSelectedRecordsFilter = (
+ executionContext: FrontComponentExecutionContext,
+): RecordGqlOperationFilter | null => {
+ (globalThis as Record<string, unknown>)[FRONT_COMPONENT_CONTEXT_KEY] =
+ executionContext;
+
+ let selectedRecordsFilter: RecordGqlOperationFilter | null = null;
+
+ const SelectedRecordsFilterReader = () => {
+ selectedRecordsFilter = useSelectedRecordsFilter();
+
+ return null;
+ };
+
+ renderToStaticMarkup(<SelectedRecordsFilterReader />);
+
+ return selectedRecordsFilter;
+};
+
+afterEach(() => {
+ delete (globalThis as Record<string, unknown>)[FRONT_COMPONENT_CONTEXT_KEY];
+});
+
+describe('useSelectedRecordsFilter', () => {
+ it('returns null when the host does not provide a selection filter', () => {
+ expect(renderUseSelectedRecordsFilter(EXECUTION_CONTEXT)).toBeNull();
+ });
+
+ it('returns the selection filter provided by the host', () => {
+ const selectAllFilter: RecordGqlOperationFilter = {
+ and: [
+ { name: { ilike: '%acme%' } },
+ { not: { id: { in: ['excluded-record-id'] } } },
+ ],
+ };
+
+ expect(
+ renderUseSelectedRecordsFilter({
+ ...EXECUTION_CONTEXT,
+ selectedRecordsFilter: selectAllFilter,
+ }),
+ ).toEqual(selectAllFilter);
+ });
+});
diff --git a/packages/twenty-sdk/src/sdk/front-component/hooks/useSelectedRecordsFilter.ts b/packages/twenty-sdk/src/sdk/front-component/hooks/useSelectedRecordsFilter.ts
new file mode 100644
index 00000000000..017eb058056
--- /dev/null
+++ b/packages/twenty-sdk/src/sdk/front-component/hooks/useSelectedRecordsFilter.ts
@@ -0,0 +1,12 @@
+import { type RecordGqlOperationFilter } from 'twenty-shared/types';
+
+import { type FrontComponentExecutionContext } from '../types/FrontComponentExecutionContext';
+import { useFrontComponentExecutionContext } from './useFrontComponentExecutionContext';
+
+const selectSelectedRecordsFilter = (
+ context: FrontComponentExecutionContext,
+): RecordGqlOperationFilter | null => context.selectedRecordsFilter ?? null;
+
+export const useSelectedRecordsFilter = (): RecordGqlOperationFilter | null => {
+ return useFrontComponentExecutionContext(selectSelectedRecordsFilter);
+};
diff --git a/packages/twenty-sdk/src/sdk/front-component/index.ts b/packages/twenty-sdk/src/sdk/front-component/index.ts
index 9d9d530c049..2aeb2ed8aa1 100644
--- a/packages/twenty-sdk/src/sdk/front-component/index.ts
+++ b/packages/twenty-sdk/src/sdk/front-component/index.ts
@@ -19,6 +19,7 @@ export { useLocale } from './hooks/useLocale';
export { useRecordId } from './hooks/useRecordId';
export { useToolCall } from './hooks/useToolCall';
export { useSelectedRecordIds } from './hooks/useSelectedRecordIds';
+export { useSelectedRecordsFilter } from './hooks/useSelectedRecordsFilter';
export { useSelectedObjectMetadata } from './hooks/useSelectedObjectMetadata';
export { useTimelineActivityId } from './hooks/useTimelineActivityId';
export { useUserId } from './hooks/useUserId';
diff --git a/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts b/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts
index d0d9a8018a9..866bab59dff 100644
--- a/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts
+++ b/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts
@@ -1,4 +1,5 @@
import { type AppLocale } from 'twenty-shared/translations';
+import { type RecordGqlOperationFilter } from 'twenty-shared/types';
import { type FrontComponentSelectedObjectMetadata } from './FrontComponentSelectedObjectMetadata';
import { type FrontComponentToolCall } from './FrontComponentToolCall';
@@ -12,6 +13,11 @@ export type FrontComponentExecutionContext = {
recordId: string | null;
/** All selected record IDs */
selectedRecordIds: string[];
+ /**
+ * Filter matching exactly the selected records. Under Select all,
+ * `selectedRecordIds` is empty and only this filter describes the selection.
+ */
+ selectedRecordsFilter?: RecordGqlOperationFilter | null;
selectedObjectMetadata?: FrontComponentSelectedObjectMetadata | null;
timelineActivityId: string | null;
/** Resolved color scheme of the host UI ('System' is already resolved) */