# useLocale

> A React hook for the locale numbers, dates and prices are formatted with, the same on the server and in the browser.

- Type: React hook (Hooks & Utilities)
- Access: Free (the source is open to everyone)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add use-locale`
- Docs: https://wingo-ui.com/components/use-locale

## Interaction

The card formats one price, one date and one count with the resolved locale. Leave the locale empty to follow the page and the browser (after hydration), or pick one to see a component's own locale prop win. The provider example pins de-DE for everything inside it, on the server too.

## Installation

```bash
npx wingo-ui@latest add use-locale
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/use-locale.json`

Files:

- `hooks/use-locale.ts`

## Usage

```tsx
import { LocaleProvider, useLocale } from "@/hooks/use-locale"

export function Price({ value, locale }: { value: number; locale?: string }) {
  const resolved = useLocale(locale)
  return <span>{new Intl.NumberFormat(resolved, { style: "currency", currency: "USD", currencyDisplay: "narrowSymbol" }).format(value)}</span>
}

export function App({ children }: { children: React.ReactNode }) {
  // everything inside formats as en-GB, on the server and in the browser
  return <LocaleProvider locale="en-GB">{children}</LocaleProvider>
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `locale?` | `string` | `""` | useLocale(locale?): a component's own locale prop, which wins when set. Empty falls back to the nearest LocaleProvider, then (after hydration) <html lang> and the browser's language. |
| `returns?` | `string` |  | A canonical BCP 47 tag. On the server and during hydration it is the provider's locale or DEFAULT_LOCALE ("en-US"), so both renders print the same text; the browser's language arrives right after. |

## Parts

### LocaleProvider (component)

Pins the locale for everything inside it, on the server too, so nothing swaps after hydration. Put one in the root layout of a Romanian app. Props: ({ locale: string; children }) => JSX.Element.

### getBrowserLocale (function)

The page's lang, then navigator.language, for code outside React (event handlers). DEFAULT_LOCALE is the server fallback. Signature: () => string.

### DEFAULT_LOCALE (constant)

The fallback locale, "en-US", used on the server and during hydration when no prop or provider sets one.

## Examples

- **One provider per storefront**: The same order card under an en-US and an en-GB LocaleProvider: dates and separators follow, the server render matches.
- **A component's own locale wins**: Inside an en-US provider, the second card passes locale="fr-FR" and useLocale returns it first.

## See also

- [Number format](https://wingo-ui.com/components/number-format) ([Markdown](https://wingo-ui.com/components/number-format.md))
- [Date utils](https://wingo-ui.com/components/date-utils) ([Markdown](https://wingo-ui.com/components/date-utils.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))

---

Canonical: https://wingo-ui.com/components/use-locale
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt