# useLocale

React hook that returns the active BCP 47 locale from the nearest I18nProvider

## Import

```tsx
import { useLocale } from "@videojs/react";
```

`useLocale` returns the resolved BCP 47 tag from the nearest [`I18nProvider`](https://videojs.org/docs/framework/react/reference/api/i18n-provider), or `'en'` when none is mounted.

Use it when UI copy depends on the active locale outside the translator, for example formatting or caption language hooks.

## Example

Switch the provider locale to see `useLocale` supply the BCP 47 tag used to format a date.

**App.tsx**

```tsx
import { I18nProvider, useLocale } from '@videojs/react/i18n';
import { useState } from 'react';

import './BasicUsage.css';

const locales = ['en-US', 'fr-FR', 'ja-JP'] as const;

type Locale = (typeof locales)[number];

function LocaleDetails() {
  const locale = useLocale();
  const date = new Intl.DateTimeFormat(locale, {
    dateStyle: 'long',
    timeZone: 'UTC',
  }).format(new Date('2026-01-15T12:00:00Z'));

  return (
    <dl className="react-use-locale-basic__output">
      <div>
        <dt>Active locale</dt>
        <dd>{locale}</dd>
      </div>
      <div>
        <dt>Formatted date</dt>
        <dd lang={locale}>{date}</dd>
      </div>
    </dl>
  );
}

export default function BasicUsage() {
  const [locale, setLocale] = useState<Locale>('en-US');

  return (
    <div className="react-use-locale-basic">
      <label>
        Locale
        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
          {locales.map((value) => (
            <option key={value}>{value}</option>
          ))}
        </select>
      </label>
      <I18nProvider locale={locale}>
        <LocaleDetails />
      </I18nProvider>
    </div>
  );
}
```

**App.css**

```css
.react-use-locale-basic {
  display: grid;
  gap: 16px;
  padding: 16px;
}

.react-use-locale-basic label,
.react-use-locale-basic__output div {
  display: flex;
  gap: 8px;
  align-items: center;
}

.react-use-locale-basic select {
  padding: 4px 8px;
}

.react-use-locale-basic__output {
  display: grid;
  gap: 8px;
  margin: 0;
}

.react-use-locale-basic__output dt {
  color: #6b7280;
}

.react-use-locale-basic__output dd {
  margin: 0;
}
```

## API Reference

`useLocale(): Locale`

### Return Value

`(typeof LOCALES)[number] | string & {}`

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt