# General Translation React SDKs (gt-react, gt-next, gt-react-native): <LocaleSelector>
URL: https://generaltranslation.com/en-US/docs/react/reference/components/locale-selector.mdx
---

title: "<LocaleSelector>"
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'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'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's refresh, reload, or navigation behavior. 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**

A mapping of locale codes to custom option labels. String values are used directly; object values use their `name` property from [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties). Other locale properties do not change 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 forwarded 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).