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

The `<RegionSelector>` component gives users a prebuilt dropdown for selecting their region, without you needing to build a custom selector. It is a client-side component that reads region data from the [`<GTProvider>`](/docs/react/reference/components/gt-provider) context.

*Available in `gt-react` and `gt-next`.*

*Note: not exported by `gt-tanstack-start` or `gt-react-native`.*

## Overview [#overview]

Render `<RegionSelector>` inside your provider. With no props, it infers regions from the supported locales.

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

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

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

*Note: `<RegionSelector>` is client-side only, and renders a `<select>` element (or `null` when no regions are available). For a fully custom switcher, use the [`useRegionSelector`](/docs/react/reference/hooks/use-region-selector) hook.*

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

* **Reads context.** By default, regions are inferred from the supported locales in the [`<GTProvider>`](/docs/react/reference/components/gt-provider) context. Provide `regions` to display a specific set.
* **Switches the region.** Selecting an option sets the active region. With `asLocaleSelector`, it also updates the locale to the region&#39;s associated locale.
* **Pass-through props.** Any additional props are forwarded to the underlying `<select>` element.

## Props [#props]

| Prop                                           | Description                                         | Type        | Optional | Default  |
| ---------------------------------------------- | --------------------------------------------------- | ----------- | -------- | -------- |
| [`regions`](#regions)                          | Subset of ISO 3166 region codes to show.            | `string[]`  | Yes      | Inferred |
| [`placeholder`](#placeholder)                  | Placeholder content for the first option.           | `ReactNode` | Yes      | —        |
| [`customMapping`](#custom-mapping)             | Custom display names, emojis or locales per region. | `object`    | Yes      | —        |
| [`prioritizeCurrentLocaleRegion`](#prioritize) | Put the current locale&#39;s region first.          | `boolean`   | Yes      | `true`   |
| [`sortRegionsAlphabetically`](#sort)           | Sort regions alphabetically by display name.        | `boolean`   | Yes      | `true`   |
| [`asLocaleSelector`](#as-locale-selector)      | Also update the locale when a region is selected.   | `boolean`   | Yes      | `false`  |

### `regions` [#regions]

**Type** `string[]` · **Optional** · **Default** Inferred

An array of ISO 3166 region codes to display, such as `['US', 'CA', 'GB']`. When omitted, regions are inferred from the supported locales.

### `placeholder` [#placeholder]

**Type** `ReactNode` · **Optional**

Placeholder content shown as the first option when no region is selected.

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

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

A mapping of region codes to custom display data. Each value can be a string (display name) or an object with `name`, `emoji`, and/or `locale` properties.

### `prioritizeCurrentLocaleRegion` [#prioritize]

**Type** `boolean` · **Optional** · **Default** `true`

When `true`, the region matching the current locale is prioritised at the top of the list.

### `sortRegionsAlphabetically` [#sort]

**Type** `boolean` · **Optional** · **Default** `true`

When `true`, regions are sorted alphabetically by display name.

### `asLocaleSelector` [#as-locale-selector]

**Type** `boolean` · **Optional** · **Default** `false`

When `true`, selecting a region also updates the locale to the region&#39;s associated locale.

## Examples [#examples]

```tsx title="MyComponent.tsx"
import { RegionSelector } from 'gt-react';

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

```tsx title="CustomRegion.tsx"
import { RegionSelector } from 'gt-react';

export default function CustomRegion() {
  return (
    <RegionSelector
      regions={['US', 'CA', 'GB']}
      placeholder="Select a region"
      customMapping={{
        US: { name: 'United States', emoji: '🇺🇸' },
        CA: { name: 'Canada', emoji: '🇨🇦' },
        GB: { name: 'United Kingdom', emoji: '🇬🇧' },
      }}
    />
  );
}
```

## Notes [#notes]

* `<RegionSelector>` is client-side only.
* To read the active region, use [`useRegion`](/docs/react/reference/hooks/use-region); to build a custom selector, use [`useRegionSelector`](/docs/react/reference/hooks/use-region-selector).
* For the locale equivalent, see [`<LocaleSelector>`](/docs/react/reference/components/locale-selector).

## Sitemap

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