Screen · Navigation

App Shell

The root of a tabbed app: a floating tab bar, a stack per tab and real reselect behaviour.

An app shell on the lens tab bar in a bottom safe-area inset, generic per-tab content, hide-on-scroll through ShellScrollView, and reselect that pops to root and scrolls to top.

SwiftUIiOS 17.0+tab-shell

Get Swift Pieces Pro

$199 once, every piece included. See how installing works · Sign in

What's included

SwiftUI source you own, built on Apple frameworks only.

One NavigationStack per tab on the Lens Tab Bar
The bar hides on scroll through ShellScrollView
Reselecting a tab pops to root and scrolls to top
Cadence's four tabs as a working example

Includes

Lessons. Installed together, automatically.

In the Build Kit

Swift Pieces Skill (setup), Native (style), Onboarding to Paywall (recipe). Your agent builds around this screen in the same design.

Used in

Subscription App (template), Finance App (template), AI Assistant (template), Productivity App (template), Meditation App (template), Travel App (template)

Implementation notes

How it behaves, what it handles, and the decisions behind it.

One NavigationStack per tab, the system tab bar hidden, and LensTabBar placed in .safeAreaInset(edge: .bottom) so scrolling content is never covered. Wrap each tab's scrolling content in ShellScrollView: it reports its offset to the shell, which hides the bar on a downward scroll and shows it again on an upward one or near the top. Reselecting a tab pops its stack to root and scrolls the root to the top.

Notes

Tab content avoids the keyboard, so a composer rides above it, and the bar steps aside while the keyboard is up.
Tab content is generic, built by a (LensTab) -> Content closure, with no AnyView.
ShellScrollView uses ScrollPosition and onScrollGeometryChange on iOS 18, and ScrollViewReader with a geometry probe on iOS 17. Scroll offsets travel up through a preference and the scroll-to-top token travels down through the environment, so the scroll container can live anywhere in the tab, including pushed screens.
Only the selected tab drives the bar. A List does not report offsets; use ShellScrollView with a LazyVStack for rows.
Built on LensTabBar from the Lessons screen; the CLI installs it with this screen.
TabShellScreenExample at the end of TabShellScreen.swift is the screen shown in the preview; copy it as a starting point.

Theming

Reads SPTheme tokens from @Environment(\.spTheme) and requires the design-system item.
The shell passes color.accent to LensTabBar as its tint, spaces the bar with space.sm, and scrolls to top with motion.smooth.
Your tab content is not restyled. Read the same @Environment(\.spTheme) in your screens so they match the bar.
LensTabBar stays self-contained: its unselected icons, material fallback and springs use system values.

Keep building

Pieces that work well next to this one.

Screen · Education

Lessons

A language-learning home with a streak, today's goals as color blocks and a floating tab bar whose lens follows your finger.

Screen · Account

Settings

A settings home with a collapsing profile header, grouped rows, toggles and sign out.

Screen · Media

Reader

A long-read article with a serif headline and a floating pill that morphs into a reading toolbar.

Notes

Tab content avoids the keyboard, so a composer rides above it, and the bar steps aside while the keyboard is up.

Tab content is generic, built by a (LensTab) -> Content closure, with no AnyView.

ShellScrollView uses ScrollPosition and onScrollGeometryChange on iOS 18, and ScrollViewReader with a geometry probe on iOS 17. Scroll offsets travel up through a preference and the scroll-to-top token travels down through the environment, so the scroll container can live anywhere in the tab, including pushed screens.

Only the selected tab drives the bar. A List does not report offsets; use ShellScrollView with a LazyVStack for rows.

Built on LensTabBar from the Lessons screen; the CLI installs it with this screen.

TabShellScreenExample at the end of TabShellScreen.swift is the screen shown in the preview; copy it as a starting point.

Theming

Reads SPTheme tokens from @Environment(\.spTheme) and requires the design-system item.

The shell passes color.accent to LensTabBar as its tint, spaces the bar with space.sm, and scrolls to top with motion.smooth.

Your tab content is not restyled. Read the same @Environment(\.spTheme) in your screens so they match the bar.

LensTabBar stays self-contained: its unselected icons, material fallback and springs use system values.