Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(table): responsive horizontal scroll + default column min-widths (#2043)

Cindy Zhang9a24cf987aca
diff --git a/apps/storybook/stories/Table.stories.tsx b/apps/storybook/stories/Table.stories.tsx
index 3451a9bf05..6bb65e89dd 100644
--- a/apps/storybook/stories/Table.stories.tsx
+++ b/apps/storybook/stories/Table.stories.tsx
@@ -83,9 +83,9 @@ const users: User[] = [
];
const columns: XDSTableColumn<User>[] = [
- {key: 'name', header: 'Name'},
+ {key: 'name', header: 'Name', width: proportional(1)},
{key: 'email', header: 'Email', width: proportional(2)},
- {key: 'role', header: 'Role'},
+ {key: 'role', header: 'Role', width: proportional(1)},
{key: 'age', header: 'Age', width: pixel(80)},
];
@@ -423,9 +423,9 @@ const containerStoryStyles = stylex.create({
});
const simpleColumns: XDSTableColumn<User>[] = [
- {key: 'name', header: 'Name'},
- {key: 'role', header: 'Role'},
- {key: 'email', header: 'Email'},
+ {key: 'name', header: 'Name', width: proportional(1)},
+ {key: 'role', header: 'Role', width: proportional(1)},
+ {key: 'email', header: 'Email', width: proportional(2)},
];
/**
@@ -789,3 +789,261 @@ export const VerticalAlignment: Story = {
</div>
),
};
+
+interface Employee extends Record<string, unknown> {
+ id: string;
+ name: string;
+ department: string;
+ title: string;
+ location: string;
+ email: string;
+ status: string;
+}
+
+const mobileData: Employee[] = [
+ {
+ id: '1',
+ name: 'Alice Johnson',
+ department: 'Engineering',
+ title: 'Senior Software Engineer',
+ location: 'San Francisco',
+ email: '[email protected]',
+ status: 'Active',
+ },
+ {
+ id: '2',
+ name: 'Bob Martinez',
+ department: 'Product Design',
+ title: 'Lead Product Designer',
+ location: 'New York',
+ email: '[email protected]',
+ status: 'Active',
+ },
+ {
+ id: '3',
+ name: 'Carol Williams',
+ department: 'Data Science',
+ title: 'Staff Data Scientist',
+ location: 'Seattle',
+ email: '[email protected]',
+ status: 'On Leave',
+ },
+];
+
+const mobileColumns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name'},
+ {key: 'department', header: 'Department'},
+ {key: 'title', header: 'Title'},
+ {key: 'location', header: 'Location'},
+ {key: 'email', header: 'Email'},
+ {key: 'status', header: 'Status'},
+];
+
+/**
+ * Demonstrates table behavior in narrow containers (mobile viewports).
+ *
+ * With many columns, the table's minimum width (driven by per-column
+ * minimums) exceeds the container width. Instead of squishing columns
+ * to illegible widths, the table scrolls horizontally.
+ *
+ * Each column — even those without an explicit `width` — gets a default
+ * minimum of 120px, so six columns require at least 720px. In a 320px
+ * container, the table becomes horizontally scrollable.
+ */
+export const ResponsiveScroll: Story = {
+ render: () => (
+ <div style={{display: 'flex', flexDirection: 'column', gap: '32px'}}>
+ <div>
+ <p style={{margin: '0 0 8px', fontWeight: 600}}>
+ 320px container — 6 columns, horizontal scroll
+ </p>
+ <div
+ style={{
+ width: '320px',
+ border: '1px dashed #ccc',
+ borderRadius: '8px',
+ }}>
+ <XDSTable
+ data={mobileData}
+ columns={mobileColumns}
+ idKey="id"
+ dividers="rows"
+ density="compact"
+ textOverflow="truncate"
+ />
+ </div>
+ </div>
+ <div>
+ <p style={{margin: '0 0 8px', fontWeight: 600}}>
+ 480px container — same table, more visible before scroll
+ </p>
+ <div
+ style={{
+ width: '480px',
+ border: '1px dashed #ccc',
+ borderRadius: '8px',
+ }}>
+ <XDSTable
+ data={mobileData}
+ columns={mobileColumns}
+ idKey="id"
+ dividers="rows"
+ density="compact"
+ textOverflow="truncate"
+ />
+ </div>
+ </div>
+ <div>
+ <p style={{margin: '0 0 8px', fontWeight: 600}}>
+ Full width — no scroll needed
+ </p>
+ <XDSTable
+ data={mobileData}
+ columns={mobileColumns}
+ idKey="id"
+ dividers="rows"
+ density="compact"
+ textOverflow="truncate"
+ />
+ </div>
+ </div>
+ ),
+};
+
+/**
+ * Shows horizontal scroll behavior when a table with many columns
+ * is placed inside a Card in a narrow container, verifying that
+ * container bleed and scroll compose correctly.
+ */
+export const ResponsiveScrollInCard: Story = {
+ render: () => (
+ <div
+ style={{
+ width: '360px',
+ border: '1px dashed #ccc',
+ borderRadius: '8px',
+ }}>
+ <XDSCard>
+ <XDSTable
+ data={mobileData}
+ columns={mobileColumns}
+ idKey="id"
+ dividers="rows"
+ density="compact"
+ textOverflow="truncate"
+ />
+ </XDSCard>
+ </div>
+ ),
+};
+
+interface PropEntry extends Record<string, unknown> {
+ name: string;
+ type: string;
+ description: string;
+}
+
+const propData: PropEntry[] = [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'The visible text label for the button.',
+ },
+ {
+ name: 'variant',
+ type: "'primary' | 'secondary' | 'ghost' | 'danger'",
+ description:
+ 'Visual style variant. Primary for main actions, secondary for supporting actions, ghost for minimal emphasis, danger for destructive operations.',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Controls button height, padding, and font size.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description:
+ 'Disables the button, preventing interactions and applying disabled styling.',
+ },
+ {
+ name: 'onClick',
+ type: '(event: MouseEvent) => void',
+ description: 'Callback fired when the button is clicked.',
+ },
+ {
+ name: 'startIcon',
+ type: 'ReactNode',
+ description: 'Icon rendered before the label text.',
+ },
+];
+
+/**
+ * Mirrors the docsite PropsTable pattern: two fixed pixel columns
+ * (Prop name + Type) and a flexible Description column.
+ *
+ * On mobile (320px), the fixed columns consume most of the space,
+ * leaving description unreadable. With horizontal scroll, all three
+ * columns maintain usable widths.
+ */
+export const PropsTablePattern: Story = {
+ render: () => {
+ const cols: XDSTableColumn<PropEntry>[] = [
+ {
+ key: 'name',
+ header: 'Prop',
+ width: pixel(140),
+ renderCell: (item: PropEntry) => (
+ <XDSText type="code" weight="bold">
+ {item.name}
+ </XDSText>
+ ),
+ },
+ {
+ key: 'type',
+ header: 'Type',
+ width: pixel(240),
+ renderCell: (item: PropEntry) => (
+ <XDSText type="code" color="secondary">
+ {item.type}
+ </XDSText>
+ ),
+ },
+ {key: 'description', header: 'Description'},
+ ];
+
+ return (
+ <div style={{display: 'flex', flexDirection: 'column', gap: '32px'}}>
+ <div>
+ <p style={{margin: '0 0 8px', fontWeight: 600}}>
+ 360px — docsite props table on mobile
+ </p>
+ <div
+ style={{
+ width: '360px',
+ border: '1px dashed #ccc',
+ borderRadius: '8px',
+ }}>
+ <XDSTable
+ data={propData}
+ columns={cols}
+ density="spacious"
+ dividers="rows"
+ />
+ </div>
+ </div>
+ <div>
+ <p style={{margin: '0 0 8px', fontWeight: 600}}>
+ Full width — normal desktop experience
+ </p>
+ <XDSTable
+ data={propData}
+ columns={cols}
+ density="spacious"
+ dividers="rows"
+ />
+ </div>
+ </div>
+ );
+ },
+};
diff --git a/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.tsx b/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.tsx
index f6f9c24c8f..3d31adce3b 100644
--- a/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.tsx
+++ b/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.tsx
@@ -5,6 +5,7 @@ import {
XDSTable,
useXDSTableColumnSettings,
useXDSTableColumnSettingsState,
+ proportional,
} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
import {XDSMultiSelector} from '@xds/core/MultiSelector';
@@ -65,11 +66,11 @@ const users: User[] = [
];
const allColumns: XDSTableColumn<User>[] = [
- {key: 'name', header: 'Name'},
- {key: 'email', header: 'Email'},
- {key: 'role', header: 'Role'},
- {key: 'department', header: 'Department'},
- {key: 'status', header: 'Status'},
+ {key: 'name', header: 'Name', width: proportional(1)},
+ {key: 'email', header: 'Email', width: proportional(2)},
+ {key: 'role', header: 'Role', width: proportional(1)},
+ {key: 'department', header: 'Department', width: proportional(1)},
+ {key: 'status', header: 'Status', width: proportional(1)},
];
const columnOptions = [
diff --git a/packages/cli/templates/blocks/components/Table/TableFilterableTable.tsx b/packages/cli/templates/blocks/components/Table/TableFilterableTable.tsx
index b848131d29..8d2804234a 100644
--- a/packages/cli/templates/blocks/components/Table/TableFilterableTable.tsx
+++ b/packages/cli/templates/blocks/components/Table/TableFilterableTable.tsx
@@ -5,6 +5,7 @@ import {
useXDSTableFiltering,
useXDSTableFilterState,
toSearchFilters,
+ proportional,
} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
import {usePowerSearchConfig} from '@xds/core/PowerSearch';
@@ -19,11 +20,41 @@ interface Employee extends Record<string, unknown> {
}
const employees: Employee[] = [
- {id: '1', name: 'Alice', email: '[email protected]', role: 'Engineer', department: 'Platform'},
- {id: '2', name: 'Bob', email: '[email protected]', role: 'Designer', department: 'Product'},
- {id: '3', name: 'Charlie', email: '[email protected]', role: 'Manager', department: 'Platform'},
- {id: '4', name: 'Diana', email: '[email protected]', role: 'Engineer', department: 'Infrastructure'},
- {id: '5', name: 'Eve', email: '[email protected]', role: 'Admin', department: 'Operations'},
+ {
+ id: '1',
+ name: 'Alice',
+ email: '[email protected]',
+ role: 'Engineer',
+ department: 'Platform',
+ },
+ {
+ id: '2',
+ name: 'Bob',
+ email: '[email protected]',
+ role: 'Designer',
+ department: 'Product',
+ },
+ {
+ id: '3',
+ name: 'Charlie',
+ email: '[email protected]',
+ role: 'Manager',
+ department: 'Platform',
+ },
+ {
+ id: '4',
+ name: 'Diana',
+ email: '[email protected]',
+ role: 'Engineer',
+ department: 'Infrastructure',
+ },
+ {
+ id: '5',
+ name: 'Eve',
+ email: '[email protected]',
+ role: 'Admin',
+ department: 'Operations',
+ },
];
const fieldDefs = [
@@ -43,10 +74,10 @@ const fieldDefs = [
] as const;
const columns: XDSTableColumn<Employee>[] = [
- {key: 'name', header: 'Name', filter: 'name'},
- {key: 'email', header: 'Email', filter: 'email'},
- {key: 'role', header: 'Role', filter: 'role'},
- {key: 'department', header: 'Department'},
+ {key: 'name', header: 'Name', width: proportional(1), filter: 'name'},
+ {key: 'email', header: 'Email', width: proportional(2), filter: 'email'},
+ {key: 'role', header: 'Role', width: proportional(1), filter: 'role'},
+ {key: 'department', header: 'Department', width: proportional(1)},
];
export default function TableFilterableTable() {
diff --git a/packages/cli/templates/blocks/components/Table/TableInCard.tsx b/packages/cli/templates/blocks/components/Table/TableInCard.tsx
index a950f6d74a..04e127d7ec 100644
--- a/packages/cli/templates/blocks/components/Table/TableInCard.tsx
+++ b/packages/cli/templates/blocks/components/Table/TableInCard.tsx
@@ -1,6 +1,6 @@
'use client';
-import {XDSTable} from '@xds/core/Table';
+import {XDSTable, proportional} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
import {XDSCard} from '@xds/core/Card';
import {XDSVStack} from '@xds/core/Layout';
@@ -14,16 +14,21 @@ interface User extends Record<string, unknown> {
}
const users: User[] = [
- {id: '1', name: 'Alice Johnson', role: 'Engineer', email: '[email protected]'},
+ {
+ id: '1',
+ name: 'Alice Johnson',
+ role: 'Engineer',
+ email: '[email protected]',
+ },
{id: '2', name: 'Bob Smith', role: 'Designer', email: '[email protected]'},
{id: '3', name: 'Charlie Brown', role: 'PM', email: '[email protected]'},
{id: '4', name: 'Diana Prince', role: 'Engineer', email: '[email protected]'},
];
const columns: XDSTableColumn<User>[] = [
- {key: 'name', header: 'Name'},
- {key: 'role', header: 'Role'},
- {key: 'email', header: 'Email'},
+ {key: 'name', header: 'Name', width: proportional(1)},
+ {key: 'role', header: 'Role', width: proportional(1)},
+ {key: 'email', header: 'Email', width: proportional(2)},
];
export default function TableInCard() {
diff --git a/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.tsx b/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.tsx
index 820ae74b96..46ccc9e7d2 100644
--- a/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.tsx
+++ b/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.tsx
@@ -5,6 +5,7 @@ import {
useXDSTableFiltering,
useXDSTableFilterState,
toSearchFilters,
+ proportional,
} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
import {usePowerSearchConfig} from '@xds/core/PowerSearch';
@@ -73,10 +74,10 @@ const fieldDefs = [
] as const;
const columns: XDSTableColumn<Employee>[] = [
- {key: 'name', header: 'Name', filter: 'name'},
- {key: 'email', header: 'Email', filter: 'email'},
- {key: 'role', header: 'Role', filter: 'role'},
- {key: 'department', header: 'Department'},
+ {key: 'name', header: 'Name', width: proportional(1), filter: 'name'},
+ {key: 'email', header: 'Email', width: proportional(2), filter: 'email'},
+ {key: 'role', header: 'Role', width: proportional(1), filter: 'role'},
+ {key: 'department', header: 'Department', width: proportional(1)},
];
export default function TableInlineFilterTable() {
diff --git a/packages/cli/templates/blocks/components/Table/TablePaginatedTable.tsx b/packages/cli/templates/blocks/components/Table/TablePaginatedTable.tsx
index 3a165bf480..318fdbc335 100644
--- a/packages/cli/templates/blocks/components/Table/TablePaginatedTable.tsx
+++ b/packages/cli/templates/blocks/components/Table/TablePaginatedTable.tsx
@@ -1,7 +1,12 @@
'use client';
import {useState} from 'react';
-import {XDSTable, useXDSTablePagination, paginateData} from '@xds/core/Table';
+import {
+ XDSTable,
+ useXDSTablePagination,
+ paginateData,
+ proportional,
+} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
import {XDSSection} from '@xds/core/Section';
@@ -45,9 +50,9 @@ const users: User[] = names.map((name, i) => ({
}));
const columns: XDSTableColumn<User>[] = [
- {key: 'name', header: 'Name'},
- {key: 'email', header: 'Email'},
- {key: 'role', header: 'Role'},
+ {key: 'name', header: 'Name', width: proportional(1)},
+ {key: 'email', header: 'Email', width: proportional(2)},
+ {key: 'role', header: 'Role', width: proportional(1)},
];
export default function TablePaginatedTable() {
diff --git a/packages/cli/templates/blocks/components/Table/TableSelectableTable.tsx b/packages/cli/templates/blocks/components/Table/TableSelectableTable.tsx
index 6463eaeff6..4020308d03 100644
--- a/packages/cli/templates/blocks/components/Table/TableSelectableTable.tsx
+++ b/packages/cli/templates/blocks/components/Table/TableSelectableTable.tsx
@@ -5,6 +5,7 @@ import {
XDSTable,
useXDSTableSelection,
useXDSTableSelectionState,
+ proportional,
} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
@@ -24,9 +25,9 @@ const users: User[] = [
];
const columns: XDSTableColumn<User>[] = [
- {key: 'name', header: 'Name'},
- {key: 'email', header: 'Email'},
- {key: 'role', header: 'Role'},
+ {key: 'name', header: 'Name', width: proportional(1)},
+ {key: 'email', header: 'Email', width: proportional(2)},
+ {key: 'role', header: 'Role', width: proportional(1)},
];
export default function TableSelectableTable() {
diff --git a/packages/cli/templates/blocks/components/Table/TableShowcase.tsx b/packages/cli/templates/blocks/components/Table/TableShowcase.tsx
index 0c7dbe6678..0ac67c050e 100644
--- a/packages/cli/templates/blocks/components/Table/TableShowcase.tsx
+++ b/packages/cli/templates/blocks/components/Table/TableShowcase.tsx
@@ -13,15 +13,33 @@ interface User extends Record<string, unknown> {
}
const users: User[] = [
- {id: '1', name: 'Alice Johnson', email: '[email protected]', role: 'Engineer', age: 30},
- {id: '2', name: 'Bob Smith', email: '[email protected]', role: 'Designer', age: 25},
- {id: '3', name: 'Charlie Brown', email: '[email protected]', role: 'PM', age: 35},
+ {
+ id: '1',
+ name: 'Alice Johnson',
+ email: '[email protected]',
+ role: 'Engineer',
+ age: 30,
+ },
+ {
+ id: '2',
+ name: 'Bob Smith',
+ email: '[email protected]',
+ role: 'Designer',
+ age: 25,
+ },
+ {
+ id: '3',
+ name: 'Charlie Brown',
+ email: '[email protected]',
+ role: 'PM',
+ age: 35,
+ },
];
const columns: XDSTableColumn<User>[] = [
- {key: 'name', header: 'Name'},
+ {key: 'name', header: 'Name', width: proportional(1)},
{key: 'email', header: 'Email', width: proportional(2)},
- {key: 'role', header: 'Role'},
+ {key: 'role', header: 'Role', width: proportional(1)},
{key: 'age', header: 'Age', width: pixel(80)},
];
diff --git a/packages/cli/templates/blocks/components/Table/TableSortableTable.tsx b/packages/cli/templates/blocks/components/Table/TableSortableTable.tsx
index 3db20ee459..64c239cffa 100644
--- a/packages/cli/templates/blocks/components/Table/TableSortableTable.tsx
+++ b/packages/cli/templates/blocks/components/Table/TableSortableTable.tsx
@@ -4,6 +4,8 @@ import {
XDSTable,
useXDSTableSortable,
useXDSTableSortableState,
+ proportional,
+ pixel,
} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
@@ -16,18 +18,36 @@ interface Employee extends Record<string, unknown> {
}
const employees: Employee[] = [
- {id: '1', name: 'Alice', email: '[email protected]', role: 'Engineer', age: 32},
+ {
+ id: '1',
+ name: 'Alice',
+ email: '[email protected]',
+ role: 'Engineer',
+ age: 32,
+ },
{id: '2', name: 'Bob', email: '[email protected]', role: 'Designer', age: 28},
- {id: '3', name: 'Charlie', email: '[email protected]', role: 'Manager', age: 45},
- {id: '4', name: 'Diana', email: '[email protected]', role: 'Engineer', age: 37},
+ {
+ id: '3',
+ name: 'Charlie',
+ email: '[email protected]',
+ role: 'Manager',
+ age: 45,
+ },
+ {
+ id: '4',
+ name: 'Diana',
+ email: '[email protected]',
+ role: 'Engineer',
+ age: 37,
+ },
{id: '5', name: 'Eve', email: '[email protected]', role: 'Admin', age: 29},
];
const columns: XDSTableColumn<Employee>[] = [
- {key: 'name', header: 'Name', sortable: true},
- {key: 'email', header: 'Email', sortable: true},
- {key: 'role', header: 'Role', sortable: true},
- {key: 'age', header: 'Age', sortable: true},
+ {key: 'name', header: 'Name', width: proportional(1), sortable: true},
+ {key: 'email', header: 'Email', width: proportional(2), sortable: true},
+ {key: 'role', header: 'Role', width: proportional(1), sortable: true},
+ {key: 'age', header: 'Age', width: pixel(80), sortable: true},
];
export default function TableSortableTable() {
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 1c6782445f..f6a6397970 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -428,8 +428,10 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
{ guidance: true, description: 'Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell.' },
+ { guidance: true, description: 'Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum.' },
{ guidance: false, description: 'Use a table for data without consistent columns — use a list or card layout for heterogeneous content.' },
{ guidance: false, description: 'Enable every plugin at once — add only the features your use case requires to keep the interface focused.' },
+ { guidance: false, description: 'Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },
],
anatomy: [
{name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
diff --git a/packages/core/src/Table/XDSBaseTable.tsx b/packages/core/src/Table/XDSBaseTable.tsx
index 5e262dbdef..429add6086 100644
--- a/packages/core/src/Table/XDSBaseTable.tsx
+++ b/packages/core/src/Table/XDSBaseTable.tsx
@@ -266,6 +266,7 @@ function XDSBaseTableInner<T extends Record<string, unknown>>({
children,
tableProps: userTableProps,
textOverflow = 'wrap',
+ scrollWrapper: ScrollWrapper,
emptyState,
ref,
}: XDSBaseTableProps<T> & {ref?: Ref<HTMLTableElement>}): ReactElement {
@@ -470,6 +471,14 @@ function XDSBaseTableInner<T extends Record<string, unknown>>({
</table>
);
+ // Wrap the <table> in a scroll container so it scrolls horizontally
+ // when columns exceed the container width. This wrapper sits between
+ // the <table> and transformTableContext, so plugin chrome (pagination,
+ // toolbars) renders outside the scroll area.
+ if (ScrollWrapper) {
+ tableElement = <ScrollWrapper>{tableElement}</ScrollWrapper>;
+ }
+
// Apply transformTableContext from each plugin.
// Iterates in reverse so the first plugin in the array wraps outermost,
// matching the mental model: plugins are listed in priority order, and
diff --git a/packages/core/src/Table/XDSTable.test.tsx b/packages/core/src/Table/XDSTable.test.tsx
index edb644a613..2e4b26d940 100644
--- a/packages/core/src/Table/XDSTable.test.tsx
+++ b/packages/core/src/Table/XDSTable.test.tsx
@@ -542,6 +542,14 @@ describe('XDSTable', () => {
expect(screen.getAllByRole('row')).toHaveLength(4);
});
+ it('wraps table in a scroll container', () => {
+ render(<XDSTable data={users} columns={columns} />);
+ const table = screen.getByRole('table');
+ const wrapper = table.parentElement;
+ expect(wrapper).toBeTruthy();
+ expect(wrapper!.className).toContain('xds-table-scroll-wrapper');
+ });
+
it('renders all data values', () => {
render(<XDSTable data={users} columns={columns} />);
expect(screen.getByText('Alice')).toBeInTheDocument();
diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsx
index 23648365e6..c4862d6ada 100644
--- a/packages/core/src/Table/XDSTable.tsx
+++ b/packages/core/src/Table/XDSTable.tsx
@@ -23,7 +23,7 @@ import {XDSTableCell} from './XDSTableCell';
import {XDSTableHeaderCell} from './XDSTableHeaderCell';
import {XDSTableContext} from './XDSTableContext';
import {useXDSBaseTablePlugins} from './useXDSBaseTablePlugins';
-import {xdsClassName} from '../utils';
+import {xdsClassName, mergeProps} from '../utils';
import type {
XDSBaseTableProps,
XDSTableVerticalAlign,
@@ -111,13 +111,13 @@ const tableStyles = stylex.create({
fontFamily: 'inherit',
color: colorVars['--color-text-primary'],
},
- /**
- * Container bleed: table escapes parent container padding
- * so rows span edge-to-edge inside Cards and Layout areas.
- *
- * Inline bleed uses --container-padding-inline-start/end set by containers.
- * Block bleed uses --container-padding-block-start/end for :first-child / :last-child.
- */
+});
+
+const scrollWrapperStyles = stylex.create({
+ base: {
+ overflowX: 'auto',
+ WebkitOverflowScrolling: 'touch',
+ },
containerBleed: {
marginInlineStart: 'calc(-1 * var(--container-padding-inline-start, 0px))',
marginInlineEnd: 'calc(-1 * var(--container-padding-inline-end, 0px))',
@@ -134,6 +134,21 @@ const tableStyles = stylex.create({
},
});
+function TableScrollWrapper({children}: {children: React.ReactNode}) {
+ return (
+ <div
+ {...mergeProps(
+ xdsClassName('table-scroll-wrapper'),
+ stylex.props(
+ scrollWrapperStyles.base,
+ scrollWrapperStyles.containerBleed,
+ ),
+ )}>
+ {children}
+ </div>
+ );
+}
+
// =============================================================================
// Table-level styling plugin (only transforms the <table> element)
// =============================================================================
@@ -153,7 +168,7 @@ function buildTableStylePlugin<
? `${existingClass} ${tableClass}`
: tableClass,
},
- styles: [...props.styles, tableStyles.base, tableStyles.containerBleed],
+ styles: [...props.styles, tableStyles.base],
};
},
};
@@ -215,6 +230,7 @@ function XDSTableInner<T extends Record<string, unknown>>({
plugins={mergedPlugins}
components={xdsComponents}
textOverflow={textOverflow}
+ scrollWrapper={TableScrollWrapper}
{...rest}
/>
</XDSTableContext.Provider>
@@ -233,19 +249,21 @@ function XDSTableInner<T extends Record<string, unknown>>({
* Combine with XDSBadge (status labels), XDSStatusDot (colored indicators),
* XDSText (formatted values), XDSAvatar (user cells), and XDSHStack/XDSVStack
* (multi-element cell layouts). Without renderCell, cells render as plain text.
+ * Always set explicit width on columns using proportional() or pixel() — omitting
+ * width skips the minimum width floor, which can cause columns to collapse on mobile.
*
* @example
* ```
* <XDSTable
* data={users}
* columns={[
- * { key: 'name', header: 'Name', renderCell: (u) => (
+ * { key: 'name', header: 'Name', width: proportional(1), renderCell: (u) => (
* <XDSHStack gap={2} align="center">
* <XDSAvatar name={u.name} size="small" />
* <XDSText weight="semibold">{u.name}</XDSText>
* </XDSHStack>
* )},
- * { key: 'status', header: 'Status', renderCell: (u) => (
+ * { key: 'status', header: 'Status', width: proportional(1), renderCell: (u) => (
* <XDSBadge variant={u.active ? 'success' : 'error'} label={u.active ? 'Active' : 'Inactive'} />
* )},
* ]}
diff --git a/packages/core/src/Table/columnUtils.ts b/packages/core/src/Table/columnUtils.ts
index 3171d3b5b7..033442627d 100644
--- a/packages/core/src/Table/columnUtils.ts
+++ b/packages/core/src/Table/columnUtils.ts
@@ -72,7 +72,8 @@ export function resolveColumnWidths<T extends Record<string, unknown>>(
} else {
const proportion = w?.value ?? 1;
// Only count minWidth for columns that explicitly used proportional().
- // Columns with no width set (w === undefined) have no minimum.
+ // Columns with no width set (w === undefined) have no minimum —
+ // they flex freely and the scroll wrapper handles overflow.
const minW = w != null ? (w.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH) : 0;
totalProportion += proportion;
proportionalCols.push({key: col.key, proportion, minWidth: minW});
@@ -109,7 +110,8 @@ export function resolveColumnWidths<T extends Record<string, unknown>>(
style.width = `${(proportion / totalProportion) * 100}%`;
}
// Only apply minWidth if the column explicitly used proportional().
- // Columns with no width set (w === undefined) have no minimum.
+ // Columns with no width set (w === undefined) have no minimum —
+ // they flex freely and the scroll wrapper handles overflow.
if (w != null) {
const minW = w.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH;
style.minWidth = `${minW}px`;
diff --git a/packages/core/src/Table/types.ts b/packages/core/src/Table/types.ts
index de5710ae9a..49b9f6196c 100644
--- a/packages/core/src/Table/types.ts
+++ b/packages/core/src/Table/types.ts
@@ -104,7 +104,24 @@ export interface XDSTableColumn<T extends Record<string, unknown>> {
key: string;
/** Header text displayed in `<th>`. Defaults to capitalized `key`. */
header?: ReactNode;
- /** Column width. Defaults to `proportional(1)`. */
+ /**
+ * Column width. Use `proportional()` for flexible columns or `pixel()` for fixed.
+ *
+ * - `proportional(1)` — shares space equally with other proportional columns.
+ * Enforces a 120px minimum width to prevent squishing on narrow viewports.
+ * - `proportional(2)` — gets twice the space of `proportional(1)`.
+ * - `pixel(200)` — fixed 200px width.
+ * - Omitted — treated as `proportional(1)` for distribution, but with **no**
+ * minimum width. Prefer explicit `proportional(1)` for text-heavy columns
+ * so they don't collapse on mobile.
+ *
+ * @example
+ * ```
+ * { key: 'name', header: 'Name', width: proportional(1) }
+ * { key: 'bio', header: 'Bio', width: proportional(2) }
+ * { key: 'age', header: 'Age', width: pixel(80) }
+ * ```
+ */
width?: ColumnWidth;
/**
* Horizontal text alignment for this column.
@@ -370,6 +387,13 @@ export interface XDSBaseTableProps<T extends Record<string, unknown>> {
children?: ReactNode;
/** Additional HTML attributes for the `<table>` element */
tableProps?: HTMLAttributes<HTMLTableElement>;
+ /**
+ * Optional wrapper rendered around the `<table>` element, inside the
+ * plugin `transformTableContext` layer. Used by `XDSTable` to add a
+ * horizontal scroll container so plugin chrome (pagination, toolbars)
+ * stays outside the scrollable area.
+ */
+ scrollWrapper?: ComponentType<{children: ReactNode}>;
/**
* How default-rendered body cell text behaves when it exceeds column width.
*