Skip to main content

useScreenOptions

A hook that provides pre-configured navigation options for React Navigation, styled with your theme.

Import​

import { useScreenOptions } from '@multinaire/ui';

Usage​

Pass the navigator type as the first argument. The hook returns a screenOptions function and helper utilities.

import { Stack } from 'expo-router';
import { useScreenOptions } from '@multinaire/ui';

export default function RootLayout() {
  const { screenOptions } = useScreenOptions('stack');

  return (
    <Stack screenOptions={screenOptions()}>
      <Stack.Screen name="index" options={{ title: 'Home' }} />
    </Stack>
  );
}

Parameters​

ParameterTypeDefaultDescription
typeNavigatorType'stack'Navigator type: 'stack', 'top-tab', 'bottom-tab', 'side-bar'

Return Value​

PropertyTypeDescription
screenOptions(overrides?) => optionsReturns themed screen options, optionally merged with your overrides
hideHeader() => { headerShown: false }Returns { headerShown: false } — spread into screen options to hide the header
title(key: TranslationKey) => stringType-safe title helper
tabBarLabel(key: TranslationKey) => stringType-safe tab label helper
tabBarIcon(icon: IconName) => tabBarIcon fnTab icon helper that receives the focused color

What's Configured​

Stack options​

  • Status bar style: Automatically adjusts based on theme mode (light/dark)
  • Header: Uses StackHeader component
  • Content style: Background color from theme

Tab options​

  • Header: Uses TabHeader component
  • Scene style: Background color from theme
  • Tab bar position: Configured for bottom, top, or side
  • Animations: Shift animation for top tabs

Examples​

Stack Navigator​

import { Stack } from 'expo-router';
import { useScreenOptions } from '@multinaire/ui';

function StackLayout() {
  const { screenOptions } = useScreenOptions('stack');

  return (
    <Stack screenOptions={screenOptions()}>
      <Stack.Screen name="home" />
      <Stack.Screen name="details" />
    </Stack>
  );
}

Bottom Tab Navigator​

import { Tabs } from 'expo-router';
import { useScreenOptions } from '@multinaire/ui';

function TabLayout() {
  const { screenOptions, tabBarIcon } = useScreenOptions('bottom-tab');

  return (
    <Tabs screenOptions={screenOptions()}>
      <Tabs.Screen
        name="home"
        options={{
          title: 'Home',
          tabBarIcon: tabBarIcon('Home'),
        }}
      />
      <Tabs.Screen
        name="profile"
        options={{
          title: 'Profile',
          tabBarIcon: tabBarIcon('Profile'),
        }}
      />
    </Tabs>
  );
}

Top Tab Navigator​

import { Tabs } from 'expo-router';
import { useScreenOptions } from '@multinaire/ui';

function TopTabLayout() {
  const { screenOptions } = useScreenOptions('top-tab');

  return (
    <Tabs screenOptions={screenOptions()}>
      <Tabs.Screen name="tab1" options={{ title: 'Tab 1' }} />
      <Tabs.Screen name="tab2" options={{ title: 'Tab 2' }} />
    </Tabs>
  );
}

Side Navigation​

import { Tabs } from 'expo-router';
import { useScreenOptions } from '@multinaire/ui';

function SideBarLayout() {
  const { screenOptions } = useScreenOptions('side-bar');

  return (
    <Tabs screenOptions={screenOptions()}>
      <Tabs.Screen name="dashboard" options={{ title: 'Dashboard' }} />
      <Tabs.Screen name="settings" options={{ title: 'Settings' }} />
    </Tabs>
  );
}

Hiding the header​

const { screenOptions, hideHeader } = useScreenOptions('stack');

<Stack screenOptions={screenOptions()}>
  <Stack.Screen name="index" options={{ title: 'Home' }} />
  <Stack.Screen name="(tabs)" options={hideHeader()} />
</Stack>

Overriding Options​

Pass an overrides object to screenOptions() — your values are merged on top of the theme defaults:

const { screenOptions } = useScreenOptions('stack');

<Stack screenOptions={screenOptions({ headerShown: false, animation: 'fade' })}>
const { screenOptions } = useScreenOptions('bottom-tab');

<Tabs screenOptions={screenOptions({ sceneStyle: { padding: 16 } })}>

Type-safe screen configuration​

When TranslationSchema is augmented, the title() and tabBarIcon() helpers are fully type-checked:

const { screenOptions, title, tabBarIcon } = useScreenOptions('bottom-tab');

<Tabs.Screen
  name="home"
  options={{
    ...screenOptions(),
    title: title('home'),          // type-checked against TranslationSchema
    tabBarIcon: tabBarIcon('Home'),
  }}
/>