locale

How the cells write numbers and dates, and how text sorts — apart from the language of the texts.

Type	string
Default	the bundle’s language (messages.locale)
Live update (update())	Yes
Angular	the [locale] input
<dz-grid>	the locale attribute
Declared in	packages/dom/src/settings.ts

What it does

A language tag ('en-GB', 'fr-CH', 'ar-DZ'): 1 234,5 or 1,234.5, 03/02/2026 or 2026-03-02, and the order of « é » among the other letters when a text column is sorted. Left out, the grid takes the messages bundle’s locale — so English texts with Swiss numbers are messages: EN, locale: 'de-CH'.

The calendar is always the Gregorian one, whatever the tag says, and the digits are Latin unless numerals asks for the language’s own. A malformed tag throws a RangeError: from createGrid, or from update(), which then leaves the grid as it was. The <dz-grid> attribute does not throw: it leaves the value out and tells an invalid-setting warning.

Example

TypeScript

import { createGrid } from '@dzgrid/dom';
import { EN } from '@dzgrid/dom/locales/en';

type Cheese = { id: string; name: string; price: number; aged: string };

const grid = createGrid<Cheese>(document.getElementById('cheeses')!, {
  rows: [{ id: 'c1', name: 'Mountain wheel', price: 1234.5, aged: '2025-11-02' }],
  columns: [
    { id: 'name', header: 'Cheese' },
    { id: 'price', header: 'Price', type: 'number' },
    { id: 'aged', header: 'Aged since', type: 'day' },
  ],
  getRowId: (c) => c.id,
  messages: EN,
  locale: 'de-CH',
});

grid.update({ locale: 'en-GB' });

Angular

import { Component } from '@angular/core';
import { DzGrid, type DzgColumnOrGroup } from '@dzgrid/angular';
import { EN } from '@dzgrid/dom/locales/en';

type Cheese = { id: string; name: string; price: number; aged: string };

@Component({
  selector: 'app-cheeses',
  imports: [DzGrid],
  template: `<dz-grid [rows]="rows" [columns]="columns" [getRowId]="rowId" [messages]="messages" locale="de-CH" />`,
})
export class Cheeses {
  readonly rows: Cheese[] = [{ id: 'c1', name: 'Mountain wheel', price: 1234.5, aged: '2025-11-02' }];
  readonly columns: DzgColumnOrGroup<Cheese>[] = [
    { id: 'name', header: 'Cheese' },
    { id: 'price', header: 'Price', type: 'number' },
    { id: 'aged', header: 'Aged since', type: 'day' },
  ];
  readonly rowId = (c: Cheese) => c.id;
  readonly messages = EN;
}

Web Component

<dz-grid locale="de-CH"></dz-grid>

import '@dzgrid/element/define';
import type { DzGridElement } from '@dzgrid/element';
import { EN } from '@dzgrid/dom/locales/en';

type Cheese = { id: string; name: string; price: number; aged: string };

const grid = document.querySelector<DzGridElement<Cheese>>('dz-grid')!;
grid.columns = [
  { id: 'name', header: 'Cheese' },
  { id: 'price', header: 'Price', type: 'number' },
  { id: 'aged', header: 'Aged since', type: 'day' },
];
grid.getRowId = (c) => c.id;
grid.messages = EN;
grid.rows = [{ id: 'c1', name: 'Mountain wheel', price: 1234.5, aged: '2025-11-02' }];

Live demo

English texts, Swiss numbers and dates (de-CH).

See also

• numerals — the language’s own digits.
• timeZone — the zone instants are shown in.
• messages — the texts’ language.