Choosing a Navigator Type
The navigator type defines the top-level structure of your application's navigation chrome — the persistent menu or shell that wraps every page. Getting this choice right early in your build is important because it shapes the visual hierarchy users see and the mental model they form about how the app is organized. Changing it later is possible but requires reconfiguring navigation items and potentially reshaping your page hierarchy.
The four navigator types are Tab Navigator, Drawer Navigator, Stack Navigator, and Top-Level Navigator. Each is described in detail below, followed by a comparison table.
Note: Navigator type is configured in App Settings → Development → Navigation → Appearance. Each breakpoint can be configured independently — your app might use a Tab Navigator on mobile and a Drawer Navigator on desktop. See Responsive Navigation for details.
Tab Navigator
The Tab Navigator displays a fixed row of tabs — at the bottom of the screen on mobile (bottom tab bar) or along the top of the content area on web. Tapping a tab switches to that tab's root page. The active tab is visually highlighted.
How it works: Each tab is an independent root page (or a Stack Navigator root — see Nesting below). Switching between tabs swaps the visible content while preserving the scroll position and state of the inactive tabs. This is the behaviour users expect from tab-based apps: going back to a tab returns you to where you left off in that tab.
Capacity and limits:
Best suited to 3–5 primary destinations. More than 5 tabs creates a crowded, hard-to-tap bottom bar on small screens.
On mobile, the 5-item cap is enforced — items beyond 5 are not shown in the bottom bar.
Tabs should represent distinct areas of the app, not steps in a flow. If two destinations are part of the same workflow, they belong in a Stack inside a single tab.
Web behaviour: On web at larger breakpoints, tabs render as a top tab strip (horizontal tabs across the top of the main content area). The same capacity recommendations apply — use 3–5 tabs on web to avoid visual crowding, especially when tab labels are long.
Drawer Navigator
The Drawer Navigator renders a slide-out side menu — typically triggered by a hamburger icon in the header. The drawer can contain a hierarchical list of links, grouped by category, with icons and badges.
How it works: The drawer slides in from the left (or right, configurable) on mobile. On desktop, it can be configured to be persistent (always visible as a sidebar) or collapsible (icon-only mode). When an item is tapped, the drawer closes and navigates to the selected page.
Capacity and limits:
Best suited to apps with many destinations — 6 or more primary pages — where a tab bar would be too crowded.
Supports hierarchical grouping via Nav Groups — collapsible sections that contain related links. This is ideal for role-based menus where different user roles see different sections.
Supports a footer slot for secondary items (profile, settings, notifications) separate from the primary link list.
When to prefer Drawer over Tab: If your app has more than 5 primary destinations, has role-based navigation where different users see different items, or if the navigation menu needs to show labels prominently (tabs with labels are space-constrained), use a Drawer Navigator.
Stack Navigator
The Stack Navigator implements a push/pop navigation model — the same model used by native iOS and Android apps for detail flows. Navigating forward pushes a new page onto the stack; the back button (or swipe gesture on mobile) pops the top page off.
How it works: The Stack Navigator itself does not render a persistent menu — instead, it renders a header bar with the page title and a back button when the stack depth is greater than 1. The visual affordance is entirely per-page rather than a persistent chrome element.
Capacity and limits:
Best suited to detail flows and linear wizards — order details, ticket threads, multi-step forms, settings drill-downs.
Not appropriate as the sole top-level navigator for an app with many parallel destinations — users cannot jump between unrelated sections without backing out of the current stack first.
Works best nested inside a Tab or Drawer Navigator — each tab or drawer item contains its own Stack, enabling both parallel top-level navigation and deep per-section stacks.
Top-Level Navigator
The Top-Level Navigator is a combination pattern — a tab bar or drawer at the top level, with a Stack Navigator nested inside each tab or drawer item. This is the most common pattern for production mobile apps and complex web applications because it provides both the parallel navigation of a Tab/Drawer and the deep hierarchical navigation of a Stack.
How it works: The top-level shell renders the tab bar or drawer as persistent chrome. Each tab's content area is its own independent Stack Navigator. Navigating to a detail page within a tab pushes onto that tab's stack. The back button pops the detail off, returning to the tab's root page. The tab bar remains visible throughout.
When to use: Any app that has both primary destinations (tabs/drawer items) and detail flows within those destinations. This covers the vast majority of internal tools, customer-facing apps, and operational dashboards. If in doubt, start with a Top-Level Navigator — it gives you the most structural flexibility.
Comparison Table
| Feature | Tab Navigator | Drawer Navigator | Stack Navigator | Top-Level Navigator |
| Persistent chrome | Tab bar (bottom/top) | Drawer (slide-in or sidebar) | Header bar only | Tab bar or Drawer + nested header |
| Best for | 3–5 parallel destinations | Many destinations, role-based menus | Detail flows, linear wizards | Most production apps — any combination |
| Back button behavior | Not applicable (tabs switch, not stack) | Not applicable (drawer opens/closes) | Pops top page off stack | Pops within the active tab's stack |
| State between switches | Preserved per tab | Preserved per section | Single screen shown | Preserved per tab, with stack per tab |
| Supports deep hierarchy | Only if nested with Stack | Only if nested with Stack | Yes — unlimited depth | Yes — each tab has its own stack |
| Mobile native feel | Very natural (bottom tab bar) | Natural (hamburger drawer) | Very natural (push/pop) | Best overall native feel |
| Desktop suitability | Good (top tabs) | Excellent (persistent sidebar) | Limited as top-level | Excellent (sidebar + page stack) |
Common Properties
All four navigator types share the following base properties, configurable in App Settings → Navigation → Appearance.
| Property | Type | Description |
initialRoute | string | The page slug (or route name) to show when the navigator first loads. For Tab and Drawer, this is the initially selected tab/item. For Stack, it is the root page of the stack. |
headerVisible | boolean | Whether the navigator renders a header bar above the page content. When false, no header is shown — useful for pages with a custom-built header component or no header at all. |
headerTitle | string or expression | The title displayed in the header bar. Can be a static string or a dynamic expression (e.g. {{page.name}} or {{currentRecord.title}}). |
animationType | enum | The default animation for this navigator's transitions. Overrides the app-wide transition default for navigations within this navigator. Options correspond to the transition types documented in Page Transitions. |
Switching Navigator Type
To change your app's navigator type after initial setup:
Open App Settings → Navigation: Go to Settings → Development → Navigation, then click the Appearance tab.
Select the breakpoint to change: Click the breakpoint button (XL, LG, MD, SM) you want to update. You can keep the existing type for some breakpoints and change only the ones that need updating.
Choose the new navigator type: From the Style dropdown, select the new type. The preview in the builder canvas updates immediately.
Reconfigure navigation items if needed: Some item types are not compatible with all navigator types (e.g. Nav Groups are not supported in the bottom tab bar). The platform will warn you if existing items are incompatible — remove or replace them.
Nesting Navigators
Navigators can be nested to create complex navigation hierarchies. The most common pattern is a Tab Navigator or Drawer Navigator at the top level, with a Stack Navigator inside each tab/item. This is what the Top-Level Navigator type encapsulates — but you can also configure it explicitly for fine-grained control.
📄 Example — Nested navigation hierarchy
Top-Level: Tab Navigator ├── Tab 1: Orders │ └── Stack Navigator │ ├── Order List (root) │ └── Order Detail (pushed on tap) ├── Tab 2: Customers │ └── Stack Navigator │ ├── Customer List (root) │ └── Customer Profile (pushed on tap) └── Tab 3: Settings └── Stack Navigator ├── Settings Home (root) └── Profile Settings (pushed on tap)
Each tab maintains its own navigation stack independently. The user can be on Order Detail in Tab 1 while Tab 2 is still on Customer List root — switching tabs preserves both states.
Frequently Asked Questions
Can I use different navigator types on mobile vs desktop?
Yes — this is one of the most powerful features of the navigation system. The Appearance tab lets you set a different navigator type per breakpoint. A common pattern is Tab Navigator on mobile (SM) for thumb-friendly bottom tabs, and Drawer Navigator on desktop (LG/XL) for a persistent sidebar with full labels. The page content, navigation items, and URLs are all identical — only the navigation chrome changes. See Responsive Navigation for a full guide.
My app has 8 destinations — should I use a Drawer or group some into one tab?
With 8 destinations, a Drawer Navigator is generally the better fit. Forcing 8 items into a tab bar requires either truncating to 5 with a "More" overflow (which buries important destinations) or accepting a very cramped bottom bar. The Drawer can show all 8 comfortably, supports grouping related items under section headers, and can hide role-restricted items cleanly. If some destinations are accessed together often, you might group them under a Tab with nested Stack navigation, then use the remaining tabs for the most important standalone destinations — but this requires careful information architecture planning.
When is it appropriate to use Stack Navigator as the sole top-level navigator?
Stack Navigator as the sole top-level navigator is appropriate for linear, single-flow apps — for example, a checkout wizard, an on-boarding sequence, or a stand-alone questionnaire. Users follow a fixed path forward and backward with no need to jump between parallel destinations. For anything that resembles a multi-section application, embed a Stack inside a Tab or Drawer instead. A pure Stack at the top level with many diverging branches creates disorienting navigation — users can get "lost in the stack" with no persistent orientation point.