# react-native: GTProvider
URL: https://generaltranslation.com/en-US/docs/react-native/api/components/gtprovider.mdx
---
title: GTProvider
description: API reference for the GTProvider component
---

## Overview

The `<GTProvider>` component provides General Translation (GT) context to its children, enabling them to access translated content.
It is required for any client-side translations on your application.

### When to use

- Wrap your entire application in `<GTProvider>` to enable translations on the client.
- The `<GTProvider>` component is used for both [inline `<T>`](/docs/react-native/guides/t) and [dictionaries](/docs/react-native/guides/dictionaries).

## Reference

### Props

<TypeTable
  type={{
    children: {
      type: 'ReactNode',
      optional: false,
    },
    projectId: {
      type: 'string',
      optional: true,
    },
    'dictionary?': {
      type: 'Dictionary',
      optional: true,
      default: 'defaultDictionary',
    },
    'locales?': {
      type: 'string[]',
      optional: true,
    },
    'defaultLocale?': {
      type: 'string',
      optional: true,
      default: 'libraryDefaultLocale',
    },
    'locale?': {
      type: 'string',
      optional: true,
    },
    'cacheUrl?': {
      type: 'string',
      optional: true,
      default: "'https://cdn.gtx.dev'",
    },
    'runtimeUrl?': {
      type: 'string',
      optional: true,
      default: "'https://runtime.gtx.dev'",
    },
    'renderSettings?': {
      type: 'RenderSettings',
      optional: true,
      default: 'defaultRenderSettings',
    },
    '_versionId?': {
      type: 'string',
      optional: true,
    },
    'devApiKey?': {
      type: 'string',
      optional: true,
    },
    'config?': {
      type: 'object',
      optional: true,
    },
    'loadTranslations?': {
      type: '(locale: string) => Promise<Record<string, any>>',
      optional: true,
    },
    'loadDictionary?': {
      type: '(locale: string) => Promise<Record<string, any>>',
      optional: true,
    },
    'region?': {
      type: 'string',
      optional: true,
    },
    'fallback?': {
      type: 'ReactNode',
      optional: true,
    },
    'customMapping?': {
      type: 'CustomMapping',
      optional: true,
    },
  }}
/>

### Description

| Prop              | Description                                                                                                                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`        | Any component or the parents of any component that needs to translate or access translation information on the client side. These should include any components using `<T>`, `useGT`, or other translation utilities. |
| `projectId?`      | The project ID required for General Translation cloud services.                                                                                                                                                       |
| `dictionary?`     | The translation dictionary for the project.                                                                                                                                                                           |
| `locales?`        | The list of approved locales for the project.                                                                                                                                                                         |
| `defaultLocale?`  | The default locale to use if no other locale is found.                                                                                                                                                                |
| `locale?`         | The current locale, if already set.                                                                                                                                                                                   |
| `cacheUrl?`       | The URL of the cache service for fetching translations.                                                                                                                                                               |
| `runtimeUrl?`     | The URL of the runtime service for fetching translations.                                                                                                                                                             |
| `renderSettings?` | The settings for rendering translations.                                                                                                                                                                              |
| `_versionId?`     | The version ID for fetching translations.                                                                                                                                                                             |
| `devApiKey?`      | The API key for development environments.                                                                                                                                                                             |
| `config?`         | A configuration object (typically imported from `gt.config.json`) containing `projectId`, `locales`, `defaultLocale`, and other settings. An alternative to passing these as individual props.                         |
| `loadTranslations?` | An async function that takes a locale string and returns the translations object for that locale. Used to load pre-generated translation files at runtime.                                                           |
| `loadDictionary?` | An async function that takes a locale string and returns the dictionary translations for that locale.                                                                                                                  |
| `region?`         | The user's region code (e.g., `US`, `GB`). Used for region-specific formatting.                                                                                                                                       |
| `fallback?`       | Custom fallback content to display while translations are loading.                                                                                                                                                     |
| `customMapping?`  | A mapping of custom component names to their React components, used when rendering translated JSX.                                                                                                                     |

### Returns

`React.JSX.Element|undefined` containing the children that were passed to this component.

## Examples

### Basic usage

Wrap your application in `<GTProvider>` to add translation to your app.
Don't forget to add a [list of supported locales](/docs/platform/supported-locales) to enable translation.

```jsx title="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import gtConfig from './gt.config.json';
import { loadTranslations } from './loadTranslations';

export default function App() {
  return (
    <GTProvider config={gtConfig} loadTranslations={loadTranslations}> {/* // [!code highlight] */}
      {/* Your app content */}
    </GTProvider>
  );
}
```

### Dictionaries

You can also pass a dictionary to the `<GTProvider>` component and then access it with the [`useTranslations`](/docs/react-native/api/dictionary/use-translations) hook.

```jsx title="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import gtConfig from './gt.config.json';
import { loadTranslations } from './loadTranslations';
import dictionary from './dictionary';

export default function App() {
  return (
    <GTProvider config={gtConfig} loadTranslations={loadTranslations} dictionary={dictionary}> {/* // [!code highlight] */}
      {/* Your app content */}
    </GTProvider>
  );
}
```

For more information on using dictionaries, check out this [guide](/docs/react-native/guides/dictionaries).

### Adding configuration

If you're not a fan of passing props directly to the `<GTProvider>` component, you can create a configuration file and pass it to the component.
It also directly integrates with the [`gt translate` command](/docs/cli/translate), so you don't have to specify things like locales manually as a parameter.

```json title="gt.config.json" copy
{
  "projectId": "your-project-id",
  "locales": ["es", "fr"],
  "defaultLocale": "en-US",
  "_versionId": "translation-version-id" // allows for rolling back to previous translations (autogenerated by the CLI)
}
```

All you have to do is just pass this to the `<GTProvider>` component.

```jsx title="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import config from './gt.config.json';

export default function App() {
  return (
    <GTProvider {...config}> {/* // [!code highlight] */}
      {/* Your app content */}
    </GTProvider>
  );
}
```

### Custom translation loader

You can use the `loadTranslations` prop to load translations from a custom source.
This is useful when you need to load translations from a different source, such as a custom API.

```jsx title="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import { loadTranslations } from './loadTranslations';

export default function App() {
  return (
    <GTProvider locales={['es', 'fr']} loadTranslations={loadTranslations}> {/* // [!code highlight] */}
      {/* Your app content */}
    </GTProvider>
  );
}
```

### Render settings

Render settings controls the loading behavior for translations.
There are two fields: `timeout` and `method`.

- `timeout` is the number of milliseconds to wait for a translation to load before showing a fallback (default: `8000ms`).
- `method` is the method to use to load translations (`"skeleton"`, `"replace"`, or `"default"`).

```jsx title="App.tsx" copy
<GTProvider renderSettings={{ method: 'skeleton', timeout: 1000 }}>
  {/* Your app content */}
</GTProvider>
```

Each render setting dictates different loading behavior:
`"skeleton"` will return `null` until the translations are loaded.
`"replace"` will return the fallback content until the translations are loaded.
`"default"` will return `null` until the translations are loaded, unless the fallback locale has the same language as the current locale (i.e., `en-US` and `en-GB`).
In this case, it will return the fallback content immediately until the translations are loaded.

---

## Notes

- The `<GTProvider>` must wrap all [`<T>` components](/docs/react-native/api/components/t) and other translation-related functions. Learn more [here](/docs/react-native/api/components/gtprovider).

## Next steps

- Learn more about the [`<T>` component](/docs/react-native/guides/t) for translating text and components.