# General Translation React SDKs (gt-react, gt-next): useRegionSelector
URL: https://generaltranslation.com/en-GB/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&#39;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 that matches the current locale is prioritised 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).