gridcn2.0.0
Theme, style, and language

Labels and i18n

Translate every grid string with one typed labels object, wire it to your i18n library, and switch the grid to right-to-left layout.

Every user-facing string lives in one typed DataGridLabels object with English defaults, except the text of the lookup editor and the comments popover. Pass a partial labels object to translate it. Lookup columns take their own labels, listed under Coverage by group. The direction prop flips the layout for right-to-left languages. The grid has no i18n dependency.

Pick a language — direction follows it.
Name
Email
Role
Age
Silent Tiger
user0@example.com
Viewer
63
Quick Lion
user1@example.com
Viewer
67
Swift Wolf
user2@example.com
Manager
40
Eager Lion
user3@example.com
User
50
Eager Tiger
user4@example.com
Viewer
45
Silent Wolf
user5@example.com
User
24
Swift Lion
user6@example.com
Viewer
34
Eager Lion
user7@example.com
Manager
21
Eager Eagle
user8@example.com
Editor
25
Bold Tiger
user9@example.com
Editor
19

The labels prop

Pass labels to DataGridProvider or DataGrid. The grid deep-merges it over DEFAULT_LABELS. Only the keys you set change, and the rest stay English:

import {
  DataGrid,
  type DeepPartialLabels,
} from "@/components/data-grid/data-grid";

const labels: DeepPartialLabels = {
  toolbar: { searchPlaceholder: "Rechercher…" },
  contextMenu: { copy: "Copier", paste: "Coller" },
  grid: { emptyState: "Aucune ligne" },
};

export function FrenchGrid() {
  return (
    <DataGrid className="h-80" defaultData={[]} columns={[]} labels={labels} />
  );
}

A label that contains a value, such as a count, is a function. The grid calls it with the values:

import type { DeepPartialLabels } from "@/components/data-grid/data-grid";

const labels: DeepPartialLabels = {
  toolbar: { searchMatches: (current, total) => `${current}/${total}` },
};

Deep merging (DeepPartialLabels)

The merge goes through plain objects key by key. A function, an array, or a string that you set replaces the default as a whole. The grid does not merge a function with the default function.

Setting toolbar.searchPlaceholder leaves every other toolbar string and every other group in English. A key that you set to undefined keeps the default.

Reading effective labels

Call useDataGridLabels() under DataGridProvider to read the merged labels. Your own controls then use the same copy as the grid:

import { useDataGridLabels } from "@/components/data-grid/data-grid";

function ClearFiltersButton() {
  const labels = useDataGridLabels();
  return <button>{labels.toolbar.clearFilters}</button>;
}

Coverage by group

DataGridLabels groups strings by the surface that owns them. Leave a group out and it stays in English.

GroupCoversOwner
toolbarsearch, filter menu, header filter, columns menudata-grid-toolbar
sortsort button, sort list, announcementsdata-grid-sort-list
filterOperatorsoperator names such as contains and gtdata-grid-toolbar
contextMenucut, copy, paste, row items, sort, pin, hide, autosizedata-grid-context-menu
keybindingsshortcuts dialog and action namesdata-grid-keybindings
markersselect-all, row checkboxes, reorder handle and announcementscore
groupinggroup row text, toggle names, menu items, announcementscore
gridempty-state, progress, and error messages, date editor, announcementscore
ioexport, import dialog, printdata-grid-io
paginationpage buttons, page size, range textdata-grid-pagination
statusBarcount, sum, average, minimum, maximum, selection textdata-grid-status-bar
viewsthe saved views button and menudata-grid-views
findReplacepanel fields, buttons, status linesdata-grid-find-replace
options.labels of a lookup columnthe lookup editordata-grid-lookup, lookup cell
labels of useDataGridCommentsthe comments popover, its menu item, and its announcementsdata-grid-comments, Comments labels

Labels reference lists every field of every group.

Some labels are functions of a count or a size, such as grid.saveRejected and io.emptyDropzoneCaption. statusBar.allSelected and statusBar.selectAllMatching receive null for an unknown result size.

keybindings.actions maps an action to its name. The defaults name the built-in actions. A custom action from commands that the map leaves out gets a name made from its own id.

Full German example

A representative override. Every key that it leaves out keeps its English default:

import type { DeepPartialLabels } from "@/components/data-grid/data-grid";

const de: DeepPartialLabels = {
  toolbar: {
    searchPlaceholder: "Suchen…",
    filter: "Filter",
    addFilter: "Filter hinzufügen",
    clearFilters: "Alle löschen",
    filterConnectorAnd: "Und",
    filterConnectorOr: "Oder",
    columns: "Spalten",
  },
  contextMenu: {
    cut: "Ausschneiden",
    copy: "Kopieren",
    paste: "Einfügen",
    duplicateRows: (n) => (n > 1 ? "Zeilen duplizieren" : "Zeile duplizieren"),
    deleteRow: "Zeile löschen",
    pinStart: "Am Anfang anheften",
    pinEnd: "Am Ende anheften",
    autosize: "Spaltenbreite anpassen",
  },
  grid: {
    emptyState: "Keine Zeilen",
    noResults: "Keine Ergebnisse",
    saveRejected: (n) => `${n} nicht gespeichert`,
    loading: "Wird geladen…",
    rowsChecked: (n) => `${n} ${n === 1 ? "Zeile" : "Zeilen"} ausgewählt`,
  },
};

Wire an i18n library

labels is a plain object, so it works with any i18n library. Build it from your translate function:

import {
  DataGrid,
  type DeepPartialLabels,
} from "@/components/data-grid/data-grid";

export function OrdersGrid({ t }: { t: (key: string) => string }) {
  const labels: DeepPartialLabels = {
    toolbar: { searchPlaceholder: t("toolbar.searchPlaceholder") },
    grid: { emptyState: t("grid.emptyState") },
  };

  return (
    <DataGrid className="h-80" defaultData={[]} columns={[]} labels={labels} />
  );
}

t stands for the translate function of your i18n library.

The grid compares labels by content, so a literal object of strings needs no useMemo. A label that is a function, such as pasteBlocked, counts as changed unless it keeps its identity. Define such a label at module scope, or build the object with useMemo keyed on your active locale.

Locale

The locale prop of the provider is a BCP 47 tag such as "de-DE". It sets the language of the number columns that have options.format and the date columns that have options.displayFormat, the status bar, and the default labels. It also sets the sort language unless you pass sortLocale. It defaults to "en-US", so the server and the browser render the same text.

options.locale of a column and formatValue of the status bar win over locale. A column options.locale without a format groups the digits of a number cell and shows the medium date style in a date cell. A column with no format and no options.locale shows the plain number or the ISO text. See Built-in cell types.

RTL layout

labels does not flip the layout. direction flips the layout and does not translate. Most apps derive both from one active locale:

import {
  DataGridBody,
  DataGridHeader,
  DataGridProvider,
  DataGridRoot,
  type DeepPartialLabels,
} from "@/components/data-grid/data-grid";

const TRANSLATIONS = {
  en: {
    dir: "ltr",
    locale: "en-US",
    labels: { toolbar: { searchPlaceholder: "Search…" } },
  },
  ar: {
    dir: "rtl",
    locale: "ar-EG",
    labels: { toolbar: { searchPlaceholder: "بحث…" } },
  },
} as const satisfies Record<
  string,
  { dir: string; locale: string; labels: DeepPartialLabels }
>;

export function LocaleGrid({ locale }: { locale: keyof typeof TRANSLATIONS }) {
  const { dir, labels, locale: tag } = TRANSLATIONS[locale];
  return (
    <DataGridProvider
      defaultData={[]}
      columns={[]}
      labels={labels}
      locale={tag}
    >
      <DataGridRoot className="h-80" direction={dir}>
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
    </DataGridProvider>
  );
}

Without direction, the grid reads the direction it inherits from the page at mount, and again when a dir attribute in the document changes. A grid inside <html dir="rtl"> is right-to-left with no prop. Pass direction to force one direction. With server rendering, pass direction: the server HTML is left-to-right until the grid mounts. See Server rendering.

What mirrors

Direction mirrors the column order, pinned zones, row marker column, pin shadows, resize handles, drop indicators, and the pointer math for selection and drags.

  • Arrow keys move visually. In rtl, ArrowRight moves toward the right edge of the screen, which is the previous column.
  • Tab and Shift+Tab leave the grid in both directions.
  • Home and End stay logical. Home goes to the first column in both directions.
  • Cell values render inside <bdi>, so each value reads in its own script. Cell editors carry dir="auto", so the caret follows the value.

Base UI chrome

DataGridRoot sets dir on the grid element and wraps its subtree in the direction provider of Base UI. Menus, popovers, and dialogs of the add-ons then place and navigate correctly. Portaled content that you render yourself, outside the grid, needs dir passed to it.

Set dir on the document too

The grid element carries its own dir. The page around it does not. Set dir="rtl" on <html> or on a layout wrapper so the rest of the page mirrors with the grid.

On this page