React Navigation

CallstackOfficialPublished by Callstack

Skill
Tool integration
Software development
MIT
No issues found

From the author

Provides React Navigation UI patterns for stacks, tabs, drawers etc. Use when building navigation UIs with React Navigation, configuring headers, bottom sheets or handling safe areas and insets.

— the description by Callstack

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured reference for building navigation interfaces in React applications using React Navigation 7. It covers both the modern Static API and the traditional Dynamic API, offering guidance on implementing stacks, tabs, drawers, and sheets. The documentation includes best practices for configuring headers, handling safe areas, and managing navigation state across different platforms.

What it does

Provides patterns for implementing stack, tab, and drawer navigation.
Explains how to configure headers and navigation UI elements.
Offers guidance on handling safe areas and screen insets.
Demonstrates how to integrate icons and custom backgrounds into navigation components.
Supports both Static and Dynamic API styles for navigation configuration.
Includes techniques for programmatic navigation control and scroll-to-top functionality.

When to use it

When building navigation structures for React-based mobile or web applications.
When you need to implement consistent UI patterns like sidebars, bottom tabs, or modals.
When configuring platform-specific navigation behaviors or safe-area insets.
When migrating or setting up navigation in a React Navigation 7 environment.

Advantages

Provides clear API selection guidance for new and existing projects.
Offers standardized patterns for common navigation UI components.
Includes practical code examples for both Static and Dynamic APIs.
Addresses cross-platform layout requirements for web and mobile.

Usage examples

“How do I create a bottom tab navigator in React Navigation 7?”: The skill provides code snippets for both Static and Dynamic APIs, showing how to use createBottomTabNavigator and configure tab icons.
“How can I handle safe areas in my navigation header?”: The skill directs you to the safe-areas reference, explaining how to manage status bar and header insets for a consistent UI.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/callstackincubator/react-navigation/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip react-navigation.zip -d .agents/skills

Documentation by Callstack

Overview

Guide for building navigation UIs with React Navigation.

This skill only applies to React Navigation 7. The API and patterns may not work with different versions.

API Selection

React Navigation offers two API - object-based Static API and component-based Dynamic API.

Existing Apps: Check the current navigation setup and follow the same API style when using the references
New Apps: If the app does not have an existing navigation setup yet, prefer Static API

When to Apply

Reference this skill when:

Building navigation UI patterns such as stacks, tabs, drawers, sheets etc.
Configuring headers and other built-in navigator UI
Handling safe areas and insets in navigation UI

References

File	Description
stacks.md	Stack based navigation
form-sheet.md	Bottom sheet and form sheets
bottom-tabs.md	Cross-platform bottom tabs
native-bottom-tabs.md	Native bottom tabs
material-top-tabs.md	Swipeable Top tabs
drawers.md	Drawer navigation and sidebars
header.md	Configuring headers
safe-areas.md	Safe-area handling

Problem -> Skill Mapping

Problem	Start With
Showing screens and modals in a stack	stacks.md
Showing bottom sheets or form sheets	form-sheet.md
Showing screens in bottom tabs or responsive sidebars with web support	bottom-tabs.md
Showing screens in native tabs on iOS & Android	native-bottom-tabs.md
Showing content in swipeable top tabs	material-top-tabs.md
Using a drawer or sidebar	drawers.md
Configuring the header in bottom tab or drawer navigator	header.md
Handling safe-area such as status bar, header insets, tab bar insets etc.	safe-areas.md

Files

ATTRIBUTION.mdAdded by AutoGineer851 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md3.3 KiB
agents/openai.yaml268 B
references/bottom-tabs.md12.7 KiB
references/drawers.md12.0 KiB
references/form-sheet.md8.0 KiB
references/header.md6.8 KiB
references/material-top-tabs.md11.5 KiB
references/native-bottom-tabs.md8.7 KiB
references/safe-areas.md3.8 KiB
references/stacks.md11.7 KiB

references/stacks.md

Skill: Native Stack Navigator

Description

Use createNativeStackNavigator for screen-to-screen flows.

When to Use

Building the default push-based flow for an app
Using platform-native headers, large titles, or a native search bar
Presenting modal or sheet screens with native-stack presentations

Basic Example

Static API

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const AppStack = createNativeStackNavigator({
  screens: {
    Home: HomeScreen,
    Profile: ProfileScreen,
  },
});

Dynamic API

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen name="Profile" component={ProfileScreen} />
    </Stack.Navigator>
  );
}

Common Features

Large Title

Use headerLargeTitleEnabled: true for an iOS large title that collapses into the regular header on scroll.

Static API

const AppStack = createNativeStackNavigator({
  screens: {
    Library: {
      screen: LibraryScreen,
      options: {
        headerLargeTitleEnabled: true,
      },
    },
  },
});

Dynamic API

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen
        name="Library"
        component={LibraryScreen}
        options={{
          headerLargeTitleEnabled: true,
        }}
      />
    </Stack.Navigator>
  );
}

Only supported on iOS.
The scroll view in the screen must use contentInsetAdjustmentBehavior="automatic".
Don't set a background color on the header if large title is enabled as it makes title invisible on iOS 26.
Don't set headerTransparent: false if large title is enabled.
If the scrollable area does not fill the screen, the large title will not collapse on scroll.

Header Search Bar

Use headerSearchBarOptions to render a native search bar. If the search configuration depends on screen state, update it with navigation.setOptions(...).

Static API

const AppStack = createNativeStackNavigator({
  screens: {
    Search: {
      screen: SearchScreen,
      options: {
        headerSearchBarOptions: {
          placeholder: 'Search',
        },
      },
    },
  },
});

Dynamic API

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen
        name="Search"
        component={SearchScreen}
        options={{
          headerSearchBarOptions: {
            placeholder: 'Search',
          },
        }}
      />
    </Stack.Navigator>
  );
}

The scroll view in the screen must use contentInsetAdjustmentBehavior="automatic".
If the screen doesn't have a scroll view, use headerTopInsetEnabled: true.

Header Buttons and Custom Content

Use unstable_headerLeftItems and unstable_headerRightItems for native iOS header buttons or menus. Use headerLeft, headerRight, headerTitle, and headerBackground for custom React content, and as a fallback on other platforms.

Static API

import { Button, Text, View } from 'react-native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const AppStack = createNativeStackNavigator({
  screens: {
    Profile: {
      screen: ProfileScreen,
      options: {
        headerTitle: ({ tintColor, children }) => (
          <Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
        ),
        headerBackground: () => (
          <View style={{ flex: 1, backgroundColor: '#fff' }} />
        ),
        unstable_headerLeftItems: () => [
          {
            type: 'button',
            label: 'Edit',
            onPress: () => {
              // Do something
            },
          },
        ],
        unstable_headerRightItems: () => [
          {
            type: 'button',
            label: 'Done',
            icon: {
              type: 'sfSymbol',
              name: 'checkmark',
            },
            onPress: () => {
              // Do something
            },
          },
        ],
        headerLeft: ({ tintColor }) => (
          <Button title="Edit" color={tintColor} onPress={() => {}} />
        ),
        headerRight: ({ tintColor }) => (
          <Button title="Done" color={tintColor} onPress={() => {}} />
        ),
      },
    },
  },
});

Dynamic API

import { Button, Text, View } from 'react-native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen
        name="Profile"
        component={ProfileScreen}
        options={{
          headerTitle: ({ tintColor, children }) => (
            <Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
          ),
          headerBackground: () => (
            <View style={{ flex: 1, backgroundColor: '#fff' }} />
          ),
          unstable_headerLeftItems: () => [
            {
              type: 'button',
              label: 'Edit',
              onPress: () => {
                // Do something
              },
            },
          ],
          unstable_headerRightItems: () => [
            {
              type: 'button',
              label: 'Done',
              icon: {
                type: 'sfSymbol',
                name: 'checkmark',
              },
              onPress: () => {
                // Do something
              },
            },
          ],
          headerLeft: ({ tintColor }) => (
            <Button title="Edit" color={tintColor} onPress={() => {}} />
          ),
          headerRight: ({ tintColor }) => (
            <Button title="Done" color={tintColor} onPress={() => {}} />
          ),
        }}
      />
    </Stack.Navigator>
  );
}

unstable_headerLeftItems and unstable_headerRightItems are only supported on iOS and override headerLeft and headerRight when both are specified.
Use headerLeft when replacing the back button. Add headerBackVisible: true if the back button should still be shown alongside the custom left element.
headerTitle is useful when the title needs custom typography or extra layout, but custom title elements do not animate with the native title transition.
Use headerBackground for a gradient, image, or custom background view. For translucent native headers on iOS, prefer headerTransparent: true with scrollEdgeEffects for iOS 26+ or headerBlurEffect for earlier versions.
Some behavior differs between iOS versions. On iOS 26+, unstable_headerRightItems can collapse into the system overflow menu when there is not enough space.
Custom items with type: 'custom' in unstable_headerRightItems are not collapsed into the overflow menu.
Labels are used when items collapse into the overflow menu, and for accessibility.

Screen Presentations

Use the screen presentation option to control whether a screen is pushed normally or shown as a modal or sheet.

Static API

const AppStack = createNativeStackNavigator({
  screens: {
    Home: HomeScreen,
    Compose: {
      screen: ComposeScreen,
      options: {
        presentation: 'modal',
        animation: 'slide_from_bottom',
      },
    },
  },
});

Dynamic API

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen
        name="Compose"
        component={ComposeScreen}
        options={{
          presentation: 'modal',
          animation: 'slide_from_bottom',
        }}
      />
    </Stack.Navigator>
  );
}

Use card for the default push presentation.
Use modal for a standard modal presentation.
Use containedModal for a current-context modal presentation on iOS and the default modal presentation on Android.
Use fullScreenModal when the screen should take over the whole screen. On iOS, this presentation cannot be dismissed by gesture.
Use transparentModal or containedTransparentModal when the previous screen should remain visible behind translucent content.
Use formSheet when the design calls for a native sheet. Use form-sheet.md for detents and platform-specific caveats.
Use the animation option in the section below when the default transition does not fit the flow.

Transition Animations

Use animation option to customize the transition animation.

Static API

const AppStack = createNativeStackNavigator({
  screens: {
    Home: HomeScreen,
    Details: {
      screen: DetailsScreen,
      options: {
        animation: 'fade_from_bottom',
        animationDuration: 300,
      },
    },
  },
});

Dynamic API

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen
        name="Details"
        component={DetailsScreen}
        options={{
          animation: 'fade_from_bottom',
          animationDuration: 300,
        }}
      />
    </Stack.Navigator>
  );
}

Supported animation values include default, fade, fade_from_bottom, simple_push, slide_from_bottom, slide_from_right, slide_from_left, flip, and none.
flip requires presentation: 'modal' on iOS.
slide_from_right and slide_from_left fall back to the default transition on iOS.
simple_push removes the shadow and native header transition on iOS and falls back to the default transition on Android.
Use animationTypeForReplace: 'pop' when navigation.replace(...) should feel like going back, such as auth or onboarding flows.
Use animationDuration on iOS to tune slide_from_bottom, fade_from_bottom, fade, and simple_push. It does not apply to default, flip, or screens presented as modal or formSheet.
Gesture-related transition options are only supported on iOS.
Use gestureEnabled to disable swipe-to-dismiss when the animation should only run programmatically.
Use fullScreenGestureEnabled to start the dismiss gesture anywhere on the screen. This uses simple_push-style behavior, and the default iOS transition cannot be matched due to platform limitations.
Use animationMatchesGesture when the interactive dismiss gesture should follow the animation option. It does not affect screens presented modally.
Use fullScreenGestureShadowEnabled to control the shadow shown during a full-screen dismiss gesture.
On iOS, gestureDirection: 'vertical' implies animation: 'slide_from_bottom' together with full-screen dismissal gestures.

Notes

For scrollable content and contentInsetAdjustmentBehavior="automatic", native stack needs it to be in the first-descendant chain — no views should be rendered before the scrollable view.

Canonical Docs

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Callstack

Publisher

Callstack (Official)

Source

callstackincubator/agent-skills · skills/react-navigation · commit 59e9d17

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Callstack.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react-navigation.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Callstack