Skip to content
DzGrid

columnMenu

Puts a menu on each column header, with one item per thing the user can do to that column.

Importimport { columnMenu } from '@dzgrid/dom/column-menu';
SignaturecolumnMenu(o?: ColumnMenuOptions): ColumnMenuFeature
Textsimport { EN_COLUMN_MENU } from '@dzgrid/dom/locales/en-column-menu';
languages: en, fr, ar
Style sheetimport '@dzgrid/theme/columns.css';
Declared inpackages/dom/src/column-menu/index.ts
OptionsType
use{ readonly columns?: { api(grid: Grid): ColumnsApiLike | null }; /** With `fill`: « Fill down » / « Fill right » on the current block (owner S12-Q12). */ readonly range?: { api(grid: Grid): { get(): unknown } | null }; readonly fill?: { api(grid: Grid): { down(o?: { readonly user?: boolean }): unknown; end(o?: { readonly user?: boolean }): unknown } | null }; /** « Choose columns… » (Phase 6 step 4), opened by the column's header. */ readonly chooser?: { api(grid: Grid): { open(anchor?: HTMLElement): boolean } | null }; /** « Group by this column » / « Stop grouping by this column » (Phase 7, `grouping()`; the way without dragging, WCAG 2.5.7). */ readonly grouping?: { api(grid: Grid): { by(): readonly string[]; setBy(by: readonly string[], o?: { readonly user?: boolean }): void } | null }; /** * The pivot (`pivot()`, Phase 10, pivot.md 20): « Total » on a created column and a row total, « Mettre en colonnes » * on a data column whose header is shown. Its texts from `locales/<lang>-pivot`. */ readonly pivot?: { api(grid: Grid): { on(): boolean; by(): readonly string[]; setBy(by: readonly string[], o?: { readonly user?: boolean }): void; accepts(id: string): boolean; values(): Readonly<Record<string, unknown>>; setValues(v: Readonly<Record<string, any>>, o?: { readonly user?: boolean }): void; valueColumn(id: string): string | undefined } | null } }
densityboolean
onDensity(density: Density) => void
items(column: ResolvedColumn<unknown>, defaults: readonly MenuEntry[], c: MenuContext) => readonly MenuEntry[]
classes{ readonly menu?: string; readonly item?: string }

What it does

Section titled “What it does”

columnMenu() adds a ⋮ button to each column header 96 px wide or more. The menu also opens by a right-click on the header (Shift+right-click keeps the browser’s), by Shift+F10 or the Menu key, by Alt+ArrowDown where the column has no filter popup, and by Ctrl+click on a Mac. Its items: sort, pin to the start or the end, size, move, filter, hide, choose columns, reset the columns, and the density when asked. Each item is said when it acts. Opened by a pointer, the menu leaves the grid’s focus where it was.

Some items come from other features, given in use: « Fit this column », « Fit all columns », « Resize with the keyboard » and the moves need columns(); « Choose columns… » needs columnsChooser(); grouping, the pivot and the fill have their items when grouping(), pivot() or range() with fill() are given. Without them, those items are absent. « Filter… » shows with filters(). « Widen » and « Narrow » change the width by 10 px and keep the menu open: a way to resize without dragging.

menu: false on a column takes the menu away from it. A locked column (movable: false) has its move and pin items disabled; « Hide column » is disabled for a column with hideable: false and for the last one shown. Without the -column-menu texts, the grid is not made: an error names the missing keys.

Options

Section titled “Options”
  • use: the features the items drive (columns, chooser, grouping, pivot, range, fill), reached through their api. A feature not given: its items are absent.
  • density: a « Compact / Normal / Spacious » line. Off by default; absent when rowHeight is a number.
  • onDensity: called after that line changed the grid’s density.
  • items: your items, from the column and the default entries: reorder, remove or add. If it throws, the defaults are shown and the error is reported.
  • classes: your classes on the menu (menu) and on every item (item), for Tailwind or Bootstrap.

Example

Section titled “Example”
import { createGrid } from '@dzgrid/dom';
import { columns } from '@dzgrid/dom/columns';
import { columnMenu } from '@dzgrid/dom/column-menu';
import { EN } from '@dzgrid/dom/locales/en';
import { EN_COLUMNS } from '@dzgrid/dom/locales/en-columns';
import { EN_COLUMN_MENU } from '@dzgrid/dom/locales/en-column-menu';
import '@dzgrid/theme/columns.css';
import '@dzgrid/theme/menu.css';


type River = { id: string; name: string; sea: string; length: number };


const moves = columns();


createGrid<River>(document.getElementById('rivers')!, {
  rows: [{ id: 'r1', name: 'Silverbrook', sea: 'North Sea', length: 212 }],
  columns: [
    { id: 'name', header: 'River' },
    { id: 'sea', header: 'Flows into', menu: false },
    { id: 'length', header: 'Length (km)', type: 'number' },
  ],
  getRowId: (r) => r.id,
  messages: { ...EN, text: { ...EN.text, ...EN_COLUMNS.text, ...EN_COLUMN_MENU.text } },
  features: [
    moves,
    columnMenu({
      use: { columns: moves },
      density: true,
      // No « Hide column » on the river's name.
      items: (column, defaults) => (column.id === 'name' ? defaults.filter((e) => 'separator' in e || e.id !== 'hide') : defaults),
    }),
  ],
});

Live demo

Section titled “Live demo”

Open a column’s menu with its ⋮ button or a right-click on its title.

See also

Section titled “See also”