# Provider **Category**: native **URL**: https://www.heroui.com/docs/native/getting-started/provider **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(handbook)/provider.mdx > Configure HeroUI Native provider with text, animation, and toast settings *** 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 - **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 - **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 ( {/* Your app content */} ); } ``` ## 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 ( {/* Your app content */} ); } ``` ### 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', }; ``` **Note**: When set to `'disable-all'`, all animations across the application will be disabled. This is useful for accessibility or performance optimization. ### Developer Information Configuration Control developer-facing informational messages displayed in the console: ```tsx const config: HeroUINativeConfig = { devInfo: { // Disable styling principles information message stylingPrinciples: false, }, }; ``` **Note**: By default, informational messages are enabled. Set `stylingPrinciples: false` to disable the styling principles message that appears in the console during development. ### 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', }; ``` **Note**: When toast is disabled (`false` or `'disabled'`), the `ToastProvider` will not be rendered, and toast functionality will not be available in your application. **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) => ( {children} ), }, }; ``` ## Complete Example Here's a comprehensive example showing all configuration options: ```tsx import { HeroUINativeProvider } from 'heroui-native'; import type { HeroUINativeConfig } from 'heroui-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 animation configuration animation: 'disable-all', // Optional: disable all animations // Developer information messages configuration devInfo: { stylingPrinciples: true, // Optional: disable styling principles message }, // 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 ( ); } ``` ## 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 ( ); } ``` ## Architecture ### Provider Hierarchy The `HeroUINativeProvider` internally composes multiple providers: ``` HeroUINativeProvider ├── SafeAreaListener (handles safe area insets updates) │ └── GlobalAnimationSettingsProvider (animation configuration) │ └── TextComponentProvider (text configuration) │ └── ToastProvider (toast configuration, conditionally rendered) │ └── Your App │ └── PortalHost (for overlays) ``` **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 `TextComponentProvider`. ### 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. ### 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 ( {/* Your app content */} ); } ``` ### 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 ( {/* Your app content */} ); } ``` ### Provider Hierarchy ``` HeroUINativeProviderRaw ├── SafeAreaListener (handles safe area insets updates) │ └── GlobalAnimationSettingsProvider (animation configuration) │ └── TextComponentProvider (text 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 {/* Don't do this */} // ✅ Good ``` ### 2. Configuration Object Define your configuration outside the component to prevent recreating on each render: ```tsx // ❌ Bad function App() { return ( {/* ... */} ); } // ✅ Good const config: HeroUINativeConfig = { textProps: { maxFontSizeMultiplier: 1.5, }, }; function App() { return ( {/* ... */} ); } ``` ### 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, }, animation: 'disable-all', // Optional: disable all animations devInfo: { stylingPrinciples: true, // Optional: disable styling principles message }, // 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