# General Translation React SDKs (gt-react, gt-next): 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 with General Translation gt-react. API reference for LocaleSelector.

---

The `<LocaleSelector>` component renders a dropdown that lets users switch the active locale. It is a client-side component.

*Available in `gt-react`, `gt-next`, and `gt-tanstack-start`. Examples import from `gt-react`; import from your framework's package instead.*

*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.

```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>` context. Provide `locales` to show a subset.
- **Switches the locale.** Selecting an option sets the active locale, which persists the choice and reloads the page.
- **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 display names or properties for locales. | `object` | 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>` context are used.

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

**Type** `object` · **Optional**

A mapping of locale codes to custom display names, emojis, or other properties. *Note: the older `customNames` prop (a plain code-to-name map) is deprecated in favor of `customMapping`.*

## 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).