# OnboardingView component for Stripe Apps

Use OnboardingView to implement an onboarding flow of your Stripe App

# v8

> This is a v8 for when app-sdk-version is 8. View the full page at https://docs.stripe.com/stripe-apps/components/onboardingview?app-sdk-version=8.

The `onboardingview` component isn’t available in the selected SDK version.


# v9

> This is a v9 for when app-sdk-version is 9. View the full page at https://docs.stripe.com/stripe-apps/components/onboardingview?app-sdk-version=9.

To add the `OnboardingView` component to your app:

```js
import {OnboardingView} from '@stripe/ui-extension-sdk/ui';
```

The `OnboardingView` component provides a standardized way to implement an onboarding view with a predefined structure:

- Left sidebar that renders a list of onboarding tasks
- Main content area that displays the content of a given onboarding step

The list of onboarding tasks is specified as an array of [TaskListItemProps](https://docs.stripe.com/stripe-apps/components/tasklist.md?app-sdk-version=9#tasklistitem-props) items. You can fully customize the content of the onboarding step itself by specifying a custom React view as a direct child of the `<OnboardingView>`. This approach lets you implement a custom onboarding step based on your business needs, while the Stripe Dashboard controls the way the list of onboarding tasks renders.

### OnboardingView props

| Property      | Type                                                                                                                                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`    | (Required)
  `React.ReactNode`

  React component that renders the content of the primary column.                                                                                                          |
| `completed`   | (Required)
  `boolean`

  Whether all onboarding tasks are done. When set to true, the onboarding modal window will automatically close after a brief delay to return the user to their previous location. |
| `tasks`       | (Required)
  `Array<Tasks>`

  A list of onboarding tasks.

  Related types: [Tasks](https://docs.stripe.com/stripe-apps/components/onboardingview.md#tasks).                                              |
| `title`       | (Required)
  `string`

  Onboarding step title.                                                                                                                                                            |
| `description` | (Optional)
  `string | undefined`

  Onboarding step description.                                                                                                                                          |
| `error`       | (Optional)
  `React.ReactNode`

  Information about an error that occurred during onboarding.                                                                                                              |
| `pending`     | (Optional)
  `boolean | undefined`

  Whether the onboarding flow is in a loading state. Shows spinner and loading message when true.                                                                      |

### Tasks

| Property   | Type                                                                                                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`    | (Required)
  `string`

  The display title of the task.                                                                                                                                              |
| `onPress`  | (Optional)
  `((event: PressEvent) => void) | undefined`

  An event handler for when the user clicks anywhere on the task.                                                                          |
| `status`   | (Optional)
  `("not-started" | "in-progress" | "blocked" | "complete") | undefined`

  The current status of the task.                                                                               |
| `subTasks` | (Optional)
  `Array<SubTasks> | undefined`

  A list of sub-tasks that belong to this task.

  Related types: [SubTasks](https://docs.stripe.com/stripe-apps/components/onboardingview.md#subtasks). |

### SubTasks

| Property  | Type                                                                                                                        |
| --------- | --------------------------------------------------------------------------------------------------------------------------- |
| `title`   | (Required)
  `string`

  The display title of the task.                                                                     |
| `onPress` | (Optional)
  `((event: PressEvent) => void) | undefined`

  An event handler for when the user clicks anywhere on the task. |
| `status`  | (Optional)
  `("not-started" | "in-progress" | "blocked" | "complete") | undefined`

  The current status of the task.      |

## Basic

The following example demonstrates the basic usage of the `OnboardingView` component, where a different React view is rendered for each onboarding step.

## Transitional

This example demonstrates how to use the `error` and `pending` props to handle different states during the onboarding flow.

The component manages three distinct states:

- **Pending**: Shows a loading spinner while fetching onboarding data
- **Error**: Displays a **Try again** button if the fetch fails
- **Ready**: Renders the normal onboarding experience with tasks and forms

When the example component first loads, it simulates a failed fetch to demonstrate the error state. When you click **Try again**, the fetch succeeds and displays the actual onboarding content. This approach allows you to handle loading and error scenarios smoothly without requiring additional components or complex state management.


## See also

- [Design patterns to follow](https://docs.stripe.com/stripe-apps/patterns.md)
- [Style your app](https://docs.stripe.com/stripe-apps/style.md)
- [UI testing](https://docs.stripe.com/stripe-apps/ui-testing.md)