Skip to main content

Columns and layout

DyonaGrid lets users resize, reorder, and hide columns. Column definitions provide the declarative defaults; use columnState when the application needs to restore a customized layout.

Try it live in the Lab

Width and resizing​

width is the initial width. minWidth and maxWidth constrain it, including while a user resizes it. Resizing is enabled by default; set resizable: false for a fixed column.

const columns: DyonaGridColumn[] = [
  {field: 'invoice', headerName: 'Invoice', width: 160, minWidth: 120, maxWidth: 260},
  {field: 'status', headerName: 'Status', width: 120, resizable: false},
];

When the user confirms a resize, the grid emits both callbacks:

<DyonaGrid
  columns={columns}
  onColumnResize={({field, width}) => saveWidth(field, width)}
  onColumnStateChange={(state) => saveLayout(state)}
/>

onColumnResize receives {field, width}. onColumnStateChange receives the complete next state. Neither callback is emitted while the pointer is only previewing a size.

Reordering​

allowColumnReorder is true by default. Set it to false to disable reordering for the whole grid. Individual columns remain in place with reorderable: false.

const columns: DyonaGridColumn[] = [
  {field: 'invoice', headerName: 'Invoice'},
  {field: 'customer', headerName: 'Customer', reorderable: false},
];

<DyonaGrid
  columns={columns}
  allowColumnReorder
  onColumnOrderChange={({field, fromIndex, toIndex}) => trackMove(field, fromIndex, toIndex)}
  onColumnStateChange={setColumnState}
/>

On a confirmed, real reorder, onColumnOrderChange receives {field, fromIndex, toIndex} and onColumnStateChange(state) receives the resulting layout. They are not emitted for a drag preview or a cancelled drag.

Visibility​

allowColumnHiding is true by default. Set it to false to remove column hiding controls. hideable: false prevents users from changing a column's visibility; its declarative visible value is still respected. Set visible: false to make a column initially hidden.

const columns: DyonaGridColumn[] = [
  {field: 'invoice', headerName: 'Invoice', hideable: false},
  {field: 'internalNotes', headerName: 'Internal notes', visible: false},
];

<DyonaGrid
  columns={columns}
  allowColumnHiding
  onColumnVisibilityChange={({field, visible}) => saveVisibility(field, visible)}
  onColumnStateChange={setColumnState}
/>

When a column is hidden or shown, onColumnVisibilityChange receives {field, visible}, followed by onColumnStateChange(state) with the complete next state. DyonaGrid does not allow the last visible data column to be hidden.

Controlled column state and persistence​

columnState is an ordered array of {field, width?, visible?} items. The array order is the logical column order; width and visible are stored by field.

const [columnState, setColumnState] = useState<DyonaGridColumnState>([
  {field: 'customer', width: 240, visible: true},
  {field: 'invoice', width: 160, visible: true},
  {field: 'internalNotes', visible: false},
]);

<DyonaGrid columns={columns} columnState={columnState} onColumnStateChange={setColumnState} />

__actions can be present in the state and may retain its position. The selection column does not participate in columnState.

DyonaGrid does not use localStorage internally. Persist columnState in the consuming application (for example, in its own storage or backend) and pass the restored value back to the grid.

Reset columns​

The built-in Reset columns action appears only when the current customization differs from the original declarative layout. It restores the layout from columns: its order, visible values, and widths. It also emits onColumnStateChange with that restored state, so consumers can replace their saved layout.

<DyonaGrid
  columns={columns}
  columnState={savedColumnState}
  onColumnStateChange={(state) => setSavedColumnState(state)}
/>