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://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/material-top-tabs.md

Skill: Material Top Tabs

Description

Use createMaterialTopTabNavigator for swipeable top tabs with a Material-style tab bar.

When to Use

Building segmented content that should switch by tap or horizontal swipe
Having a scrollable tab bar at the top of the screen

Prerequisites

Install react-native-pager-view for material top tabs to work on native platforms.

Basic Example

Static API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const HomeTabs = createMaterialTopTabNavigator({
  screens: {
    Feed: FeedScreen,
    Updates: UpdatesScreen,
  },
});

Dynamic API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const Tab = createMaterialTopTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="Feed" component={FeedScreen} />
      <Tab.Screen name="Updates" component={UpdatesScreen} />
    </Tab.Navigator>
  );
}

Common Features

Displaying Icons

Icons are hidden by default. Set tabBarShowIcon: true, then provide tabBarIcon. Optionally use tabBarActiveTintColor and tabBarInactiveTintColor to change the color passed to the icon.

Static API

import Ionicons from '@expo/vector-icons/Ionicons';
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const HomeTabs = createMaterialTopTabNavigator({
  screenOptions: ({ route }) => ({
    tabBarShowIcon: true,
    tabBarIcon: ({ focused, color }) => {
      let iconName;

      switch (route.name) {
        case 'Feed':
          iconName = focused ? 'newspaper' : 'newspaper-outline';
          break;
        default:
          iconName = focused ? 'notifications' : 'notifications-outline';
          break;
      }

      return <Ionicons name={iconName} size={18} color={color} />;
    },
    tabBarActiveTintColor: 'tomato',
    tabBarInactiveTintColor: 'gray',
  }),
  screens: {
    Feed: FeedScreen,
    Updates: UpdatesScreen,
  },
});

Dynamic API

import Ionicons from '@expo/vector-icons/Ionicons';
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const Tab = createMaterialTopTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator
      screenOptions={({ route }) => ({
        tabBarShowIcon: true,
        tabBarIcon: ({ focused, color }) => {
          let iconName;

          switch (route.name) {
            case 'Feed':
              iconName = focused ? 'newspaper' : 'newspaper-outline';
              break;
            default:
              iconName = focused ? 'notifications' : 'notifications-outline';
              break;
          }

          return <Ionicons name={iconName} size={18} color={color} />;
        },
        tabBarActiveTintColor: 'tomato',
        tabBarInactiveTintColor: 'gray',
      })}
    >
      <Tab.Screen name="Feed" component={FeedScreen} />
      <Tab.Screen name="Updates" component={UpdatesScreen} />
    </Tab.Navigator>
  );
}

The tabBarIcon option can render any React element. Choose between the icon libraries that best fit the app's design and environment:

@expo/vector-icons if Expo SDK is configured in the app
react-native-vector-icons for an app using React Native Community CLI
<Image> for local images

Scrollable Tab Bar

Use tabBarScrollEnabled: true if the list of tabs won't fit on the screen to make the tab bar scrollable. Set a fixed width for each tab with tabBarItemStyle to make the scrollable tab bar work better.

Use tabBarItemStyle with { width: 'auto' } if the tab button width should fit the label instead of being equally divided.

Static API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const HomeTabs = createMaterialTopTabNavigator({
  screenOptions: {
    tabBarScrollEnabled: true,
  },
  screens: {
    Feed: FeedScreen,
    Updates: UpdatesScreen,
    Mentions: MentionsScreen,
    Saved: SavedScreen,
    Archive: ArchiveScreen,
  },
});

Dynamic API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const Tab = createMaterialTopTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator
      screenOptions={{
        tabBarScrollEnabled: true,
      }}
    >
      <Tab.Screen name="Feed" component={FeedScreen} />
      <Tab.Screen name="Updates" component={UpdatesScreen} />
      <Tab.Screen name="Mentions" component={MentionsScreen} />
      <Tab.Screen name="Saved" component={SavedScreen} />
      <Tab.Screen name="Archive" component={ArchiveScreen} />
    </Tab.Navigator>
  );
}

Badges

Use tabBarBadge to render a custom badge element for a tab.

Static API

import { Text, View } from 'react-native';
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const HomeTabs = createMaterialTopTabNavigator({
  screens: {
    Inbox: {
      screen: InboxScreen,
      options: {
        tabBarBadge: () => (
          <View
            style={{
              minWidth: 18,
              height: 18,
              borderRadius: 9,
              backgroundColor: 'tomato',
              alignItems: 'center',
              justifyContent: 'center',
            }}
          >
            <Text style={{ color: 'white', fontSize: 12 }}>3</Text>
          </View>
        ),
      },
    },
    Settings: SettingsScreen,
  },
});

Dynamic API

import { Text, View } from 'react-native';
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const Tab = createMaterialTopTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen
        name="Inbox"
        component={InboxScreen}
        options={{
          tabBarBadge: () => (
            <View
              style={{
                minWidth: 18,
                height: 18,
                borderRadius: 9,
                backgroundColor: 'tomato',
                alignItems: 'center',
                justifyContent: 'center',
              }}
            >
              <Text style={{ color: 'white', fontSize: 12 }}>3</Text>
            </View>
          ),
        }}
      />
      <Tab.Screen name="Settings" component={SettingsScreen} />
    </Tab.Navigator>
  );
}

Indicators

Use tabBarIndicatorStyle to customize the indicator:

Use horizontal margin ({ marginHorizontal: 16 }) to make the indicator shorter than the tab button width.
Set width ({ width: 24 }) for a fixed-width indicator, with marginHorizontal: 'auto' to center it under the tab button.
Don't set borderRadius if tabBarItemStyle has 'auto' width as it's not supported.

If the default styling options aren't sufficient, use tabBarIndicator to render a custom indicator.

Static API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const HomeTabs = createMaterialTopTabNavigator({
  screenOptions: {
    tabBarIndicatorStyle: {
      backgroundColor: '#111827',
      height: 3,
      marginHorizontal: 16,
    },
  },
  screens: {
    Feed: FeedScreen,
    Updates: UpdatesScreen,
  },
});

Dynamic API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const Tab = createMaterialTopTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator
      screenOptions={{
        tabBarIndicatorStyle: {
          backgroundColor: '#111827',
          height: 3,
          marginHorizontal: 16,
        },
      }}
    >
      <Tab.Screen name="Feed" component={FeedScreen} />
      <Tab.Screen name="Updates" component={UpdatesScreen} />
    </Tab.Navigator>
  );
}

Custom Tab Bar

Use the tabBar option if a custom design is needed. Use the navigation prop passed to the tab bar instead of useNavigation.

import { Text, View } from 'react-native';
import { useLinkBuilder } from '@react-navigation/native';
import { PlatformPressable } from '@react-navigation/elements';

function MyTabBar({ state, descriptors, navigation }) {
  const { buildHref } = useLinkBuilder();

  return (
    <View style={{ flexDirection: 'row' }}>
      {state.routes.map((route, index) => {
        const { options } = descriptors[route.key];
        const label =
          options.tabBarLabel !== undefined
            ? options.tabBarLabel
            : options.title !== undefined
              ? options.title
              : route.name;

        const isFocused = state.index === index;

        return (
          <PlatformPressable
            key={route.key}
            href={buildHref(route.name, route.params)}
            onPress={() => {
              const event = navigation.emit({
                type: 'tabPress',
                target: route.key,
                canPreventDefault: true,
              });

              if (!isFocused && !event.defaultPrevented) {
                navigation.navigate(route.name, route.params);
              }
            }}
            onLongPress={() =>
              navigation.emit({
                type: 'tabLongPress',
                target: route.key,
              })
            }
            style={{ flex: 1, alignItems: 'center', paddingVertical: 12 }}
          >
            <Text style={{ opacity: isFocused ? 1 : 0.6 }}>{label}</Text>
          </PlatformPressable>
        );
      })}
    </View>
  );
}

Static API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const HomeTabs = createMaterialTopTabNavigator({
  tabBar: (props) => <MyTabBar {...props} />,
  screens: {
    Feed: FeedScreen,
    Updates: UpdatesScreen,
  },
});

Dynamic API

import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const Tab = createMaterialTopTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator tabBar={(props) => <MyTabBar {...props} />}>
      <Tab.Screen name="Feed" component={FeedScreen} />
      <Tab.Screen name="Updates" component={UpdatesScreen} />
    </Tab.Navigator>
  );
}

If the custom tab bar also needs proper web links, use useLinkBuilder when building each tab button.

Lazy Rendering

All screens are mounted immediately by default for smoother swiping. Enable lazy only when rendering tabs upfront is too expensive.

Static API

import { ActivityIndicator, View } from 'react-native';
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const HomeTabs = createMaterialTopTabNavigator({
  screenOptions: {
    lazy: true,
  },
  screens: {
    Feed: FeedScreen,
    Updates: UpdatesScreen,
    Mentions: MentionsScreen,
  },
});

Dynamic API

import { ActivityIndicator, View } from 'react-native';
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

const Tab = createMaterialTopTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator
      screenOptions={{
        lazy: true,
      }}
    >
      <Tab.Screen name="Feed" component={FeedScreen} />
      <Tab.Screen name="Updates" component={UpdatesScreen} />
      <Tab.Screen name="Mentions" component={MentionsScreen} />
    </Tab.Navigator>
  );
}

Customize lazy loading behavior with lazyPlaceholder to show a custom placeholder before the screen is loaded and lazyPreloadDistance to control how many screens away from the focused screen should be preloaded.

Canonical Docs

Material Top Tabs Navigator

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-09

AutoGineer is not affiliated with or endorsed by Callstack or 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