API

A Table holds Column children, and each column renders a Cell for every row. The other components customize cells and headers.

Usage#

import {
  Cell,
  Column,
  ColumnHeaderCell,
  EditableCell,
  JSONFormat,
  RowHeaderCell,
  Table,
  TruncatedFormat,
} from "@clawscale/react/table";

Table2 and EditableCell2

Table2 and EditableCell2 are deprecated aliases of Table and EditableCell. Use the names without the 2.

Table#

The root component. Set numRows and pass Column children. The table fills the height of its container.

interface TableProps extends Props, Partial<RowHeights>, Partial<ColumnWidths>@clawscale/react/table

Props	Description
`bodyContextMenuRenderer`	`ContextMenuRenderer` An optional callback for displaying a context menu when right-clicking on the table body. The callback is supplied with an array of `Region`s. If the mouse click was on a selection, the array will contain all selected regions. Otherwise it will have one `Region` that represents the clicked cell.
`cellRendererDependencies`	`React.DependencyList` This dependency list may be used to trigger a re-render of all cells when one of its elements changes (compared using shallow equality checks). This is done by invalidating the grid, which forces TableQuadrantStack to re-render.
`children`	`React.ReactElement<ColumnProps> \| Array<React.ReactElement<ColumnProps>>` The children of a `Table` component, which must be React elements that use `ColumnProps`.
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`columnWidths`	`Array<number \| null \| undefined>` A sparse number array with a length equal to the number of columns. Any non-null value will be used to set the width of the column at the same index. Note that if you want to update these values when the user drag-resizes a column, you may define a callback for `onColumnWidthChanged`.
`defaultColumnWidth`	`number` Inherited from `ColumnWidths`
`defaultRowHeight`	`number` Inherited from `RowHeights`
`enableBodyContextMenu`	`boolean` = `true if bodyContextMenuRenderer is defined` Whether the body context menu is enabled.
`enableColumnHeader`	`boolean` = `true` If `false`, hides the column headers.
`enableColumnInteractionBar`	`boolean` = `false` If `true`, adds an interaction bar on top of all column header cells, and moves interaction triggers into it.
`enableColumnReordering`	`boolean` = `false` If `false`, disables reordering of columns.
`enableColumnResizing`	`boolean` = `true` If `false`, disables resizing of columns.
`enableFocusedCell`deprecated	`boolean` = `false` If `true`, there will be a single "focused" cell at all times, which can be used to interact with the table as though it is a spreadsheet. When false, no such cell will exist. When using `Table2`, use the `focusMode` prop instead.
`enableGhostCells`	`boolean` = `false` If `true`, empty space in the table container will be filled with empty cells instead of a blank background.
`enableMultipleSelection`	`boolean` = `true` If `false`, only a single region of a single column/row/cell may be selected at one time. Using `ctrl` or `meta` key will have no effect, and a mouse drag will select the current column/row/cell only.
`enableRowHeader`	`boolean` = `true` If `false`, hides the row headers and settings menu.
`enableRowReordering`	`boolean` = `false` If `false`, disables reordering of rows.
`enableRowResizing`	`boolean` = `true` If `false`, disables resizing of rows.
`focusedCell`deprecated	`FocusedCellCoordinates` If defined, will set the focused cell state. This changes the focused cell to controlled mode, meaning you are in charge of setting the focus in response to events in the `onFocusedCell` callback. When using `Table2`, use the `focusedRegion` prop instead
`focusedRegion`	`FocusedRegion` If defined, will set the focused region state. This changes the focused region to controlled mode, meaning yo uare in charge of setting the focus in response to events in the `onFocusedRegion` callback. The shape of the region is defined by the `focusMode` prop.
`focusMode`	`FocusMode` = `undefined` If this is defined, there will be a single focused cell or row at all times which can be used to interact with the table as though it is a spread sheet. The type of allowed focus area is given by the value. If undefined is passed, then this focus state will be disabled.
`forceRerenderOnSelectionChange`	`boolean` = `false` If `true`, selection state changes will cause the component to re-render. If `false`, selection state is ignored when deciding to re-render.
`getCellClipboardData`	`(row: number, col: number, celRenderer: CellRenderer) => any` If defined, this callback will be invoked for each cell when the user attempts to copy a selection via `mod+c`. The returned data will be copied to the clipboard and need not match the display value of the `<Cell>`. The data will be invisibly added as `textContent` into the DOM before copying. If not defined, a default implementation will be used that turns the rendered cell elements into strings using 'react-innertext'.
`loadingOptions`	`TableLoadingOption[]` A list of `TableLoadingOption`. Set this prop to specify whether to render the loading state for the column header, row header, and body sections of the table.
`maxColumnWidth`	`number` Inherited from `ColumnWidths`
`maxRowHeight`	`number` Inherited from `RowHeights`
`minColumnWidth`	`number` Inherited from `ColumnWidths`
`minRowHeight`	`number` Inherited from `RowHeights`
`numFrozenColumns`	`number` = `0` The number of columns to freeze to the left side of the table, counting from the leftmost column.
`numFrozenRows`	`number` = `0` The number of rows to freeze to the top of the table, counting from the topmost row.
`numRows`	`number` The number of rows in the table.
`onColumnsReordered`	`(oldIndex: number, newIndex: number, length: number) => void` If reordering is enabled, this callback will be invoked when the user finishes drag-reordering one or more columns.
`onColumnWidthChanged`	`IndexedResizeCallback` If resizing is enabled, this callback will be invoked when the user finishes drag-resizing a column.
`onCompleteRender`	`() => void` An optional callback invoked when all cells in view have completely rendered. Will be invoked on initial mount and whenever cells update (e.g., on scroll).
`onCopy`	`(success: boolean) => void` If you want to do something after the copy or if you want to notify the user if a copy fails, you may provide this optional callback.
`onFocusedCell`deprecated	`(focusedCell: FocusedCellCoordinates) => void` A callback called when the focus is changed in the table. When using `Table2`, use the `onFocusedRegion` prop instead
`onFocusedRegion`	`(focusedRegion: FocusedRegion) => void` A callback called when the focused region is changed in the table.
`onRowHeightChanged`	`IndexedResizeCallback` If resizing is enabled, this callback will be invoked when the user finishes drag-resizing a row.
`onRowsReordered`	`(oldIndex: number, newIndex: number, length: number) => void` If reordering is enabled, this callback will be invoked when the user finishes drag-reordering one or more rows.
`onSelection`	`(selectedRegions: Region[]) => void` A callback called when the selection is changed in the table.
`onVisibleCellsChange`	`(rowIndices: RowIndices, columnIndices: ColumnIndices) => void` A callback called when the visible cell indices change in the table.
`renderMode`	`RenderMode` = `RenderMode.BATCH_ON_UPDATE` Dictates how cells should be rendered. Supported modes are: - `RenderMode.BATCH`: renders cells in batches to improve performance - `RenderMode.BATCH_ON_UPDATE`: renders cells synchronously on mount and in batches on update - `RenderMode.NONE`: renders cells synchronously all at once
`rowHeaderCellRenderer`	`RowHeaderRenderer` Render each row's header cell.
`rowHeights`	`Array<number \| null \| undefined>` A sparse number array with a length equal to the number of rows. Any non-null value will be used to set the height of the row at the same index. Note that if you want to update these values when the user drag-resizes a row, you may define a callback for `onRowHeightChanged`.
`selectedRegions`	`Region[]` If defined, will set the selected regions in the cells. If defined, this changes table selection to controlled mode, meaning you in charge of setting the selections in response to events in the `onSelection` callback.
`selectedRegionTransform`	`SelectedRegionTransform` An optional transform function that will be applied to the located `Region`.
`selectionModes`	`RegionCardinality[]` = `SelectionModes.ALL` A `SelectionModes` enum value indicating the selection mode. You may equivalently provide an array of `RegionCardinality` enum values for precise configuration.
`styledRegionGroups`	`StyledRegionGroup[]` Styled region groups are rendered as overlays above the table and are marked with their own `className` for custom styling.

Instance methods#

Get the instance with a ref, for example useRef<Table>(null).

Method	What it does
`scrollToRegion(region)`	Scrolls a region to the top left of the viewport.
`scrollByOffset({ left, top })`	Scrolls the body by a number of pixels.
`resizeRowsByTallestCell(columns?)`	Sets every row to the height of the tallest visible cell.
`resizeRowsByApproximateHeight(getCellText)`	Sizes each row to fit its wrapped text, by estimate. Experimental.

Regions#

A region is a rectangle of cells. Selection, styled overlays and scrollToRegion all take regions. Build them with the Regions helpers.

import { Regions } from "@clawscale/react/table";

Regions.cell(0, 2); // one cell: row 0, column 2
Regions.row(4, 6); // rows 4 to 6
Regions.column(1); // column 1
Regions.table(); // every cell

Column#

One column: its name, its cell renderer and an optional header renderer. Give each column a stable id, so its width survives reordering.

interface ColumnProps extends ColumnNameProps, Props@clawscale/react/table

Props	Description
`cellRenderer`	`CellRenderer` An instance of `CellRenderer`, a function that takes a row and column index, and returns a `Cell` React element.
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`columnHeaderCellRenderer`	`ColumnHeaderRenderer` An instance of `ColumnHeaderRenderer`, a function that takes a column index and returns a `ColumnHeaderCell` React element.
`id`	`string \| number` A unique ID, similar to React's `key`. This is used, for example, to maintain the width of a column between re-ordering and rendering. If no IDs are provided, widths will be persisted across renders using a column's index only. Columns widths can also be persisted outside the `Table` component, then passed in with the `columnWidths` prop.
`loadingOptions`	`ColumnLoadingOption[]` Set this prop to specify whether to render the loading state of the column header and cells in this column. Column-level `loadingOptions` override `Table`-level `loadingOptions`. For example, if you set `loadingOptions=[ TableLoadingOption.CELLS ]` on `Table` and `loadingOptions=[ ColumnLoadingOption.HEADER ]` on a `Column`, the cells in that column will _not_ show their loading state.
`name`	`string` The name displayed in the header of the column. Inherited from `ColumnNameProps`
`nameRenderer`	`(name: string, index?: number) => React.ReactElement<Props>` A callback to override the default name rendering behavior. The default behavior is to simply use the `ColumnHeaderCell`s name prop. Inherited from `ColumnNameProps`

Cell#

The content of one cell, returned from a column's cellRenderer. intent colors the cell, wrapText allows several lines and loading shows a skeleton.

interface CellProps extends IntentProps, Props@clawscale/react/table

Props	Description
`cellRef`	`React.Ref<HTMLDivElement>` A ref handle to capture the outer div of this cell. Used internally.
`children`	`React.ReactNode`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`columnIndex`	`number` The column index of the cell. If provided, this will be passed as an argument to any callbacks when they are invoked.
`intent`	`Intent` Visual intent color to apply to element. Inherited from `IntentProps`
`interactive`	`boolean` = `false` If `true`, the cell will be rendered above overlay layers to enable mouse interactions within the cell.
`key`	`string`
`loading`	`boolean` = `false` An optional native tooltip that is displayed on hover. If `true`, content will be replaced with a fixed-height skeleton.
`onKeyDown`	`React.KeyboardEventHandler<HTMLElement>` Callback invoked when the cell is focused and a key is pressed down.
`onKeyPress`	`React.KeyboardEventHandler<HTMLElement>` Callback invoked when a character-key is pressed.
`onKeyUp`	`React.KeyboardEventHandler<HTMLElement>` Callback invoked when the cell is focused and a key is released.
`rowIndex`	`number` The row index of the cell. If provided, this will be passed as an argument to any callbacks when they are invoked.
`style`	`React.CSSProperties`
`tabIndex`	`number` Allows for setting a tab index on the cell, so the cell can be browser-focusable.
`tooltip`	`string` An optional native tooltip that is displayed on hover.
`truncated`	`boolean` = `true` If `true`, the cell contents will be wrapped in a `div` with styling that will prevent the content from overflowing the cell.
`wrapText`	`boolean` = `false` If `true`, the cell contents will be wrapped in a `div` with styling that will cause text to wrap, rather than displaying it on a single line.

EditableCell#

A cell that turns into a text input on double click. onConfirm receives the new value.

interface EditableCellProps extends Omit<CellProps, "onKeyDown" | "onKeyUp">@clawscale/react/table

Props	Description
`cellRef`	`React.Ref<HTMLDivElement>` A ref handle to capture the outer div of this cell. Used internally. Inherited from `CellProps`
`children`	`React.ReactNode` Inherited from `CellProps`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`columnIndex`	`number` The column index of the cell. If provided, this will be passed as an argument to any callbacks when they are invoked. Inherited from `CellProps`
`editableTextProps`	`Omit<EditableTextProps, "elementRef">` Props that should be passed to the EditableText when it is used to edit
`intent`	`Intent` Visual intent color to apply to element. Inherited from `IntentProps`
`interactive`	`boolean` = `false` If `true`, the cell will be rendered above overlay layers to enable mouse interactions within the cell. Inherited from `CellProps`
`isFocused`	`boolean` Whether the given cell is the current active/focused cell.
`key`	`string` Inherited from `CellProps`
`loading`	`boolean` = `false` An optional native tooltip that is displayed on hover. If `true`, content will be replaced with a fixed-height skeleton. Inherited from `CellProps`
`onCancel`	`(value: string, rowIndex?: number, columnIndex?: number) => void` A listener that is triggered if the user cancels the edit. This is important to listen to if you are doing anything with `onChange` events, since you'll likely want to revert whatever changes you made. The callback will also receive the row index and column index if they were originally provided via props.
`onChange`	`(value: string, rowIndex?: number, columnIndex?: number) => void` A listener that is triggered as soon as the editable name is modified. This can be due, for example, to keyboard input or the clipboard. The callback will also receive the row index and column index if they were originally provided via props.
`onConfirm`	`(value: string, rowIndex?: number, columnIndex?: number) => void` A listener that is triggered once the editing is confirmed. This is usually due to the <code>return</code> (or <code>enter</code>) key press. The callback will also receive the row index and column index if they were originally provided via props.
`onKeyPress`	`React.KeyboardEventHandler<HTMLElement>` Callback invoked when a character-key is pressed. Inherited from `CellProps`
`rowIndex`	`number` The row index of the cell. If provided, this will be passed as an argument to any callbacks when they are invoked. Inherited from `CellProps`
`style`	`React.CSSProperties` Inherited from `CellProps`
`tabIndex`	`number` Allows for setting a tab index on the cell, so the cell can be browser-focusable. Inherited from `CellProps`
`tooltip`	`string` An optional native tooltip that is displayed on hover. Inherited from `CellProps`
`truncated`	`boolean` = `true` If `true`, the cell contents will be wrapped in a `div` with styling that will prevent the content from overflowing the cell. Inherited from `CellProps`
`value`	`string` The value displayed in the text box. Be sure to update this value when rendering this component after a confirmed change.
`wrapText`	`boolean` = `false` If `true`, the cell contents will be wrapped in a `div` with styling that will cause text to wrap, rather than displaying it on a single line. Inherited from `CellProps`

ColumnHeaderCell#

Return one from a column's columnHeaderCellRenderer to customize its header. menuRenderer adds a menu that opens from a header button or on right click. Children render below the name.

<Column
  name="Rows"
  cellRenderer={renderRows}
  columnHeaderCellRenderer={() => (
    <ColumnHeaderCell
      name="Rows"
      menuRenderer={() => (
        <Menu>
          <MenuItem icon="sort-desc" text="Sort largest first" onClick={sortByRows} />
        </Menu>
      )}
    />
  )}
/>

interface ColumnHeaderCellProps extends HeaderCellProps, ColumnNameProps@clawscale/react/table

Props	Description
`children`	`React.ReactNode` Inherited from `HeaderCellProps`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`enableColumnInteractionBar`	`boolean` = `false` If `true`, adds an interaction bar on top of all column header cells, and moves interaction triggers into it.
`enableColumnReordering`	`boolean` Specifies if the column is reorderable.
`index`	`number` The index of the cell in the header. If provided, this will be passed as an argument to any callbacks when they are invoked. Inherited from `HeaderCellProps`
`isActive`	`boolean` If `true`, will apply the active class to the header to indicate it is part of an external operation. Inherited from `HeaderCellProps`
`isColumnSelected`	`boolean` Specifies if the full column is part of a selection.
`loading`	`boolean` = `false` If `true`, the row/column `name` will be replaced with a fixed-height skeleton, and the `resizeHandle` will not be rendered. If passing in additional children to this component, you will also want to conditionally apply `Classes.SKELETON` where appropriate. Inherited from `HeaderCellProps`
`menuIcon`	`IconName \| React.JSX.Element` = `"chevron-down"` The icon name or element for the header's menu button.
`menuPopoverProps`	`Omit<PopoverProps, "content" \| keyof OverlayLifecycleProps>` Optional props to forward to the dropdown menu popover. This has no effect if `menuRenderer` is undefined.
`menuRenderer`	`(index?: number) => React.JSX.Element` A callback that returns an element, like a `<Menu>`, which is displayed by right-clicking anywhere in the header. The callback will receive the cell index if it was provided via props. Inherited from `HeaderCellProps`
`name`	`string` The name displayed in the header of the row/column. Inherited from `HeaderCellProps`
`nameRenderer`	`(name: string, index?: number) => React.ReactElement<Props>` A callback to override the default name rendering behavior. The default behavior is to simply use the `ColumnHeaderCell`s name prop. Inherited from `ColumnNameProps`
`reorderHandle`	`React.JSX.Element` A `ReorderHandle` React component that allows users to drag-reorder the column header. Inherited from `HeaderCellProps`
`resizeHandle`	`React.JSX.Element` A `ResizeHandle` React component that allows users to drag-resize the header. Inherited from `HeaderCellProps`
`selectCellsOnMenuClick`	`boolean` = `true` If `true`, clicks on the header menu target element will cause the column's cells to be selected.
`style`	`React.CSSProperties` CSS styles for the top level element. Inherited from `HeaderCellProps`
`targetRef`	`React.RefObject<HTMLElement>` Required for Draggable to attach a DOM ref. Inherited from `HeaderCellProps`

RowHeaderCell#

Return one from the table's rowHeaderCellRenderer to replace the default row numbers.

<Table numRows={runs.length} rowHeaderCellRenderer={(row) => <RowHeaderCell name={runs[row]?.id} />}>
  {columns}
</Table>

interface RowHeaderCellProps extends HeaderCellProps, Props@clawscale/react/table

Props	Description
`children`	`React.ReactNode` Inherited from `HeaderCellProps`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`enableRowReordering`	`boolean` Specifies if the row is reorderable.
`index`	`number` The index of the cell in the header. If provided, this will be passed as an argument to any callbacks when they are invoked. Inherited from `HeaderCellProps`
`isActive`	`boolean` If `true`, will apply the active class to the header to indicate it is part of an external operation. Inherited from `HeaderCellProps`
`isRowSelected`	`boolean` Specifies whether the full row is part of a selection.
`loading`	`boolean` = `false` If `true`, the row/column `name` will be replaced with a fixed-height skeleton, and the `resizeHandle` will not be rendered. If passing in additional children to this component, you will also want to conditionally apply `Classes.SKELETON` where appropriate. Inherited from `HeaderCellProps`
`menuRenderer`	`(index?: number) => React.JSX.Element` A callback that returns an element, like a `<Menu>`, which is displayed by right-clicking anywhere in the header. The callback will receive the cell index if it was provided via props. Inherited from `HeaderCellProps`
`name`	`string` The name displayed in the header of the row/column. Inherited from `HeaderCellProps`
`nameRenderer`	`(name: string, index?: number) => React.ReactElement<Props>` A callback to override the default name rendering behavior. The default behavior is to simply use the `RowHeaderCell`s name prop.
`reorderHandle`	`React.JSX.Element` A `ReorderHandle` React component that allows users to drag-reorder the column header. Inherited from `HeaderCellProps`
`resizeHandle`	`React.JSX.Element` A `ResizeHandle` React component that allows users to drag-resize the header. Inherited from `HeaderCellProps`
`style`	`React.CSSProperties` CSS styles for the top level element. Inherited from `HeaderCellProps`
`targetRef`	`React.RefObject<HTMLElement>` Required for Draggable to attach a DOM ref. Inherited from `HeaderCellProps`

TruncatedFormat#

Wraps long text in a cell. With detectTruncation, a button opens the full text when it does not fit.

interface TruncatedFormatProps extends Props@clawscale/react/table

Props	Description
`children`	`string`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`detectTruncation`	`boolean` = `false;` Should the component keep track of the truncation state of the string content. If true, the value of `truncateLength` is ignored. When combined with a `showPopover` value of `WHEN_TRUNCATED`, popovers will only render when necessary.
`measureByApproxOptions`	`TrucatedFormateMeasureByApproximateOptions` Values to use for character width, line height, cell padding, and buffer lines desired, when using approximate truncation. These values are used to guess at the size of the text and determine if the popover should be drawn. They should work well enough for default table styles, but may need to be overridden for more accuracy if the default styles or font size, etc are changed.
`parentCellHeight`	`number` Height of the parent cell. Used by shouldComponentUpdate only
`parentCellWidth`	`number` Width of the parent cell. Used by shouldComponentUpdate only
`preformatted`	`boolean` = `false` Sets the popover content style to `white-space: pre` if `true` or `white-space: normal` if `false`.
`showPopover`	`TruncatedPopoverMode` = `WHEN_TRUNCATED` Configures when the popover is shown with the `TruncatedPopoverMode` enum.
`truncateLength`	`number` = `2000` Number of characters that are displayed before being truncated and appended with the `truncationSuffix` prop. A value of 0 will disable truncation. This prop is ignored if `detectTruncation` is `true`.
`truncationSuffix`	`string` = `"..."` The string that is appended to the display string if it is truncated.

JSONFormat#

Prints an object as JSON and truncates it like TruncatedFormat.

interface JSONFormatProps extends TruncatedFormatProps@clawscale/react/table

Props	Description
`children`	`any`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`detectTruncation`	`boolean` = `false;` Should the component keep track of the truncation state of the string content. If true, the value of `truncateLength` is ignored. When combined with a `showPopover` value of `WHEN_TRUNCATED`, popovers will only render when necessary. Inherited from `TruncatedFormatProps`
`measureByApproxOptions`	`TrucatedFormateMeasureByApproximateOptions` Values to use for character width, line height, cell padding, and buffer lines desired, when using approximate truncation. These values are used to guess at the size of the text and determine if the popover should be drawn. They should work well enough for default table styles, but may need to be overridden for more accuracy if the default styles or font size, etc are changed. Inherited from `TruncatedFormatProps`
`omitQuotesOnStrings`	`boolean` = `true` By default, we omit stringifying native JavaScript strings since `JSON.stringify` awkwardly adds double-quotes to the display value. This behavior can be turned off by setting this boolean to `false`.
`parentCellHeight`	`number` Height of the parent cell. Used by shouldComponentUpdate only Inherited from `TruncatedFormatProps`
`parentCellWidth`	`number` Width of the parent cell. Used by shouldComponentUpdate only Inherited from `TruncatedFormatProps`
`preformatted`	`boolean` = `false` Sets the popover content style to `white-space: pre` if `true` or `white-space: normal` if `false`. Inherited from `TruncatedFormatProps`
`showPopover`	`TruncatedPopoverMode` = `WHEN_TRUNCATED` Configures when the popover is shown with the `TruncatedPopoverMode` enum. Inherited from `TruncatedFormatProps`
`stringify`	`(obj: any) => string` Optionally specify the stringify method. Default is `JSON.stringify` with 2-space indentation.
`truncateLength`	`number` = `2000` Number of characters that are displayed before being truncated and appended with the `truncationSuffix` prop. A value of 0 will disable truncation. This prop is ignored if `detectTruncation` is `true`. Inherited from `TruncatedFormatProps`
`truncationSuffix`	`string` = `"..."` The string that is appended to the display string if it is truncated. Inherited from `TruncatedFormatProps`