# gt-next: General Translation Next.js SDK: useRegionSelector
URL: https://generaltranslation.com/en-US/docs/next/api/helpers/use-region-selector.mdx
---
title: useRegionSelector
description: API reference for the useRegionSelector hook
---
{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */}


## Overview

The `useRegionSelector` hook provides the data and handlers needed to implement a custom region selector UI component. It returns the current region, a list of available regions, region metadata, and functions to update the region or locale.

<Callout>
    `useRegionSelector` is a client-side hook and *can only be used in client-side components*.
    Ensure your app is wrapped in a [`<GTProvider>`](/docs/next/api/components/gtprovider).
</Callout>

## Reference

### Parameters

An optional configuration object:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `regions` | `string[]` | — | An optional array of ISO 3166 region codes to display. If not provided, regions are inferred from supported locales. |
| `customMapping` | `object` | — | Optional mapping to override region display names, emojis, or associated locales. Values can be a string (display name) or an object with `name`, `emoji`, and/or `locale` properties. |
| `prioritizeCurrentLocaleRegion` | `boolean` | `true` | If true, the region corresponding to the current locale is prioritized in the list. |
| `sortRegionsAlphabetically` | `boolean` | `true` | If true, regions are sorted alphabetically by display name. |

### Returns

An object containing:

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

---

## Examples

### Build a custom region selector

```jsx title="CustomRegionSelector.jsx" copy
'use client';
import { useRegionSelector } from 'gt-next';

export default function CustomRegionSelector() {
  const { region, setRegion, regions, regionData } = useRegionSelector({ // [!code highlight]
    customMapping: { US: { name: "United States", emoji: "🇺🇸" } }, // [!code highlight]
  }); // [!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>
  );
}
```

---

## Notes

- If `regions` is not provided, the available regions are inferred from the supported locales configured in your [`gt.config.json`](/docs/next/api/config/gt-config-json).
- For a pre-built region selector, use the [`<RegionSelector>`](/docs/next/api/components/region-selector) component.

## Next steps

- See [`<RegionSelector>`](/docs/next/api/components/region-selector) for a ready-to-use dropdown component.
- See [`useRegion`](/docs/next/api/helpers/use-region) to read the current region.
- See [`useLocaleSelector`](/docs/next/api/helpers/use-locale-selector) for the locale equivalent.