# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<LocaleSelector>`
URL: https://generaltranslation.com/en-GB/docs/react/reference/components/locale-selector.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Render a dropdown for switching the active locale. API reference for the `<LocaleSelector>` component.

The `<LocaleSelector>` component is a prebuilt, client-side dropdown of your app&#39;s configured locales, so you can add a working language switcher without building your own.

*Available in `gt-react`, `gt-next`, and `gt-tanstack-start`.*

*Note: not exported by `gt-react-native`. For a custom selector, use [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector).*

## Overview [#overview]

Render `<LocaleSelector>` anywhere in a client component. With no props, it lists the configured locales.

*Examples import from `gt-react`; import from your framework&#39;s package instead.*

```tsx
import { LocaleSelector } from 'gt-react';

export default function MyComponent() {
  return <LocaleSelector />;
}
```

*Note: `<LocaleSelector>` is client-side only. For a fully custom switcher, use the [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) hook.*

## How it works [#how-it-works]

* **Reads context.** By default, the options come from the supported locales in the [`<GTProvider>`](/docs/react/reference/components/gt-provider) context. Provide `locales` to show a subset.
* **Switches the locale.** Selecting an option persists the active locale and applies the framework&#39;s refresh, reload, or navigation behaviour. See [Managing locales](/docs/react/guides/managing-locales#persistence).
* **Renders nothing when empty.** The component returns `null` when no locales are available.

## Props [#props]

| Prop                                    | Description                                                 | Type                                                  | Optional | Default       |
| --------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- | -------- | ------------- |
| [`locales`](#locales)                   | Subset of locales to show.                                  | `string[]`                                            | Yes      | All supported |
| [`customMapping`](#custom-mapping)      | Custom option labels for locales.                           | `Record<string, string \| Partial<LocaleProperties>>` | Yes      | —             |
| [`customNames`](#custom-names)          | Deprecated code-to-label mapping.                           | `Record<string, string>`                              | Yes      | —             |
| [Select attributes](#select-attributes) | Standard attributes forwarded to the underlying `<select>`. | `React.SelectHTMLAttributes<HTMLSelectElement>`       | Yes      | —             |

### `locales` [#locales]

**Type** `string[]` · **Optional** · **Default** All supported

A subset of locale codes to populate the dropdown, such as `['en', 'es-MX', 'fr']`. When omitted, the locales from the [`<GTProvider>`](/docs/react/reference/components/gt-provider) context are used.

### `customMapping` [#custom-mapping]

**Type** `Record<string, string | Partial<LocaleProperties>>` · **Optional**

Maps locale codes to custom option labels. String values are used directly; object values use the `name` property from [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties). Other locale properties do not affect the rendered label.

### `customNames` [#custom-names]

**Type** `Record<string, string>` · **Optional** · **Deprecated**

An older code-to-label mapping retained for compatibility. Use `customMapping` instead. When both props are provided, `customMapping` takes precedence.

### Select attributes [#select-attributes]

Standard `<select>` attributes such as `className`, `disabled`, and `aria-describedby` are passed through to the rendered element. The component controls `value` and `onChange`, so selecting an option updates the active locale.

## Examples [#examples]

```tsx
import { LocaleSelector } from 'gt-react';

export default function MyComponent() {
  return <LocaleSelector />;
}
```

```tsx
import { LocaleSelector } from 'gt-react';

export default function MyComponent() {
  const customMapping = {
    en: 'English',
    es: 'Español',
    'fr-CA': 'Français (Canada)',
  };
  return <LocaleSelector customMapping={customMapping} />;
}
```

## Notes [#notes]

* `<LocaleSelector>` is client-side only.
* To read the active locale, use [`useLocale`](/docs/react/reference/hooks/use-locale); to build a custom selector, use [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector).

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.