Public preview

Full-page apps Public preview

Full-page apps give you an entire page in the Stripe Dashboard. This provides room for tabbed navigation, overview dashboards, list-to-detail flows, and data visualisation. This guide describes key design patterns for building a full-page app view.

Before you begin

Before you build a full-page app, make sure your app meets these requirements:

Create an app or use an existing one.
Install @stripe/ui-extension-sdk version 9. 2. 1 or later.
Install the latest version of the Stripe Apps CLI plugin .
Add a stripe. dashboard. fullpage viewport to your app.
Review and download the example app on GitHub for detailed code examples.
Review the routing guide for full details on createRoutes , AppRouter , useAppRoute and useNavigation .

Apply best practices

Keep these principles in mind when you design a full-page app:

Organised : Structure your app into logical tabs that represent distinct areas of your workflow. Each tab serves a clear purpose so users always know where to find what they need.
Progressive : Lead with a high-level overview and let users discover details at their own pace. Don’t overwhelm users with all information at once.
Consistent : Follow the layout and navigation patterns used by native Stripe Dashboard pages.
Connected : Connect your full-page app to other parts of your Stripe Apps. If your app also uses a drawer view or settings page, provide clear pathways between them.

Set up your full-page view

Every full-page app wraps its content in the FullPageView component. This renders the Dashboard page header that displays your app’s identity and actions.

The page header pulls from your stripe-app.json:

App name : The name field.
App icon : The icon field.
Page action : An optional primary button. See the FullPageView component for the pageAction prop.
Settings : Appears automatically to let users navigate to app settings.

Your stripe-app.json must include a stripe.dashboard.fullpage viewport:

The component field maps to your view file in src/views/.

Structure your page with tabs

Use Tabs and Tab from @the relevant part of the product to organise content into sections. Full-page apps use routing to map URLs to views. This gives users bookmarkable URLs, browser back/forward navigation, and shareable links to specific tabs.

Start by defining your route config with a /:tabId? pattern so the selected tab persists in the URL:

export const routes = createRoutes({
 home: route('/:tabId?', () => (
 <FullPageView>
 <Home />
 </FullPageView>
 )),
 customer: route('/customers/:id', ({id}) => (
 <FullPageView>
 <CustomerDetail id={id} />
 </FullPageView>
 )),
});

See the routing guide for the full setup, including AppRouter, type-safe navigation with RouteRegister, path patterns, and redirectOnNotFound.

Then wire the selected tab to your route parameter:

This pattern connects tabs to routing in three steps:

Read the current tab from the route : useAppRoute() returns routeParams and key directly. Check key === 'home' first to narrow the type, then fall back to the related setting _ TAB when no tab is specified (the / root URL).
Control the selected tab : Pass the resolved tab ID to selectedKey so the Tabs component renders the correct panel.
Update the route on tab change : Pass navigateToAppRoute to onSelectionChange so selecting a tab updates the URL from / to /customers .

This means navigating directly to a URL like /customers renders the correct tab automatically, and the browser’s back and forward buttons move between tabs.

Build an overview tab

An overview tab gives users a high-level summary of activity across your app. Use the OverviewPage component to structure a two-column layout with summary metrics, charts, and sidebar modules.

Place the loading state inside the tab component so the tab bar remains visible and interactive while content loads.

Build a list view

Use the DataTable component to display structured data with sortable columns, status indicators and clickable rows. Use navigateToAppRoute to navigate to a detail view when a user clicks a row.

Include an emptyMessage prop to handle empty states. If your list supports filter controls, swap the emptyMessage based on whether filters are active.

Build a detail view

When a user selects an item from a list, the router renders the detail route. Use the DetailPage component to structure the detail view with breadcrumbs, a two-column layout and page-level actions.

Because the detail view is its own route, the tab bar isn’t visible. The breadcrumb provides the path back to the list. See the routing guide for more on createAppRoute and declarative navigation.

Build create and edit flows

When users create a new item or edit an existing one, use a FocusView drawer. The drawer overlays the current view without interrupting the user’s place in the app.

Use the Button component’s pending prop to indicate that a save operation is in progress.

Full-page apps