Expo Router UI

GitHub

npm

An Expo Router submodule that provides headless tab components to create custom tab layouts.

Android

iOS

tvOS

Web

Bundled version:

~5.0.2-preview.3

expo-router/ui is a submodule of expo-router library and exports components and hooks to build custom tab layouts, rather than using the default React Navigation navigators provided by expo-router.

See the Expo Router reference for more information about the file-based routing library for native and web app.

Installation

To use expo-router/ui in your project, you need to install expo-router in your project. Follow the instructions from the Install Expo Router guide.

Configuration in app config

If you are using the default template to create a new project, expo-router config plugin is automatically configured in the app config automatically.

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": ["expo-router"]
  }
}

Usage

Find more information about using expo-router/ui in Expo Router UI guide.

API

import { Tabs, TabList, TabTrigger, TabSlot } from 'expo-router/ui';

Components

`TabContext`

Type: React.Element<ProviderProps<ExpoTabsNavigatorScreenOptions>>

`TabList`

Type: React.Element<TabListProps>

Wrapper component for TabTriggers. TabTriggers within the TabList define the tabs.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabListProps

`asChild`

Optional • Type: boolean

Forward props to child component and removes the extra <View>. Useful for custom wrappers.

Inherited Props

ViewProps

`Tabs`

Type: React.Element<TabsProps>

Root component for the headless tabs.

See: useTabsWithChildren for a hook version of this component.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabsProps

`asChild`

Optional • Type: boolean

Forward props to child component and removes the extra <View>. Useful for custom wrappers.

`options`

Optional • Type: UseTabsOptions

Inherited Props

ViewProps

`TabSlot`

Type: React.Element<TabSlotProps>

Renders the current tab.

See: useTabSlot for a hook version of this component.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabSlotProps

`detachInactiveScreens`

Optional • Type: boolean

Remove inactive screens.

`renderFn`

Optional • Type: defaultTabsSlotRender

Override how the Screen component is rendered.

Inherited Props

ComponentProps<ScreenContainer>

`TabTrigger`

Type: React.Element<TabTriggerProps>

Creates a trigger to navigate to a tab. When used as child of TabList, its functionality slightly changes since the href prop is required, and the trigger also defines what routes are present in the Tabs.

When used outside of TabList, this component no longer requires an href.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabTriggerProps

`asChild`

Optional • Type: boolean

Forward props to child component. Useful for custom wrappers.

`href`

Optional • Type: Href

Name of tab. Required when used within a TabList.

`name`

Type: string

Name of tab. When used within a TabList this sets the name of the tab. Otherwise, this references the name.

`reset`

Optional • Literal type:

Resets the route when switching to a tab.

Acceptable values are: SwitchToOptions[reset] | 'onLongPress'

Inherited Props

PressablePropsWithoutFunctionChildren

`useTabSlot`

Type: React.Element<TabSlotProps>

Returns a ReactElement of the current tab.

Example

function MyTabSlot() {
  const slot = useTabSlot();

  return slot;
}

Hooks

`useTabSlot(namedParameters)`

Parameter	Type
namedParameters(optional)	`TabSlotProps`

Returns a ReactElement of the current tab.

Returns:

Element

Example

function MyTabSlot() {
  const slot = useTabSlot();

  return slot;
}

`useTabsWithChildren(options)`

Parameter	Type
options	`UseTabsWithChildrenOptions`

Hook version of Tabs. The returned NavigationContent component should be rendered. Using the hook requires using the <TabList /> and <TabTrigger /> components exported from Expo Router.

The useTabsWithTriggers() hook can be used for custom components.

See: Tabs for the component version of this hook.

Example

export function MyTabs({ children }) {
 const { NavigationContent } = useTabsWithChildren({ children })

 return <NavigationContent />
}

`useTabsWithTriggers(options)`

Parameter	Type
options	`UseTabsWithTriggersOptions`

Alternative hook version of Tabs that uses explicit triggers instead of children.

Returns:

TabsContextValue

See: Tabs for the component version of this hook.

Example

export function MyTabs({ children }) {
  const { NavigationContent } = useTabsWithChildren({ triggers: [] })

  return <NavigationContent />
}

`useTabTrigger(options)`

Parameter	Type
options	`TabTriggerProps`

Utility hook creating custom TabTrigger.

Returns:

UseTabTriggerResult

Types

`ExpoTabsNavigationProp`

Type: NavigationProp<ParamList, RouteName, NavigatorID, TabNavigationState<ParamListBase>, ExpoTabsScreenOptions, TabNavigationEventMap>

`ExpoTabsNavigatorOptions`

Literal Type: multiple types

Acceptable values are: DefaultNavigatorOptions<ParamListBase, string | undefined, TabNavigationState<ParamListBase>, ExpoTabsScreenOptions, TabNavigationEventMap, ExpoTabsNavigationProp<ParamListBase>> | Omit<TabRouterOptions, 'initialRouteName'> | ExpoTabsNavigatorScreenOptions

`ExpoTabsNavigatorScreenOptions`

Property	Type	Description
detachInactiveScreens(optional)	`boolean`	-
freezeOnBlur(optional)	`boolean`	-
lazy(optional)	`boolean`	-
unmountOnBlur(optional)	`boolean`	-

`ExpoTabsResetValue`

Literal Type: string

Acceptable values are: 'always' | 'onFocus' | 'never'

`ExpoTabsScreenOptions`

Type: Pick<BottomTabNavigationOptions, 'title' | 'lazy' | 'freezeOnBlur'> extended by:

Property	Type	Description
action	`NavigationAction`	-
params(optional)	`object`	-
title	`string`	-

`SwitchToOptions`

Options for switchTab function.

Property	Type	Description
reset(optional)	`ExpoTabsResetValue`	Navigate and reset the history.

`TabNavigationEventMap`

Property	Type	Description
tabLongPress	`{ data: undefined }`	Event which fires on long press on the tab in the tab bar.
tabPress	`{ canPreventDefault: true, data: undefined }`	Event which fires on tapping on the tab in the tab bar.

`TabsContextValue`

Type: ReturnType<useNavigationBuilder>

The React Navigation custom navigator.

See: useNavigationBuilder hook from React Navigation for more information.

`TabsSlotRenderOptions`

Options provided to the UseTabSlotOptions.

Property	Type	Description
detachInactiveScreens	`boolean`	Should the screen be unloaded when inactive.
index	`number`	Index of screen.
isFocused	`boolean`	Whether the screen is focused.
loaded	`boolean`	Whether the screen has been loaded.

`TabTriggerOptions`

Property	Type	Description
href	`Href`	-
name	`string`	-

`Trigger`

Type: extended by:

Property	Type	Description
isFocused	`boolean`	-
resolvedHref	`string`	-
route	`[number]`	-

`UseTabsOptions`

Options to provide to the Tab Router.

Type: Omit<DefaultNavigatorOptions<ParamListBase, any, TabNavigationState<any>, ExpoTabsScreenOptions, TabNavigationEventMap, any>, 'children'> extended by:

Property	Type	Description
backBehavior(optional)	`TabRouterOptions[backBehavior]`	-

`UseTabsWithChildrenOptions`

Type: PropsWithChildren<UseTabsOptions>

`UseTabsWithTriggersOptions`

Type: UseTabsOptions extended by:

Property	Type	Description
triggers	`ScreenTrigger[]`	-

`UseTabTriggerResult`

Property	Type	Description
getTrigger	`(name: string) => Trigger \| undefined`	-
switchTab	`(name: string, options: SwitchToOptions) => void`	-
trigger(optional)	`Trigger`	-
triggerProps	`TriggerProps`	-