Provider

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:

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:

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:

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>
  );
}

Animation Configuration

Global animation configuration for the entire application:

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.

Toast Configuration

Configure the global toast system including insets, default props, and wrapper components:

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>
    ),
  },
};

Complete Example

Here's a comprehensive example showing all configuration options:

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
  // Global toast configuration
  toast: {
    defaultProps: {
      variant: 'default',
      placement: 'top',
    },
    insets: {
      top: 0,
      bottom: 6,
      left: 12,
      right: 12,
    },
    maxVisibleToasts: 3,
  },
};

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:

// 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
├── GlobalAnimationSettingsProvider (animation configuration)
│   └── TextComponentProvider (text configuration)
│       └── ToastProvider (toast configuration)
│           └── Your App
│           └── PortalHost (for overlays)

Best Practices

1. Single Provider Instance

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

// ❌ 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:

// ❌ 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:

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:

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
  toast: {
    defaultProps: {
      variant: 'default',
      placement: 'top',
    },
    insets: {
      top: 0,
      bottom: 6,
      left: 12,
      right: 12,
    },
  },
};

Quick Start - Basic setup guide
Theming - Customize colors and themes
Styling - Style components with Tailwind

On this page