Table options

comins-table@0.2.2React

React props for CominsTable. Start with mode differences and defaults, then open a feature reference. A property without ? is required in that type. Defaults describe the published 0.2.0 implementation; an omitted prop is distinct from an internal state default.

clipboardPaste

clipboardPaste?: boolean;

Defaults to false. Reads plain-text TSV from native paste events at the current selection. Requires cellSelection and onChangeData; independent of the clipboard copy option. Disabled while loading; native editors keep their own paste behavior. Out-of-bounds cells are clipped and protected targets are skipped.

fillHandle

fillHandle?: boolean;

Defaults to false. With cellSelection and onChangeData, repeats values from a contiguous selection using its corner handle. Dragging previews the change and release commits once. Escape cancels. Automatic numeric/date series and clearing cells when shrinking are not supported.

onClipboardError

onClipboardError?: (error: Error) => void;

Optional error callback for paste and fill failures: malformed TSV, size limits, conversion/validation errors and unloaded Viewport ranges. The application displays the error. Rejected operations do not partially update data.

Mode compatibility

Mode	data / required configuration	Main unsupported combinations
Flat array	readonly TData[], columns	Subject to the feature restrictions below.
Filtered array	Above + columnFiltering.model	Tree, Viewport, incremental loading, row drag, tableTransfer
Grouped array	Above + rowGrouping	Tree, Viewport, pagination, incremental loading
Tree	tree: true, CominsTreeNode<TData>[], getRowId	Filtering, grouping, pagination, incremental loading, row detail, tableTransfer
Viewport	CominsViewportData<TData>, viewportDatasource, getRowId, onViewportRequest	Tree, filtering, grouping, pagination, incremental loading, summary, row detail, row drag, tableTransfer

Grouping and filtering can be combined; both the grouping pagination restriction and the filtering row-drag restriction apply. tableTransfer supports flat/grouped arrays without filtering or incremental loading. Do not merge every option into one object and bypass the mode contract with a type assertion.

State ownership

The parent owns data and applies edits or moves through onChangeData. Filtering, group expansion, and row details also require their controlled values and callbacks. This React API has no selection, sort, sortModel, or columnLayout input props. Selection, sorting, and column layout are internal state; their callbacks notify you of changes. Use CominsTableRef for external commands. Core state constructor options are not React props.

Selection and ref example

CominsTable

columns

columns: Array<CominsTableColumn<TData>>;

Required column definitions. See column options for fields, renderers, pinning, and sorting.

data

data: readonly TData[];

Required parent-owned row array. Tree and Viewport replace this shape as shown below.

getRowId

getRowId?: (row: TData, index: number) => CominsRowId;

Optional for flat arrays; required for Tree/Viewport. Return a stable unique business ID. Index-based identities can move selection to another row after insertion or reordering.

columnGroups

columnGroups?: Array<CominsTableColumnGroup>;

No grouped headers when omitted. children refer to column IDs. See column options.

cellSelection

cellSelection?: boolean;

Default true. Enables cell/range selection independently of row click selection.

rowSelectionOnClick

rowSelectionOnClick?: boolean;

Default true. Controls row selection from clicks/context menus; false does not disable ref selection commands.

clipboard

clipboard?: boolean;

Default false. Enables keyboard clipboard operations. ref.copySelection is independent. See the 0.2.0 clipboard contract.

multiSort

multiSort?: boolean;

Default false. Enables multiple sort rules; columns must also enable sort. Observe the model with onChangeSortModel.

pagination

pagination?: Partial<CominsPaginationState>;

Partial configuration for flat arrays. pageIndex defaults to 0; pageSize defaults to max(data.length, 1). Not supported with grouping, Tree, or Viewport.

rowProps

rowProps?: CominsTableRowProps<TData>;

Row styling, disabled state, and drag permission. See CominsTableRowProps below.

showHeader

showHeader?: boolean;

Default true. Shows or hides the header.

showColumnMoveHandle

showColumnMoveHandle?: boolean;

Default true. Shows column move handles; use column lockPosition to constrain movement.

className

className?: string;

No custom class when omitted. Added to the table root.

style

style?: React.CSSProperties;

No custom inline style when omitted. A 100% height also requires a definite parent height.

data-testid

"data-testid"?: string;

No custom test ID when omitted. Identifies the root element in tests.

theme

theme?: CominsTableTheme;

Density, class, and style settings. See CominsTableTheme below.

summary

summary?: CominsTableSummaryConfig<TData>;

No summary row when omitted. Aggregates data; with filtering it uses filtered rows before pagination. Not supported in Viewport.

tree

tree?: false;

Omit or pass false for a flat array; true selects CominsTreeTableProps.

CominsTreeTableProps

data

data: readonly CominsTreeNode<TData>[];

Required tree nodes containing item and children, rather than plain rows.

getRowId

getRowId: (item: TData, index: number) => CominsRowId;

Required stable unique ID for each tree item.

defaultExpandAll

defaultExpandAll?: boolean;

Default true. Initial expansion policy; node.expand takes precedence. Changing this prop later does not reset all nodes.

treeRowDrag

treeRowDrag?: CominsTreeRowDragConfig<TData>;

No tree-drag configuration when omitted. See the Tree guide for destination and keyboard policies.

tree

tree: true;

Required true discriminator for Tree mode.

CominsViewportTableProps

data

data: CominsViewportData<TData>;

Required controlled snapshot of total row count and loaded blocks. See data loading.

getRowId

getRowId: (row: TData, index: number) => CominsRowId;

Required. index is absolute in the remote dataset, not an index in a loaded subset.

CominsTableRowProps

className

className?: CominsRowPropValue<TData, CominsClassValue>;

String, boolean class map, or per-row resolver. No custom class when omitted.

disabled

disabled?: CominsRowPropValue<TData, boolean | undefined>;

Default false. Disables user selection, row events, and dragging for the row. May be a per-row resolver.

draggable

draggable?: CominsRowPropValue<TData, boolean | undefined>;

Flat-row dragging defaults to disabled. Set rowProps={{ draggable: true }} or return true from its row resolver to enable it. Flat-row reordering can update internal order without onChangeData; supplying a new data array replaces that order. Not available in filtering mode. Tree movement uses the separate treeRowDrag contract.

style

style?: CominsRowPropValue<TData, React.CSSProperties | undefined>;

Inline style or per-row resolver. Configure automatic height through getRowHeight.

CominsTableTheme

className

className?: string;

Additional theme class; no custom class by default.

density

density?: CominsTableDensity;

Choose comfortable, compact, or spacious. Omission uses the default theme density.

style

style?: React.CSSProperties;

Theme inline styles. See the styling guide for CSS variables.

CominsTableSummaryConfig

columns

columns: Partial<Record<string, CominsSummaryColumn<TData>>>;

Required aggregation by column ID: sum/avg/min/max/count, a custom function, or a configuration object.

className

className?: string;

Additional summary-row class; none by default.

label

label?: React.ReactNode;

Summary-row label. Omission uses the built-in presentation.

style

style?: React.CSSProperties;

Summary-row inline styles; none by default.

CominsSummaryColumnConfig

aggregate

aggregate: CominsSummaryBuiltin | CominsSummaryAggregator<TData>;

Required built-in aggregation name or custom function receiving rows, values, and column.

className

className?: string;

Additional summary-cell class; none by default.

colSpan

colSpan?: number;

Number of columns spanned by the summary cell. Check the visible columns being merged.

format

format?: (payload: CominsSummaryFormatPayload<TData>) => React.ReactNode;

Formats the aggregate value as a ReactNode; also receives source rows and values.

style

style?: React.CSSProperties;

Summary-cell inline styles; none by default.

Filtered mode

columnFiltering

columnFiltering: CominsColumnFilteringConfig;

Parent-owned filtering configuration. Connect model and open/change callbacks as shown in the filter reference.

Grouping and cross-table transfer

rowGrouping

rowGrouping: CominsRowGroupingConfig<TData, TGroup>;

Required grouping configuration. See the group reference for groups, membership, and expansion.

tableTransfer

tableTransfer?: CominsTableTransferConfig<TData, TGroup>;

No cross-table transfer when omitted. See the transfer guide for coordinator, scope, tableId, and conflict policies.

Related API

• Events

• Columns

• Data loading

• Filtering

• Grouping

• Row details

• Tree drag options

• Cross-table transfer options

treeSlots

treeSlots?: never;

Rendering slots for Tree mode; unavailable in flat mode.

treeSlots

treeSlots?: CominsTreeSlots<TData>;

Rendering slots for Tree mode; unavailable in flat mode.

CominsTreeSlotParams

export type CominsTreeSlotParams<TData> = CominsVisibleTreeRow<TData> & {
    defaultContent: React.ReactNode;
};

Inherits current row information from CominsVisibleTreeRow, including item, rowId, depth, hasChildren and expanded. Slots affect only the first Tree column. Default drag handles and expand toggles remain outside slots.

Property	Behavior
defaultContent	Default cell content, reusable within content.

CominsTreeSlots

export type CominsTreeSlots<TData> = {
    /** Prefer { render }. Direct callbacks remain in 0.x; removal target: 1.0.0. */
    leading?: ((params: CominsTreeSlotParams<TData>) => React.ReactNode) | {
        render?: (params: CominsTreeSlotParams<TData>) => React.ReactNode;
    };
    /** Prefer { render }. Direct callbacks remain in 0.x; removal target: 1.0.0. */
    content?: ((params: CominsTreeSlotParams<TData>) => React.ReactNode) | {
        render?: (params: CominsTreeSlotParams<TData>) => React.ReactNode;
    };
    /** Prefer { render }. Direct callbacks remain in 0.x; removal target: 1.0.0. */
    trailing?: ((params: CominsTreeSlotParams<TData>) => React.ReactNode) | {
        render?: (params: CominsTreeSlotParams<TData>) => React.ReactNode;
    };
};

Optional callbacks returning ReactNode. Omitting content preserves default content. Supported for folder/leaf rows and virtualization, but not flat or Viewport mode. Interactive slot click, keyboard and clipboard events are isolated from default row selection and Table clipboard handling. Provide accessible names.

Property	Behavior
leading	Renders before the content.
content	Replaces default content; use defaultContent to retain it.
trailing	Renders after the content.

render

render?: (payload: CominsSummaryRenderPayload<TData>) => React.ReactNode;

See the 0.2.2 migration guide for rendering precedence and return values.

emptyContent

emptyContent?: {
        render?: () => React.ReactNode;
    };

Standard content rendering options in 0.2.2. When present, render takes precedence over static content; its return value becomes the displayed content. See the rendering migration guide for precedence and restrictions.

loadingContent

loadingContent?: {
        render?: () => React.ReactNode;
    };

Standard content rendering options in 0.2.2. When present, render takes precedence over static content; its return value becomes the displayed content. See the rendering migration guide for precedence and restrictions.