---
title: Provider
description: Configure HeroUI Native provider with text, text input, animation, toast, and layout direction settings
icon: chevrons-expand-horizontal
---

The `HeroUINativeProvider` is the root provider component that configures and initializes HeroUI Native in your React Native application. It provides global configuration and portal management for your application.

## Overview

The provider serves as the main entry point for HeroUI Native, wrapping your application with essential contexts and configurations:

- **Safe Area Insets**: Automatically handles safe area insets updates via `SafeAreaListener` and syncs them with Uniwind for use in Tailwind classes (e.g., `pb-safe-offset-3`)
- **Text Configuration**: Global text component settings for consistency across all HeroUI components
- **Text Input Configuration**: Global text input settings for consistency across all HeroUI input components
- **Animation Configuration**: Global animation control to disable all animations across the application
- **Toast Configuration**: Global toast system configuration including insets, default props, and wrapper components
- **Layout Direction**: Global right-to-left flag used by component logic that runs in JavaScript instead of styles
- **Portal Management**: Handles overlays, modals, and other components that render on top of the app hierarchy

## Basic Setup

Wrap your application root with the provider:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}
```

## Configuration Options

The provider accepts a `config` prop with the following options:

### Text Component Configuration

Global settings for all Text components within HeroUI Native. These props are carefully selected to include only those that make sense to configure globally across all Text components in the application:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';

const config: HeroUINativeConfig = {
  textProps: {
    // Disable font scaling for accessibility
    allowFontScaling: false,

    // Auto-adjust font size to fit container
    adjustsFontSizeToFit: false,

    // Maximum font size multiplier when scaling
    maxFontSizeMultiplier: 1.5,

    // Minimum font scale (iOS only, 0.01-1.0)
    minimumFontScale: 0.5,
  },
};

export default function App() {
  return (
    <HeroUINativeProvider config={config}>
      {/* Your app content */}
    </HeroUINativeProvider>
  );
}
```

### Text Input Component Configuration

Global settings for all TextInput-based components within HeroUI Native (e.g. Input, TextArea, SearchField, InputGroup, InputOTP). These props are carefully selected to include only those that make sense to configure globally across all inputs in the application:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';

const config: HeroUINativeConfig = {
  textInputProps: {
    // Respect Text Size accessibility settings
    allowFontScaling: false,

    // Maximum font size multiplier when allowFontScaling is enabled
    maxFontSizeMultiplier: 1.5,
  },
};

export default function App() {
  return (
    <HeroUINativeProvider config={config}>
      {/* Your app content */}
    </HeroUINativeProvider>
  );
}
```

<Callout type="info">
  **Note**: These props are applied as defaults. Any prop passed directly to an individual input component overrides the corresponding global value.
</Callout>

### Animation Configuration

Global animation configuration for the entire application:

```tsx
const config: HeroUINativeConfig = {
  // Disable all animations across the application (cascades to all children)
  animation: 'disable-all',
};
```

<Callout type="warning">
  **Note**: When set to `'disable-all'`, all animations across the application will be disabled. This is useful for accessibility or performance optimization.
</Callout>

### Developer Information Configuration

Control developer-facing informational messages displayed in the console:

```tsx
const config: HeroUINativeConfig = {
  devInfo: {
    // Disable styling principles information message
    stylingPrinciples: false,
  },
};
```

<Callout type="info">
  **Note**: By default, informational messages are enabled. Set `stylingPrinciples: false` to disable the styling principles message that appears in the console during development.
</Callout>

### Toast Configuration

Configure the global toast system including insets, default props, and wrapper components. You can also disable the toast provider entirely:

**Option 1: Disable Toast Provider**

```tsx
const config: HeroUINativeConfig = {
  // Disable toast provider entirely
  toast: false,
  // or
  toast: 'disabled',
};
```

<Callout type="info">
  **Note**: When toast is disabled (`false` or `'disabled'`), the `ToastProvider` will not be rendered, and toast functionality will not be available in your application.
</Callout>

**Option 2: Configure Toast Provider**

```tsx
import { KeyboardAvoidingView } from 'react-native';

const config: HeroUINativeConfig = {
  toast: {
    // Global toast configuration (used as defaults for all toasts)
    defaultProps: {
      variant: 'default',
      placement: 'top',
      isSwipeable: true,
      animation: true,
    },
    // Insets for spacing from screen edges (added to safe area insets)
    insets: {
      top: 0,      // Default: iOS = 0, Android = 12
      bottom: 6,   // Default: iOS = 6, Android = 12
      left: 12,    // Default: 12
      right: 12,   // Default: 12
    },
    // Maximum number of visible toasts before opacity starts fading
    maxVisibleToasts: 3,
    // Custom wrapper function to wrap the toast content
    contentWrapper: (children) => (
      <KeyboardAvoidingView
        behavior="padding"
        keyboardVerticalOffset={24}
        className="flex-1"
      >
        {children}
      </KeyboardAvoidingView>
    ),
  },
};
```

### Layout Direction Configuration

Tell HeroUI Native components which layout direction they render in:

```tsx
import { I18nManager } from 'react-native';

const config: HeroUINativeConfig = {
  isRTL: I18nManager.isRTL,
};
```

Components mirror themselves with Yoga logical properties (`start`/`end`), so most of the UI flips on its own. This flag only covers logic that runs in JavaScript, such as `Slider` gesture deltas and popover `start`/`end` alignment.

<Callout type="info">
  **Note**: `isRTL` defaults to `I18nManager.isRTL`. Set it only when your app renders in a direction that differs from the global RTL state.
</Callout>

To override the direction for a subtree, wrap it with `LayoutDirectionScope`, together with Uniwind's `LayoutDirection` for the `rtl:` variants and a `direction` style for Yoga layout:

```tsx
<LayoutDirection rtl={false}>
  <View className="flex-1" style={{ direction: 'ltr' }}>
    <LayoutDirectionScope isRTL={false}>
      {children}
      <PortalHost name="preview" />
    </LayoutDirectionScope>
  </View>
</LayoutDirection>
```

<Callout type="warning">
  **Note**: Portalled content renders at the app root and escapes the scope, so render a `PortalHost` with a custom `name` inside it and pass the matching `hostName` to the overlay. In your own components, read the effective direction with the `useIsRTL` hook.
</Callout>

## Complete Example

Here's a comprehensive example showing all configuration options:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
import { I18nManager } from 'react-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

const config: HeroUINativeConfig = {
  // Global text configuration
  textProps: {
    minimumFontScale: 0.5,
    maxFontSizeMultiplier: 1.5,
    allowFontScaling: true,
    adjustsFontSizeToFit: false,
  },
  // Global text input configuration
  textInputProps: {
    allowFontScaling: true,
    maxFontSizeMultiplier: 1.5,
  },
  // Global animation configuration
  animation: 'disable-all', // Optional: disable all animations
  // Developer information messages configuration
  devInfo: {
    stylingPrinciples: true, // Optional: disable styling principles message
  },
  // Global layout direction (defaults to I18nManager.isRTL)
  isRTL: I18nManager.isRTL,
  // Global toast configuration
  // Option 1: Configure toast with custom settings
  toast: {
    defaultProps: {
      variant: 'default',
      placement: 'top',
    },
    insets: {
      top: 0,
      bottom: 6,
      left: 12,
      right: 12,
    },
    maxVisibleToasts: 3,
  },
  // Option 2: Disable toast entirely
  // toast: false,
  // or
  // toast: 'disabled',
};

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider config={config}>
        <YourApp />
      </HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}
```

## Integration with Expo Router

When using Expo Router, wrap your root layout:

```tsx
// app/_layout.tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
import { Stack } from 'expo-router';

const config: HeroUINativeConfig = {
  textProps: {
    minimumFontScale: 0.5,
    maxFontSizeMultiplier: 1.5,
  },
};

export default function RootLayout() {
  return (
    <HeroUINativeProvider config={config}>
      <Stack />
    </HeroUINativeProvider>
  );
}
```

## Architecture

### Provider Hierarchy

The `HeroUINativeProvider` internally composes multiple providers:

```
HeroUINativeProvider
├── SafeAreaListener (handles safe area insets updates)
│   └── LayoutDirectionProvider (layout direction configuration)
│       └── GlobalAnimationSettingsProvider (animation configuration)
│           └── TextComponentProvider (text configuration)
│               └── TextInputComponentProvider (text input configuration)
│                   └── ToastProvider (toast configuration, conditionally rendered)
│                       └── Your App
│                       └── PortalHost (for overlays)
```

<Callout type="info">
  **Note**: The `ToastProvider` is conditionally rendered based on the `toast` configuration. If `toast` is set to `false` or `'disabled'`, the `ToastProvider` will not be rendered, and the app content and `PortalHost` will be rendered directly under `TextInputComponentProvider`.
</Callout>

### Safe Area Insets Handling

The provider automatically wraps your application with [`SafeAreaListener`](https://appandflow.github.io/react-native-safe-area-context/api/safe-area-listener) from `react-native-safe-area-context`. This component listens to safe area insets and frame changes without triggering re-renders, and automatically updates Uniwind with the latest insets via the `onChange` callback.

## Raw Provider

`HeroUINativeProviderRaw` is a lightweight variant of `HeroUINativeProvider` designed for bundle optimization. It excludes `ToastProvider` and `PortalHost`, giving you a bare minimum starting point where you only install and add what you actually need. Its `HeroUINativeConfigRaw` config accepts the same options as `HeroUINativeConfig` except `toast`, so `textProps`, `textInputProps`, `animation`, `devInfo`, and `isRTL` all behave identically.

### When to Use

Use `HeroUINativeProviderRaw` when you want full control over which dependencies are included in your bundle. With the raw provider imported from `heroui-native/provider-raw`, the following dependencies are optional and only required if you use the corresponding components:

- **react-native-screens** -- required for overlay components (Popover, Dialog)
- **@gorhom/bottom-sheet** -- required for BottomSheet component
- **react-native-svg** -- required for components that use icons (Accordion, Alert, Checkbox, etc.)

### Setup

```tsx
import {
  HeroUINativeProviderRaw,
  type HeroUINativeConfigRaw,
} from 'heroui-native/provider-raw';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

const config: HeroUINativeConfigRaw = {
  textProps: {
    maxFontSizeMultiplier: 1.5,
  },
};

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProviderRaw config={config}>
        {/* Your app content */}
      </HeroUINativeProviderRaw>
    </GestureHandlerRootView>
  );
}
```

### Adding Toast and Portal Manually

If you need toast or portal functionality with the raw provider, add them yourself:

```tsx
import { HeroUINativeProviderRaw } from 'heroui-native/provider-raw';
import { PortalHost } from 'heroui-native/portal';
import { ToastProvider } from 'heroui-native/toast';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProviderRaw>
        <ToastProvider>
          {/* Your app content */}
          <PortalHost />
        </ToastProvider>
      </HeroUINativeProviderRaw>
    </GestureHandlerRootView>
  );
}
```

### Provider Hierarchy

```
HeroUINativeProviderRaw
├── SafeAreaListener (handles safe area insets updates)
│   └── LayoutDirectionProvider (layout direction configuration)
│       └── GlobalAnimationSettingsProvider (animation configuration)
│           └── TextComponentProvider (text configuration)
│               └── TextInputComponentProvider (text input configuration)
│                   └── Your App
```

## Best Practices

### 1. Single Provider Instance

Always use a single `HeroUINativeProvider` at the root of your app. Don't nest multiple providers:

```tsx
// ❌ Bad
<HeroUINativeProvider>
  <SomeComponent>
    <HeroUINativeProvider> {/* Don't do this */}
      <AnotherComponent />
    </HeroUINativeProvider>
  </SomeComponent>
</HeroUINativeProvider>

// ✅ Good
<HeroUINativeProvider>
  <SomeComponent>
    <AnotherComponent />
  </SomeComponent>
</HeroUINativeProvider>
```

### 2. Configuration Object

Define your configuration outside the component to prevent recreating on each render:

```tsx
// ❌ Bad
function App() {
  return (
    <HeroUINativeProvider
      config={{
        textProps: {
          /* inline config */
        },
      }}
    >
      {/* ... */}
    </HeroUINativeProvider>
  );
}

// ✅ Good
const config: HeroUINativeConfig = {
  textProps: {
    maxFontSizeMultiplier: 1.5,
  },
};

function App() {
  return (
    <HeroUINativeProvider config={config}>{/* ... */}</HeroUINativeProvider>
  );
}
```

### 3. Text Configuration

Consider accessibility when configuring text props:

```tsx
const config: HeroUINativeConfig = {
  textProps: {
    // Allow font scaling for accessibility
    allowFontScaling: true,
    // But limit maximum scale
    maxFontSizeMultiplier: 1.5,
  },
};
```

## TypeScript Support

The provider is fully typed. Import types for better IDE support:

```tsx
import { HeroUINativeProvider, type HeroUINativeConfig } from 'heroui-native';

const config: HeroUINativeConfig = {
  // Full type safety and autocomplete
  textProps: {
    allowFontScaling: true,
    maxFontSizeMultiplier: 1.5,
  },
  textInputProps: {
    allowFontScaling: true,
    maxFontSizeMultiplier: 1.5,
  },
  animation: 'disable-all', // Optional: disable all animations
  devInfo: {
    stylingPrinciples: true, // Optional: disable styling principles message
  },
  isRTL: false, // Optional: layout direction, defaults to I18nManager.isRTL
  // Toast configuration options:
  // - false or 'disabled': Disable toast provider
  // - ToastProviderProps object: Configure toast settings
  toast: {
    defaultProps: {
      variant: 'default',
      placement: 'top',
    },
    insets: {
      top: 0,
      bottom: 6,
      left: 12,
      right: 12,
    },
  },
};
```

## Related

- [Quick Start](/docs/native/getting-started/quick-start) - Basic setup guide
- [Theming](/docs/native/getting-started/theming) - Customize colors and themes
- [Styling](/docs/native/getting-started/styling) - Style components with Tailwind

