Language

The words and the number and date notation the components write themselves: English by default, German in one import, and any single entry your own. Wording is a directory of named entries, not a translation call (also called i18n or localisation).

import { LanguageProvider, useWording, useFormats } from "@umriss-ui/core";

English needs nothing (ADR-0018). German ships as the subpath @umriss-ui/core/wording/de with GERMAN_WORDING and GERMAN_FORMATS, the two halves of a language; take both in one import (ADR-0019, ADR-0024).

Pass them to the language of UmrissProvider for the application, or to LanguageProvider for one section. Both merge entry by entry: what you leave out keeps its default. Every wording is typed Wording, so a whole language of your own misses no entry without a compile error.

Examples

German

Import both halves of German from @umriss-ui/core/wording/de; the components' own words and notation change, your labels stay as written.

import { useState } from "react";
import { DatePicker, FormField, LanguageProvider, NumberInput, Stack } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";

export default function German() {
  const [date, setDate] = useState<Date | null>(new Date(2026, 2, 18));
  const [weight, setWeight] = useState<number | null>(1284.5);

  return (
    <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
      <Stack direction="row" gap={3} wrap>
        <FormField label="Delivery date">
          <DatePicker value={date} onChange={setDate} clearable />
        </FormField>
        <FormField label="Weight">
          <NumberInput value={weight} onChange={setWeight} decimals={1} suffix="kg" />
        </FormField>
      </Stack>
    </LanguageProvider>
  );
}

English and German side by side

The same surface without a provider and under German: verdicts, placeholders and number notation move, the caller's labels and data stay.

import { Combobox, FormField, Grid, LanguageProvider, Stack, Stat, Text } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";

/* The p95 latency objective of the checkout service: 300 ms. */
const OBJECTIVE: LimitSet = {
  target: 250,
  limits: [
    { value: 270, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

const ENGINEERS = [
  { value: "priya", label: "Priya Raman" },
  { value: "jonas", label: "Jonas Keller" },
  { value: "ada", label: "Ada Mwangi" },
];

function Surface() {
  return (
    <Stack gap={3}>
      <Stat label="Checkout p95" value={312} unit="ms" limits={OBJECTIVE} />
      <Stat label="Search p95" value={null} unit="ms" limits={OBJECTIVE} />
      <Stat label="Requests today" value={1284311} decimals={0} />
      <FormField label="Assignee">
        <Combobox value={null} onChange={() => {}} clearable options={ENGINEERS} />
      </FormField>
    </Stack>
  );
}

export default function SideBySide() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          Without a provider
        </Text>
        <Surface />
      </Stack>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          GERMAN_WORDING and GERMAN_FORMATS
        </Text>
        <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
          <Surface />
        </LanguageProvider>
      </Stack>
    </Grid>
  );
}

Replace single entries

Pass only the entries your application says differently; every entry you leave out keeps its default, never an empty text or a key.

import { Grid, LanguageProvider, Stack, Stat, Text } from "@umriss-ui/core";
import type { LanguageOptions, LimitSet } from "@umriss-ui/core";

/* Outside the component, so the provider does not rebuild on every render. */
const WORDING: LanguageOptions["wording"] = {
  verdictOk: "Within objective",
  verdictWarning: "Objective at risk",
  verdictAlarm: "Objective breached",
};

const OBJECTIVE: LimitSet = {
  target: 250,
  limits: [
    { value: 270, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

function Surface() {
  return (
    <Stack gap={3}>
      <Stat label="Sign-in p95" value={184} unit="ms" limits={OBJECTIVE} />
      <Stat label="Search p95" value={276} unit="ms" limits={OBJECTIVE} />
      <Stat label="Checkout p95" value={312} unit="ms" limits={OBJECTIVE} />
      <Stat label="Billing p95" value={null} unit="ms" limits={OBJECTIVE} />
    </Stack>
  );
}

export default function SingleEntries() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          The defaults
        </Text>
        <Surface />
      </Stack>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          Three entries replaced
        </Text>
        <LanguageProvider wording={WORDING}>
          <Surface />
        </LanguageProvider>
      </Stack>
    </Grid>
  );
}

Write numbers in your own notation

Formats are a register of their own: replace number and count for Swiss notation and every word stays English.

import { Grid, LanguageProvider, Stack, Stat, Text } from "@umriss-ui/core";
import type { LanguageOptions } from "@umriss-ui/core";

/* Formatters are costly to build: one per number of decimals, made once. */
const swiss = new Map<number | undefined, Intl.NumberFormat>();
function number(n: number, decimals?: number) {
  let format = swiss.get(decimals);
  if (!format) {
    format = new Intl.NumberFormat("de-CH", { minimumFractionDigits: decimals, maximumFractionDigits: decimals ?? 10 });
    swiss.set(decimals, format);
  }
  return format.format(n);
}
const swissCount = new Intl.NumberFormat("de-CH");

const FORMATS: LanguageOptions["formats"] = {
  number,
  count: (n) => swissCount.format(n),
};

function Surface() {
  return (
    <Stack gap={3}>
      <Stat label="Engineering, actual March" value={196420.5} decimals={2} unit="CHF" />
      <Stat label="Invoices booked" value={1284} decimals={0} />
    </Stack>
  );
}

export default function OwnNotation() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          The default notation
        </Text>
        <Surface />
      </Stack>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          Swiss notation, English words
        </Text>
        <LanguageProvider formats={FORMATS}>
          <Surface />
        </LanguageProvider>
      </Stack>
    </Grid>
  );
}

Use the language in your own components

Read useFormats and useWording in a component of your own, and it writes dates and numbers like the library, under any provider.

import { Button, Grid, LanguageProvider, Stack, Text, useFormats, useWording } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";

const SPRINT_END = new Date(2026, 2, 27, 17, 0);

function SprintHeader() {
  const formats = useFormats();
  const wording = useWording();
  return (
    <Stack direction="row" gap={3} align="center" wrap>
      <Text size="sm">
        Sprint 14 ends <Text as="span" mono>{formats.dateTime(SPRINT_END, false)}</Text> ·{" "}
        <Text as="span" mono>{formats.count(1240)}</Text> points delivered this year
      </Text>
      <Button size="sm" variant="ghost">
        {wording.today}
      </Button>
    </Stack>
  );
}

export default function OwnComponents() {
  return (
    <Grid minItemWidth="280px" gap={5}>
      <SprintHeader />
      <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
        <SprintHeader />
      </LanguageProvider>
    </Grid>
  );
}

Wording

Charts wording

Formats

When to use something else

• The application also sets a density, a portal target or toasts → UmrissProvider

Keyboard

The keys of Button, NumberInput, Combobox and DatePicker apply here.

API

Known limits

• Two languages ship; a third is a Wording object of your own. No right-to-left (ADR-0032).
• It holds only what the components say themselves; your labels, titles and data are yours to translate.

What umriss deliberately does not build, and why: ADR-0032.

Every page of @umriss-ui/core

Getting started

• Installation
• UmrissProvider

Customising

• Theming
• Sizes
• Language

Layout

• Stack and Grid
• Divider
• Card
• Splitter

Typography

• Typography
• VisuallyHidden

Actions

• Button
• IconButton
• ButtonGroup

Forms

• Input
• FormField
• Textarea
• NumberInput
• Slider
• Checkbox
• Switch
• RadioGroup
• SegmentedControl
• FileInput

Choosing

• Select
• Combobox
• MultiSelect

Dates and times

• DatePicker
• DateTimePicker
• DateRangePicker
• DateTimeRangePicker

Feedback

• Spinner
• ProgressBar
• Skeleton
• Alert
• Toast
• EmptyState

Overlays

• Tooltip
• Popover
• Menu
• ContextMenu
• Modal
• Drawer
• ConfirmDialog
• CommandPalette

Navigation

• Breadcrumb
• Tabs
• Accordion
• Stepper
• TreeView
• Benchmark

Data display

• Badge
• Tag
• Stat
• Meter
• Sparkline

API index

• API index