# General Translation React SDKs (gt-react, gt-next): useRegionSelector
URL: https://generaltranslation.com/en-US/docs/react/reference/hooks/use-region-selector.mdx
---

title: useRegionSelector
description: Build a custom region switcher with General Translation gt-react. API reference for useRegionSelector.

---

The `useRegionSelector` hook returns the data and handlers needed to build a custom region selector: the active region, available regions, region metadata, and functions to update the region or locale.

*Available in `gt-react` and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.*

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

## Overview [#overview]

Call `useRegionSelector` and wire its values into your own UI.

```tsx
'use client';
import { useRegionSelector } from 'gt-react';

export default function CustomRegionSelector() {
  const { region, setRegion, regions, regionData } = useRegionSelector({ // [!code highlight]
    customMapping: { US: { name: 'United States', emoji: '🇺🇸' } }, // [!code highlight]
  });

  return (
    <select value={region} onChange={(e) => setRegion(e.target.value)}>
      {regions.map((r) => (
        <option key={r} value={r}>
          {regionData.get(r)?.emoji} {regionData.get(r)?.name}
        </option>
      ))}
    </select>
  );
}
```

*Note: `useRegionSelector` is client-side only and must be used under a [`<GTProvider>`](/docs/react/reference/components/gt-provider). If you do not need a custom UI, use the [`<RegionSelector>`](/docs/react/reference/components/region-selector) component instead.*

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

The hook returns the active region, the ordered list of regions, a `regionData` map of display metadata, and setters for the region and locale. When `regions` is not provided, the available regions are inferred from the supported locales.

## Parameters [#parameters]

`useRegionSelector` accepts an optional configuration object.

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`regions`](#regions) | Subset of ISO 3166 region codes to display. | `string[]` | Yes | Inferred |
| [`customMapping`](#custom-mapping) | Custom display names, emojis, or locales per region. | `object` | Yes | — |
| [`prioritizeCurrentLocaleRegion`](#prioritize) | Put the current locale's region first. | `boolean` | Yes | `true` |
| [`sortRegionsAlphabetically`](#sort) | Sort regions alphabetically by display name. | `boolean` | Yes | `true` |

### `regions` [#regions]

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

ISO 3166 region codes to display. When omitted, regions are inferred from the supported locales.

### `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 prioritized in the list.

### `sortRegionsAlphabetically` [#sort]

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

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

## Returns [#returns]

**Type** `object`

| Field | Description | Type |
| --- | --- | --- |
| `region` | The currently selected region code. | `string \| undefined` |
| `setRegion` | Update the selected region. | `(region: string \| undefined) => void` |
| `regions` | Available region codes. | `string[]` |
| `regionData` | Map of region codes to display data (`code`, `name`, `emoji`, `locale`). | `Map<string, RegionData>` |
| `locale` | The current locale. | `string` |
| `setLocale` | Update the locale. | `(locale: string) => void` |
| `localeRegion` | The ISO 3166 region code of the current locale. | `string` |

## Notes [#notes]

- `useRegionSelector` is client-side only.
- For a ready-made dropdown, use [`<RegionSelector>`](/docs/react/reference/components/region-selector).
- For the locale equivalent, see [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector).