---
id: react/api/use-locale
title: useLocale
---

The active locale, its direction, the switch function, and the current agreement context — the four things locale-aware UI reads.

```tsx
const { locale, direction, setLocale, context } = useLocale()
```

## Returns

### `locale`

- Type: `RegisteredLocale` — your registered locale union, narrowed by the typegen. Never a bare string.

### `direction`

- Type: `'ltr' | 'rtl'`
- Derive `dir` attributes and logical CSS from this, never from the locale tag.

### `setLocale`

- Type: `(locale: RegisteredLocale) => void`
- Reactive switch that persists the user preference. Components re-render; packs load per the loading strategy.

### `context`

- Type: the merged `LocaleScope` params (grammatical agreement).
- Read side only. Set it declaratively with [`<LocaleScope>`](./components.md) wrapping the subtree, or imperatively per key with `setParam` — a hook cannot render a provider for its own children, so there is no setter here.

## Examples

```tsx
function LocaleSwitcher() {
  const { locale, setLocale } = useLocale()
  const { t } = useTranslation('common')
  const supported = useConfig().locales.supported
  return (
    <label>
      {t('language')}
      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
        {supported.map((l) => (
          <option key={l} value={l}>{l}</option>
        ))}
      </select>
    </label>
  )
}
```

## Next

- Scoped agreement params → [`LocaleScope`](./components.md)
- Declaring context params → [stift.config.ts](../../configuration/config-file.md)
- Reading config without subscribing → [`useConfig`](./use-config.md)