Skip to content

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

TypeScript

feat(table): add textOverflow prop — wrap by default, truncate with tooltips (#1986)

Cindy Zhang694e8420139c
diff --git a/apps/storybook/stories/Table.stories.tsx b/apps/storybook/stories/Table.stories.tsx
index 9aebf2cf3b..3451a9bf05 100644
--- a/apps/storybook/stories/Table.stories.tsx
+++ b/apps/storybook/stories/Table.stories.tsx
@@ -327,74 +327,67 @@ export const KitchenSink: Story = {
// =============================================================================
interface OverflowRow extends Record<string, unknown> {
- column: string;
- truncated: string;
- wrapped: string;
+ scenario: string;
+ content: string;
}
const overflowData: OverflowRow[] = [
{
- column: 'Default (truncate)',
- truncated:
- 'a_very_long_string_like_this_that_overflows_the_column_without_spaces',
- wrapped:
- 'a_very_long_string_like_this_that_overflows_the_column_without_spaces',
+ scenario: 'Long unbroken string',
+ content:
+ 'a_very_long_string_like_this_that_overflows_the_column_without_any_spaces_or_hyphens',
},
{
- column: 'Normal prose',
- truncated:
- 'This is a longer sentence that will also get clipped by the ellipsis when it runs out of room.',
- wrapped:
- 'This is a longer sentence that wraps naturally onto the next line when it runs out of room.',
+ scenario: 'Normal prose',
+ content:
+ 'This is a longer sentence that might wrap or truncate depending on the textOverflow setting of the table.',
+ },
+ {
+ scenario: 'Short text',
+ content: 'Fits fine.',
},
];
/**
- * Cells truncate overflow with an ellipsis by default.
- * The default renderer adds a native title tooltip so truncated text
- * is still accessible on hover.
- *
- * For the full XDS tooltip experience (only shows when actually truncated),
- * use renderCell with <XDSText maxLines={1}>.
- *
- * The "Wrapped" column shows how consumers can opt into wrapping
- * via renderCell with white-space: normal and overflow: visible.
+ * Text wraps by default — rows grow taller and no content is hidden.
+ * Set `textOverflow="truncate"` for dense data tables where fixed row
+ * height matters. In truncate mode, default-rendered cells show a
+ * tooltip on hover when text is actually overflowing.
*/
export const OverflowBehavior: Story = {
render: () => {
const cols: XDSTableColumn<OverflowRow>[] = [
- {key: 'column', header: 'Row', width: pixel(140)},
- {
- key: 'truncated',
- header: 'Truncated (default)',
- width: proportional(1),
- },
- {
- key: 'wrapped',
- header: 'Wrapped (xstyle override)',
- width: proportional(1),
- renderCell: item => (
- <span
- style={{
- whiteSpace: 'normal',
- overflow: 'visible',
- wordBreak: 'break-word',
- display: 'block',
- }}>
- {item.wrapped}
- </span>
- ),
- },
+ {key: 'scenario', header: 'Scenario', width: pixel(160)},
+ {key: 'content', header: 'Content', width: proportional(1)},
];
return (
- <div style={{width: '640px'}}>
- <XDSTable
- data={overflowData}
- columns={cols}
- dividers="grid"
- density="balanced"
- />
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '32px',
+ width: '480px',
+ }}>
+ <div>
+ <h4 style={{margin: '0 0 8px'}}>Wrap (default)</h4>
+ <XDSTable
+ data={overflowData}
+ columns={cols}
+ dividers="grid"
+ density="balanced"
+ />
+ </div>
+ <div>
+ <h4 style={{margin: '0 0 8px'}}>Truncate (with tooltip on hover)</h4>
+ <XDSTable
+ data={overflowData}
+ columns={cols}
+ dividers="grid"
+ density="balanced"
+ textOverflow="truncate"
+ />
+ </div>
</div>
);
},
diff --git a/packages/core/src/Table/XDSBaseTable.tsx b/packages/core/src/Table/XDSBaseTable.tsx
index d833b0efc4..5e262dbdef 100644
--- a/packages/core/src/Table/XDSBaseTable.tsx
+++ b/packages/core/src/Table/XDSBaseTable.tsx
@@ -38,6 +38,7 @@ import {XDSTableCell} from './XDSTableCell';
import {XDSTableHeaderCell} from './XDSTableHeaderCell';
import {xdsClassName, mergeProps} from '../utils';
import {XDSEmptyState} from '../EmptyState';
+import {XDSText} from '../Text';
const styles = stylex.create({
table: {
@@ -114,6 +115,7 @@ interface TableRowProps<T extends Record<string, unknown>> {
rowKey: string | number;
columns: XDSTableColumn<T>[];
plugins: TablePlugin<T>[];
+ textOverflow: 'wrap' | 'truncate';
RowComponent: React.ComponentType<TableRowComponentProps>;
CellComponent: React.ComponentType<TableCellComponentProps>;
}
@@ -129,6 +131,7 @@ function TableRowInner<T extends Record<string, unknown>>({
rowKey,
columns,
plugins,
+ textOverflow,
RowComponent,
CellComponent,
}: TableRowProps<T>): ReactElement {
@@ -148,23 +151,35 @@ function TableRowInner<T extends Record<string, unknown>>({
item,
);
- const content = col.renderCell
- ? col.renderCell(item)
- : defaultCellRenderer(item, col.key);
-
- // Default renderer: add title so truncated text is accessible on hover.
- // For the full XDS tooltip experience, use renderCell with
- // <XDSText maxLines={1}> — the title attr is the zero-cost safety net.
- const titleProp =
- !col.renderCell && typeof content === 'string' && content.length > 0
- ? {title: content}
- : {};
+ const isDefaultRenderer = !col.renderCell;
+ const rawContent = isDefaultRenderer
+ ? defaultCellRenderer(item, col.key)
+ : col.renderCell!(item);
+
+ // In truncate mode, wrap default-rendered string content in
+ // <XDSText maxLines={1}> for smart tooltips that only appear
+ // when text is actually overflowing. In wrap mode (default),
+ // content renders as-is — the cell's CSS handles wrapping.
+ let content: ReactNode;
+ if (
+ isDefaultRenderer &&
+ textOverflow === 'truncate' &&
+ typeof rawContent === 'string' &&
+ rawContent.length > 0
+ ) {
+ content = (
+ <XDSText type="body" maxLines={1}>
+ {rawContent}
+ </XDSText>
+ );
+ } else {
+ content = rawContent;
+ }
return (
<CellComponent
key={col.key}
{...cellRenderProps.htmlProps}
- {...titleProp}
xstyle={cellRenderProps.styles}>
{content}
</CellComponent>
@@ -207,9 +222,9 @@ function areRowPropsEqual<T extends Record<string, unknown>>(
if (prevProps.rowKey !== nextProps.rowKey) return false;
if (prevProps.rowIndex !== nextProps.rowIndex) return false;
- // If columns, plugins, or components change, need to re-render all rows
if (prevProps.columns !== nextProps.columns) return false;
if (prevProps.plugins !== nextProps.plugins) return false;
+ if (prevProps.textOverflow !== nextProps.textOverflow) return false;
if (prevProps.RowComponent !== nextProps.RowComponent) return false;
if (prevProps.CellComponent !== nextProps.CellComponent) return false;
@@ -250,6 +265,7 @@ function XDSBaseTableInner<T extends Record<string, unknown>>({
components,
children,
tableProps: userTableProps,
+ textOverflow = 'wrap',
emptyState,
ref,
}: XDSBaseTableProps<T> & {ref?: Ref<HTMLTableElement>}): ReactElement {
@@ -436,6 +452,7 @@ function XDSBaseTableInner<T extends Record<string, unknown>>({
rowKey={rowKey}
columns={resolvedColumns}
plugins={plugins}
+ textOverflow={textOverflow}
RowComponent={RowComponent}
CellComponent={CellComponent}
/>
diff --git a/packages/core/src/Table/XDSTable.test.tsx b/packages/core/src/Table/XDSTable.test.tsx
index 6173cdd0d4..edb644a613 100644
--- a/packages/core/src/Table/XDSTable.test.tsx
+++ b/packages/core/src/Table/XDSTable.test.tsx
@@ -707,15 +707,14 @@ describe('XDSTable', () => {
it('applies overflow truncation styles to body cells', () => {
// text-overflow: ellipsis + overflow: hidden + white-space: nowrap are applied
- // via StyleX class names. We verify a class is present on the cell; the actual
- // CSS rendering is covered by visual/e2e tests (jsdom doesn't compute layout).
+ // via StyleX class names when textOverflow="truncate".
const longData = [
{
name: 'a_very_long_string_without_spaces_that_would_overflow_a_fixed_width_column',
value: '42',
},
];
- render(<XDSTable data={longData} />);
+ render(<XDSTable data={longData} textOverflow="truncate" />);
const cell = screen.getAllByRole('cell')[0];
// Cell should have at least one StyleX-generated class applied
expect(cell.className.length).toBeGreaterThan(0);
@@ -725,29 +724,37 @@ describe('XDSTable', () => {
);
});
- it('sets title attribute on default-rendered cells for overflow accessibility', () => {
+ it('wraps text by default (textOverflow="wrap")', () => {
render(<XDSTable data={users} columns={columns} />);
const cells = screen.getAllByRole('cell');
- // Default renderer adds title for native hover tooltip on truncated text
- expect(cells[0]).toHaveAttribute('title', 'Alice');
- expect(cells[1]).toHaveAttribute('title', '30');
+ // In wrap mode, no title attribute is added (text is visible, not hidden)
+ expect(cells[0]).not.toHaveAttribute('title');
+ // Content is present
+ expect(cells[0]).toHaveTextContent('Alice');
+ });
+
+ it('wraps default-rendered cells in XDSText when textOverflow="truncate"', () => {
+ render(<XDSTable data={users} columns={columns} textOverflow="truncate" />);
+ const cells = screen.getAllByRole('cell');
+ // Default-rendered cells contain an XDSText child element (a <span>)
+ const textEl = cells[0].querySelector('span');
+ expect(textEl).toBeTruthy();
+ expect(textEl).toHaveTextContent('Alice');
});
- it('does not set title attribute on renderCell columns', () => {
+ it('does not wrap renderCell content in XDSText when truncating', () => {
const cols: XDSTableColumn<User>[] = [
{
key: 'name',
header: 'Name',
- renderCell: item => <span>{item.name}</span>,
+ renderCell: item => <span data-testid="custom">{item.name}</span>,
},
{key: 'email', header: 'Email'},
];
- render(<XDSTable data={users} columns={cols} />);
- const cells = screen.getAllByRole('cell');
- // renderCell column: consumer owns disclosure
- expect(cells[0]).not.toHaveAttribute('title');
- // default column: title present
- expect(cells[1]).toHaveAttribute('title', users[0].email);
+ render(<XDSTable data={users} columns={cols} textOverflow="truncate" />);
+ // Custom renderCell: consumer owns the content
+ const customCells = screen.getAllByTestId('custom');
+ expect(customCells[0]).toHaveTextContent('Alice');
});
it('sets title attribute on string header cells', () => {
diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsx
index fe57e2428a..23648365e6 100644
--- a/packages/core/src/Table/XDSTable.tsx
+++ b/packages/core/src/Table/XDSTable.tsx
@@ -46,6 +46,10 @@ export type XDSTableDensity = 'compact' | 'balanced' | 'spacious';
export type XDSTableDividers = 'rows' | 'columns' | 'grid' | 'none';
+/** How body cell text behaves when it exceeds column width */
+
+export type XDSTableTextOverflow = 'wrap' | 'truncate';
+
/**
* Props for the styled XDSTable component.
* Supports both data-driven mode and children mode with XDSTableRow/Cell.
@@ -77,6 +81,23 @@ export interface XDSTableProps<T extends Record<string, unknown>> extends Omit<
* ```
*/
verticalAlign?: XDSTableVerticalAlign;
+ /**
+ * How body cell text behaves when it exceeds the column width.
+ *
+ * - `'wrap'` — text wraps and the row grows taller. No content is hidden.
+ * - `'truncate'` — text is clipped with an ellipsis. Default-rendered cells
+ * show a tooltip on hover when truncated.
+ *
+ * Header cells always truncate regardless of this setting.
+ *
+ * @default 'wrap'
+ *
+ * @example
+ * ```
+ * <XDSTable data={logs} columns={columns} textOverflow="truncate" />
+ * ```
+ */
+ textOverflow?: 'wrap' | 'truncate';
/** Named plugins to extend table behavior */
plugins?: Record<string, TablePlugin<T>>;
}
@@ -159,6 +180,7 @@ function XDSTableInner<T extends Record<string, unknown>>({
isStriped = false,
hasHover = false,
verticalAlign = 'middle',
+ textOverflow = 'wrap',
plugins: userPlugins,
columns,
data,
@@ -173,8 +195,15 @@ function XDSTableInner<T extends Record<string, unknown>>({
const mergedPlugins = useXDSBaseTablePlugins<T>(basePlugins, userPlugins);
const contextValue = useMemo(
- () => ({density, dividers, isStriped, hasHover, verticalAlign}),
- [density, dividers, isStriped, hasHover, verticalAlign],
+ () => ({
+ density,
+ dividers,
+ isStriped,
+ hasHover,
+ verticalAlign,
+ textOverflow,
+ }),
+ [density, dividers, isStriped, hasHover, verticalAlign, textOverflow],
);
return (
@@ -185,6 +214,7 @@ function XDSTableInner<T extends Record<string, unknown>>({
columns={columns}
plugins={mergedPlugins}
components={xdsComponents}
+ textOverflow={textOverflow}
{...rest}
/>
</XDSTableContext.Provider>
diff --git a/packages/core/src/Table/XDSTableCell.tsx b/packages/core/src/Table/XDSTableCell.tsx
index 42e4012280..9fc3b08276 100644
--- a/packages/core/src/Table/XDSTableCell.tsx
+++ b/packages/core/src/Table/XDSTableCell.tsx
@@ -24,6 +24,7 @@ import {
import type {StyleXStyles} from '../theme/types';
import {
overflowStyles,
+ wrapStyles,
containerEdgeStyles,
tableRowMarker,
} from './table.stylex';
@@ -152,7 +153,7 @@ export function XDSTableCell({
const cellStyles: StyleXStyles[] = [
densityStyles[ctx.density],
- overflowStyles.cell,
+ ctx.textOverflow === 'truncate' ? overflowStyles.cell : wrapStyles.cell,
containerEdgeStyles[ctx.density],
verticalAlignStyles[ctx.verticalAlign],
...buildDividerStyles(ctx, dividerRowStyles.cell, dividerColumnStyles.cell),
diff --git a/packages/core/src/Table/XDSTableContext.ts b/packages/core/src/Table/XDSTableContext.ts
index 2910a14bcf..cf56ff20fa 100644
--- a/packages/core/src/Table/XDSTableContext.ts
+++ b/packages/core/src/Table/XDSTableContext.ts
@@ -22,6 +22,7 @@ export interface XDSTableContextValue {
isStriped: boolean;
hasHover: boolean;
verticalAlign: XDSTableVerticalAlign;
+ textOverflow: 'wrap' | 'truncate';
}
export const XDSTableContext = createContext<XDSTableContextValue | null>(null);
diff --git a/packages/core/src/Table/index.ts b/packages/core/src/Table/index.ts
index 647f0a4685..8417dae2b9 100644
--- a/packages/core/src/Table/index.ts
+++ b/packages/core/src/Table/index.ts
@@ -58,6 +58,7 @@ export type {
XDSTableProps,
XDSTableDensity,
XDSTableDividers,
+ XDSTableTextOverflow,
} from './XDSTable';
export type {XDSTableRowProps} from './XDSTableRow';
export type {XDSTableCellProps} from './XDSTableCell';
diff --git a/packages/core/src/Table/table.stylex.ts b/packages/core/src/Table/table.stylex.ts
index 0ed5fd2793..b827fa134f 100644
--- a/packages/core/src/Table/table.stylex.ts
+++ b/packages/core/src/Table/table.stylex.ts
@@ -26,10 +26,10 @@ export const tableRowMarker: ReturnType<typeof stylex.defineMarker> =
/**
* Overflow truncation for table cells.
*
- * Applied at the <td>/<th> level as a CSS safety net. For data-driven
- * tables, the default renderer also adds a title attribute so truncated
- * text is accessible on hover. For the full XDS tooltip experience,
- * use renderCell with <XDSText maxLines={1}>.
+ * Applied at the <td>/<th> level when textOverflow is 'truncate'.
+ * For data-driven tables in truncate mode, the default renderer wraps
+ * content in <XDSText maxLines={1}> for smart tooltips that only appear
+ * when text is actually overflowing.
*/
export const overflowStyles = stylex.create({
cell: {
@@ -40,6 +40,21 @@ export const overflowStyles = stylex.create({
},
});
+/**
+ * Wrap styles for table cells.
+ *
+ * Applied at the <td>/<th> level when textOverflow is 'wrap' (the default).
+ * Text wraps naturally and the row grows taller to fit. No content is hidden.
+ */
+export const wrapStyles = stylex.create({
+ cell: {
+ overflow: 'hidden',
+ overflowWrap: 'break-word',
+ wordBreak: 'break-word',
+ maxWidth: '0',
+ },
+});
+
/**
* Container edge compensation for table cells.
*
diff --git a/packages/core/src/Table/types.ts b/packages/core/src/Table/types.ts
index 033f17fea8..de5710ae9a 100644
--- a/packages/core/src/Table/types.ts
+++ b/packages/core/src/Table/types.ts
@@ -370,6 +370,19 @@ export interface XDSBaseTableProps<T extends Record<string, unknown>> {
children?: ReactNode;
/** Additional HTML attributes for the `<table>` element */
tableProps?: HTMLAttributes<HTMLTableElement>;
+ /**
+ * How default-rendered body cell text behaves when it exceeds column width.
+ *
+ * - `'wrap'` (default) — text wraps and the row grows taller
+ * - `'truncate'` — text is clipped with an ellipsis; default-rendered cells
+ * show a tooltip on hover when truncated
+ *
+ * Only affects cells using the default renderer (no `renderCell`).
+ * Cells with `renderCell` control their own overflow behavior.
+ *
+ * @default 'wrap'
+ */
+ textOverflow?: 'wrap' | 'truncate';
/**
* Content displayed when `data` is an empty array.
* Rendered as a full-width row spanning all columns.
diff --git a/packages/core/src/Text/useTruncation.ts b/packages/core/src/Text/useTruncation.ts
index fbc2a4476e..291eeb2e6f 100644
--- a/packages/core/src/Text/useTruncation.ts
+++ b/packages/core/src/Text/useTruncation.ts
@@ -2,7 +2,7 @@
/**
* @file useTruncation.ts
- * @input Uses React hooks, ResizeObserver
+ * @input Uses React hooks, sharedResizeObserver
* @output Exports useTruncation hook for detecting text overflow
* @position Hook; consumed by XDSText.tsx, XDSHeading.tsx
*
@@ -11,6 +11,7 @@
*/
import {useCallback, useRef, useState, type RefCallback} from 'react';
+import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
export interface UseTruncationOptions {
/**
@@ -40,7 +41,11 @@ export interface UseTruncationReturn {
/**
* Hook for detecting text overflow/truncation.
*
- * Uses ResizeObserver for efficient detection when content or container changes.
+ * Uses a shared ResizeObserver singleton (via observeResize/unobserveResize)
+ * for efficient detection when content or container changes. A single
+ * ResizeObserver instance is shared across all mounted useTruncation hooks,
+ * so even hundreds of table cells only create one observer.
+ *
* - Single-line: compares scrollWidth > offsetWidth
* - Multi-line: uses Range.getBoundingClientRect() to measure actual content
* height, bypassing -webkit-line-clamp's clamped scrollHeight
@@ -63,7 +68,6 @@ export function useTruncation(
const [isTruncated, setIsTruncated] = useState(false);
const [fullText, setFullText] = useState('');
const elementRef = useRef<HTMLElement | null>(null);
- const observerRef = useRef<ResizeObserver | null>(null);
const checkTruncation = useCallback(
(element: HTMLElement) => {
@@ -102,10 +106,9 @@ export function useTruncation(
const ref: RefCallback<HTMLElement> = useCallback(
(element: HTMLElement | null) => {
- // Cleanup previous observer
- if (observerRef.current) {
- observerRef.current.disconnect();
- observerRef.current = null;
+ // Cleanup previous observation
+ if (elementRef.current) {
+ unobserveResize(elementRef.current);
}
elementRef.current = element;
@@ -114,12 +117,11 @@ export function useTruncation(
// Initial check
checkTruncation(element);
- // Setup ResizeObserver for dynamic updates (if available)
+ // Observe via shared singleton (if available)
if (typeof ResizeObserver !== 'undefined') {
- observerRef.current = new ResizeObserver(() => {
+ observeResize(element, () => {
checkTruncation(element);
});
- observerRef.current.observe(element);
}
} else {
setIsTruncated(false);
diff --git a/packages/core/src/utils/index.ts b/packages/core/src/utils/index.ts
index 10748871b2..a252021559 100644
--- a/packages/core/src/utils/index.ts
+++ b/packages/core/src/utils/index.ts
@@ -36,3 +36,4 @@ export {xdsClassName} from './xdsClassName';
export {mergeProps} from './mergeProps';
export {groupItems, getItemGroup} from './groupItems';
export type {ItemGroup} from './groupItems';
+export {observeResize, unobserveResize} from './sharedResizeObserver';
diff --git a/packages/core/src/utils/sharedResizeObserver.test.ts b/packages/core/src/utils/sharedResizeObserver.test.ts
new file mode 100644
index 0000000000..4dd2e6898e
--- /dev/null
+++ b/packages/core/src/utils/sharedResizeObserver.test.ts
@@ -0,0 +1,147 @@
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+
+// We need to test the module in isolation, so we re-import fresh each test.
+// The module has module-level state (the singleton observer).
+
+describe('sharedResizeObserver', () => {
+ let mockObserve: ReturnType<typeof vi.fn>;
+ let mockUnobserve: ReturnType<typeof vi.fn>;
+ let mockDisconnect: ReturnType<typeof vi.fn>;
+ let capturedCallback: ResizeObserverCallback;
+ let constructorCalls: number;
+
+ beforeEach(() => {
+ mockObserve = vi.fn();
+ mockUnobserve = vi.fn();
+ mockDisconnect = vi.fn();
+ constructorCalls = 0;
+
+ global.ResizeObserver = vi.fn((cb: ResizeObserverCallback) => {
+ constructorCalls++;
+ capturedCallback = cb;
+ return {
+ observe: mockObserve,
+ unobserve: mockUnobserve,
+ disconnect: mockDisconnect,
+ };
+ }) as unknown as typeof ResizeObserver;
+ });
+
+ afterEach(() => {
+ vi.resetModules();
+ });
+
+ it('creates a single ResizeObserver for multiple elements', async () => {
+ const {observeResize, unobserveResize} = await import(
+ './sharedResizeObserver'
+ );
+
+ const el1 = document.createElement('div');
+ const el2 = document.createElement('div');
+ const cb1 = vi.fn();
+ const cb2 = vi.fn();
+
+ observeResize(el1, cb1);
+ observeResize(el2, cb2);
+
+ // Only one ResizeObserver created
+ expect(constructorCalls).toBe(1);
+ // Both elements observed
+ expect(mockObserve).toHaveBeenCalledTimes(2);
+ expect(mockObserve).toHaveBeenCalledWith(el1);
+ expect(mockObserve).toHaveBeenCalledWith(el2);
+
+ unobserveResize(el1);
+ unobserveResize(el2);
+ });
+
+ it('dispatches entries to the correct callbacks', async () => {
+ const {observeResize, unobserveResize} = await import(
+ './sharedResizeObserver'
+ );
+
+ const el1 = document.createElement('div');
+ const el2 = document.createElement('div');
+ const cb1 = vi.fn();
+ const cb2 = vi.fn();
+
+ observeResize(el1, cb1);
+ observeResize(el2, cb2);
+
+ // Simulate observer firing for el1 only
+ const fakeEntry1 = {target: el1} as ResizeObserverEntry;
+ capturedCallback([fakeEntry1], {} as ResizeObserver);
+
+ expect(cb1).toHaveBeenCalledTimes(1);
+ expect(cb1).toHaveBeenCalledWith(fakeEntry1);
+ expect(cb2).not.toHaveBeenCalled();
+
+ // Simulate observer firing for el2
+ const fakeEntry2 = {target: el2} as ResizeObserverEntry;
+ capturedCallback([fakeEntry2], {} as ResizeObserver);
+
+ expect(cb2).toHaveBeenCalledTimes(1);
+ expect(cb2).toHaveBeenCalledWith(fakeEntry2);
+
+ unobserveResize(el1);
+ unobserveResize(el2);
+ });
+
+ it('destroys the observer when the last element is unobserved', async () => {
+ const {observeResize, unobserveResize} = await import(
+ './sharedResizeObserver'
+ );
+
+ const el1 = document.createElement('div');
+ const el2 = document.createElement('div');
+
+ observeResize(el1, vi.fn());
+ observeResize(el2, vi.fn());
+
+ unobserveResize(el1);
+ expect(mockDisconnect).not.toHaveBeenCalled();
+
+ unobserveResize(el2);
+ expect(mockDisconnect).toHaveBeenCalledTimes(1);
+ });
+
+ it('recreates observer after full teardown', async () => {
+ const {observeResize, unobserveResize} = await import(
+ './sharedResizeObserver'
+ );
+
+ const el1 = document.createElement('div');
+ observeResize(el1, vi.fn());
+ unobserveResize(el1);
+ expect(constructorCalls).toBe(1);
+
+ // New observation after teardown → new observer
+ const el2 = document.createElement('div');
+ observeResize(el2, vi.fn());
+ expect(constructorCalls).toBe(2);
+
+ unobserveResize(el2);
+ });
+
+ it('replaces callback when same element is observed twice', async () => {
+ const {observeResize, unobserveResize} = await import(
+ './sharedResizeObserver'
+ );
+
+ const el = document.createElement('div');
+ const cb1 = vi.fn();
+ const cb2 = vi.fn();
+
+ observeResize(el, cb1);
+ observeResize(el, cb2);
+
+ const fakeEntry = {target: el} as ResizeObserverEntry;
+ capturedCallback([fakeEntry], {} as ResizeObserver);
+
+ // Only the latest callback fires
+ expect(cb1).not.toHaveBeenCalled();
+ expect(cb2).toHaveBeenCalledTimes(1);
+
+ unobserveResize(el);
+ });
+});
diff --git a/packages/core/src/utils/sharedResizeObserver.ts b/packages/core/src/utils/sharedResizeObserver.ts
new file mode 100644
index 0000000000..82b2bb9a13
--- /dev/null
+++ b/packages/core/src/utils/sharedResizeObserver.ts
@@ -0,0 +1,76 @@
+'use client';
+
+/**
+ * @file sharedResizeObserver.ts
+ * @input ResizeObserver API
+ * @output Exports observeResize / unobserveResize for shared observation
+ * @position Utility; consumed by useTruncation, useOverflow, and any component
+ * that needs resize observation without creating per-instance observers
+ *
+ * A single ResizeObserver can observe thousands of elements. Creating one
+ * per component (e.g. per table cell) is wasteful — browsers batch
+ * observations per observer instance, so a shared observer means one
+ * callback dispatch per animation frame instead of N.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/index.ts (exports)
+ * - /packages/core/src/Text/useTruncation.ts (primary consumer)
+ */
+
+type ResizeCallback = (entry: ResizeObserverEntry) => void;
+
+let observer: ResizeObserver | null = null;
+const callbacks = new Map<Element, ResizeCallback>();
+
+function getObserver(): ResizeObserver {
+ if (!observer) {
+ observer = new ResizeObserver((entries) => {
+ for (const entry of entries) {
+ const cb = callbacks.get(entry.target);
+ if (cb) cb(entry);
+ }
+ });
+ }
+ return observer;
+}
+
+/**
+ * Observe an element's size via a shared ResizeObserver singleton.
+ *
+ * Call `unobserveResize` when the element unmounts or observation is
+ * no longer needed. The shared observer is destroyed when the last
+ * element is unobserved.
+ *
+ * @example
+ * ```
+ * // In a ref callback or effect:
+ * observeResize(element, (entry) => {
+ * console.log(entry.contentRect.width);
+ * });
+ *
+ * // Cleanup:
+ * unobserveResize(element);
+ * ```
+ */
+export function observeResize(
+ element: Element,
+ callback: ResizeCallback,
+): void {
+ callbacks.set(element, callback);
+ getObserver().observe(element);
+}
+
+/**
+ * Stop observing an element. If no elements remain, the shared
+ * observer is disconnected and released for garbage collection.
+ */
+export function unobserveResize(element: Element): void {
+ callbacks.delete(element);
+ if (observer) {
+ observer.unobserve(element);
+ if (callbacks.size === 0) {
+ observer.disconnect();
+ observer = null;
+ }
+ }
+}