Locale and Direction

Headless Locale and Direction; covers HTML dir, HTML lang, Intl.Locale.


Package	`@vizejs/ui/locale`
Maturity	stable
Own the source	`vize lib pull locale`
Requires	context
Aliases	direction, rtl, writing mode, i18n provider
Covers	HTML dir, HTML lang, Intl.Locale

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { LocaleProvider } from "@vizejs/ui/locale";

Or copy the source into your project with vize lib pull locale (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Locale provider that switches language and direction for a subtree and formats a price in it. -->
<script setup lang="ts">
import { ref, useId } from "vue";

import { LocaleProvider, resolveListFormatter, resolveNumberFormatter } from "@vizejs/ui/locale";

const locale = ref("en-US");
const selectId = useId();
const locales = [
  { value: "en-US", label: "English (United States)" },
  { value: "de-DE", label: "Deutsch (Deutschland)" },
  { value: "ar-EG", label: "العربية (مصر)" },
];

function formatPrice(tag: string): string {
  return resolveNumberFormatter(tag, { style: "currency", currency: "EUR" }).format(1299.5);
}
</script>

<template>
  <div>
    <label :for="selectId">Language</label>
    <select :id="selectId" v-model="locale">
      <option v-for="item in locales" :key="item.value" :value="item.value">
        {{ item.label }}
      </option>
    </select>
    <LocaleProvider v-slot="{ locale: active, direction }" :locale direction="auto">
      <p>Price: {{ formatPrice(active) }}</p>
      <p>
        Direction: {{ direction }}; ships in
        {{ resolveListFormatter(active).format(["S", "M", "L"]) }}
      </p>
    </LocaleProvider>
  </div>
</template>

API

`LocaleProvider`

Source: src/families/i18n/locale/locale-provider.vue

Props

Prop	Type	Default	Description
`locale`	`string`	`"en-US"`	BCP 47 locale for the subtree.
`direction`	`DirectionPreference`	`"ltr"`	Writing direction. `auto` resolves from the locale when possible.
`numberingSystem`	`string`	`undefined`	Intl numbering system for formatter composables in the subtree.
`calendar`	`string`	`undefined`	Intl calendar system for date-time formatter composables in the subtree.
`timeZone`	`string`	`"UTC"`	IANA time-zone identifier for date-time and Temporal adapters.
`timeZoneDisambiguation`	`LocaleTimeZoneDisambiguation`	`"compatible"`	Temporal-compatible policy for DST gaps and overlaps.

Slots

Slot	Slot props	Description
`default`	`{ readonly locale: string; readonly direction: TextDirection; readonly numberingSystem: string \| undefined; readonly calendar: string \| undefined; readonly timeZone: string; readonly timeZoneDisambiguation: LocaleTimeZoneDisambiguation; }`	Localized subtree. Receives the resolved locale, direction, and formatter defaults.

Behavior

Normative state × input → outcome table for locale-provider.vue (@vizejs/ui/locale). Every row is proven by the named test in src/families/i18n/locale/locale.test.ts or src/families/i18n/locale/locale-ssr.test.ts; compile-only assertions live in src/families/i18n/locale/locale.types.test-d.ts.

#	State	Input	Outcome	Proven by
I1	provider	default props	`lang=en-US` and `dir=ltr`	`provides default locale and direction`
I2	provider	`locale` and `direction=rtl`	subtree lang/dir and slot props update	`publishes an explicit rtl locale`
I3	provider	numbering, calendar, time zone, DST policy	slot props, data attributes, and formatter defaults update	`publishes formatter defaults through context and slot props`
I4	provider	`direction=auto` with RTL tag	resolved direction is `rtl` when the engine can tell	`resolves auto direction from the locale`
I5	locale helper	invalid or lower-case locale tags	canonical locale or `en-US` fallback is used	`canonicalizes invalid locale tags before formatter construction`
I6	provider	formatter composables with options	number, date, list, and relative-time use provider locale	`resolves formatters from the provider locale and explicit options`
I7	provider	display-name and search-collator helpers	localized code names and accent-insensitive search compare	`resolves display names and search collators from the provider locale`
I8	locale helper	decomposed Unicode and whitespace	text is NFC-normalized before exact, prefix, or contains	`matches normalized locale text with exact, prefix, and contains policies`
I9	provider	locale or formatter options change	formatter composables update without stale Intl objects	`updates formatter composables when provider locale or options change`
I10	provider	invalid locale or formatter defaults	context, markup, direction, and formatters fall back	`normalizes invalid provider locales before publishing context`
I11	no provider	`useLocale` / `useDirection`	document or SSR fallbacks are used	`falls back without a provider`
I12	outside setup	composable call	stable setup diagnostic is thrown	`rejects composable use outside setup`
I13	SSR	identical trees	byte-identical lang and dir	SSR test
I14	SSR	provider formatter defaults	byte-identical data attributes and time-zone defaults	SSR formatter-defaults test
I15	SSR	formatter without provider	`en-US` fallback locale is used	SSR formatter test
I16	SSR	display names and search collator fallback	`en-US` formatter locale and search usage are used	SSR display/search test
I17	SSR	invalid provider locale	fallback lang and direction are rendered	SSR invalid-locale test
I18	public types	invalid direction or formatter/search opts	compilation rejects misuse	`src/families/i18n/locale/locale.types.test-d.ts`