Skip to Content
Labels

Labels

Some components contain English text of their own: the accessible names of icon buttons (the Combobox chevron, the remove button of a Chip), screen-reader text (the “More pages” of Pagination.Ellipsis) and visible defaults (the month and weekday names of Calendar, the “Pick a date” of DatePicker). Each of these components takes a labels prop that replaces this text, for example to translate it.

Translate a component

Pass only the keys you want to change. The keys you leave out keep their English default.

<Combobox.Root
  items={["Jabłko", "Banan"]}
  labels={{ trigger: "Pokaż opcje", clear: "Wyczyść wybór", chipRemove: "Usuń" }}
>
  {/* The parts read the labels from Combobox.Root */}
</Combobox.Root>

Text that depends on data is a function. The Calendar keys get the date they describe, so you can pass Intl formatters:

<Calendar
  weekStartsOn={1}
  labels={{
    previousMonth: "Poprzedni miesiąc",
    nextMonth: "Następny miesiąc",
    heading: (date) => date.toLocaleDateString("pl-PL", { month: "long", year: "numeric" }),
    weekday: (date) => date.toLocaleDateString("pl-PL", { weekday: "short" }),
    weekdayLong: (date) => date.toLocaleDateString("pl-PL", { weekday: "long" }),
    day: (date) => date.toLocaleDateString("pl-PL", { dateStyle: "full" }),
  }}
/>

The column headers show weekday, and screen readers read weekdayLong in its place, so translate both. If you leave out weekdayLong, screen readers read your weekday text. The Calendar functions get each date at local midnight. Format it in the user’s time zone, as toLocaleDateString does by default. With timeZone: "UTC", a user east of UTC sees the day before.

Calendar, DatePicker and Slider take functions in labels. A React Server Component cannot pass a function to a client component, and every chunks-ui component is one (see Server components). Pass function labels from a client component (a file that starts with "use client"), for example a small wrapper that holds your translations. String labels can come from a server component, which can also call the function defaults, for example DEFAULT_CALENDAR_LABELS.day(date).

There is no provider that sets the labels of all components. To use the same translation in many places, keep it in a constant and pass it to each component:

import type { ComboboxLabels } from "chunks-ui";
 
export const PL_COMBOBOX: Partial<ComboboxLabels> = {
  trigger: "Pokaż opcje",
  clear: "Wyczyść wybór",
  chipRemove: "Usuń",
};

Each component exports the type of its labels as <Component>Labels (ComboboxLabels) and the English defaults as DEFAULT_<COMPONENT>_LABELS (DEFAULT_COMBOBOX_LABELS). The defaults are typed read-only: change the text with labels, not by writing to the defaults.

Read the defaults in a server component

chunks-ui starts with "use client". In a React Server Component, each of its exports is a client reference, so DEFAULT_COPY_BUTTON_LABELS.copy from chunks-ui is not the string. Import the defaults and the <Component>Labels types from chunks-ui/utils. This entry has no "use client" and no React code (see Server components):

// app/keys/page.tsx: a server component
import { CopyButton } from "chunks-ui";
import { DEFAULT_COPY_BUTTON_LABELS } from "chunks-ui/utils";
 
export default function KeysPage() {
  return (
    <CopyButton
      value="sk-test-123"
      labels={{ copy: `${DEFAULT_COPY_BUTTON_LABELS.copy}: API key` }}
    />
  );
}

The button reads “Copy to clipboard: API key”. chunks-ui and chunks-ui/utils export the same objects, so a client component can import the defaults from either entry.

What takes precedence

  • An aria-label on a part wins over labels: <Combobox.Trigger aria-label="Show fruits" /> keeps that name.
  • A prop that already sets the same text wins too: placeholder on DatePicker, label on ClearButton (deprecated: use labels={{ clear }}), children on Pagination.Previous and Pagination.Next, and getAriaValueText or aria-valuetext on Slider.Thumb.
  • An aria-labelledby on ClearButton turns its default name off: the button is named by the elements it references.

Remove buttons

The remove button of a Chip and Combobox.ChipRemove read their label together with the text of their chip, for example “Remove Apple”. By default the label comes first: with labels={{ remove: "Usuń" }} on a Chip, the button reads “Usuń Apple”.

To put the chip’s text somewhere else, write {chip} where it goes:

<Chip labels={{ remove: "{chip} を削除" }} onRemove={() => {}}>
  Apple
</Chip>

This button reads “Apple を削除”. On a Combobox, labels={{ chipRemove: "Supprimer {chip} ?" }} makes it read “Supprimer Apple ?”. The text before and after {chip} is joined to the chip’s text with a space, so "Delete {chip}?" reads “Delete Apple ?”. Punctuation attached to {chip} is read with a space for the same reason: aria-labelledby joins its parts with spaces. Only the first {chip} counts; a second one stays as plain text.

Components with labels

These components take labels. The Labels section of each page lists the keys and their defaults.

  • Breadcrumb: labels on Breadcrumb.Root, type BreadcrumbLabels
  • Calendar: labels on Calendar, type CalendarLabels
  • Chip: labels on Chip, type ChipLabels
  • ClearButton: labels on ClearButton, type ClearButtonLabels
  • Combobox: labels on Combobox.Root, type ComboboxLabels
  • CopyButton: labels on CopyButton, type CopyButtonLabels
  • DatePicker: labels on DatePicker, type DatePickerLabels
  • Input: labels on Input, type InputLabels
  • InputCopy: labels on InputCopy, type InputCopyLabels
  • NumberField: labels on NumberField.Root, type NumberFieldLabels
  • Pagination: labels on Pagination.Root, type PaginationLabels
  • Slider: labels on Slider.Root, type SliderLabels
  • ThemeToggle: labels on ThemeToggle, type ThemeToggleLabels
  • Toast: labels on Toast.Viewport, type ToastLabels

One string cannot be changed: while a Combobox popup is open, Base UI adds visually hidden “Dismiss” buttons for screen readers around it, and they take no props.

Last updated on
Utilities