ContextQMD
Back to Heroui

Provider

apps/docs/content/docs/en/native/getting-started/(handbook)/provider.mdx

3.2.213.5 KB
Original Source

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

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 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 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)
│   └── 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 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 (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProviderRaw config={config}>
      </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>
          <PortalHost />
        </ToastProvider>
      </HeroUINativeProviderRaw>
    </GestureHandlerRootView>
  );
}

Provider Hierarchy

HeroUINativeProviderRaw
├── SafeAreaListener (handles safe area insets updates)
│   └── 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>
      <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
  },
  // 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,
    },
  },
};