# Welcome screen

> A complete first-run welcome: an onboarding pager with parallax pages and a worm page dot, where each page's art plays as it settles (a weekly ring fills, a distance chart draws, a group of runners fans out), Get started and a Sign in link.

- Type: Component (screens)
- Access: Pro
- Page: https://goodui.dev/native/components/welcome-screen
- Markdown: https://goodui.dev/native/components/welcome-screen.md
- Registry item: https://goodui.dev/native/r/welcome-screen.json
- Dependencies: none
- Keywords: react native welcome screen, onboarding screen expo, intro slides, get started screen, walkthrough pager, first run experience

## When to use

- The first screen a new install sees, before sign-up: three or four pages of value, then Get started.
- When returning people need a clear way to sign in from the same screen.

## When not to use

- Pointing at controls inside the app after sign-in: use coach-mark.
- A single splash with one message: a plain screen with a button is enough.
- A pager inside another layout: use page-dots-onboarding directly.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add @goodui-native-pro/welcome-screen
npx expo install --fix
```

Pro: add `"@goodui-native-pro": { "url": "https://goodui.dev/native/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${GOODUI_LICENSE_KEY}" } }` to the `registries` of components.json and put your license key in .env.local.

The component lands in `components/goodui-native/welcome-screen/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs avatar, page-dots-onboarding, progress-ring, sparkline.

## Usage

```tsx
// app/welcome.tsx
import { router } from "expo-router";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { WelcomeScreen } from "@/components/goodui-native/welcome-screen/welcome-screen";

export default function WelcomeRoute() {
  return (
    <WelcomeScreen
      appName="Stride"
      onGetStarted={async () => {
        await AsyncStorage.setItem("seen-welcome", "1");
        router.replace("/sign-up");
      }}
      onSignIn={() => router.push("/sign-in")}
    />
  );
}
```

## Examples

### Your own pages

```tsx
import { Image } from "react-native";

<WelcomeScreen
  appName="Fernway"
  pages={[
    { key: "trips", title: "Plan trips together", description: "One itinerary everyone can edit.", illustration: <Image source={tripsArt} style={{ width: 220, height: 220 }} /> },
    { key: "split", title: "Split costs fairly", description: "Add a receipt and it is shared by who was there." },
    { key: "offline", title: "Works offline", description: "Maps and bookings stay on your phone." },
  ]}
  onGetStarted={finish}
  onSignIn={signIn}
/>
```

### Photos for the default runners

```tsx
<WelcomeScreen people={[{ name: "Maya Patel", source: mayaPhoto }, { name: "Leo Martins", source: leoPhoto }, { name: "Aiko Tanaka" }]} onGetStarted={finish} />
```

## API reference

### WelcomeScreen

`import { WelcomeScreen } from "@/components/goodui-native/welcome-screen/welcome-screen";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `appName` | `string` | `"Stride"` | Product name, shown at the top left and in the footer copy. |
| `pages` | `OnboardingPage[]` | – | Your own pages (two to six). Omit to get three running-app pages whose art plays as each page settles: a ring fills, a chart draws, a group of runners fans out. |
| `people` | `AvatarGroupPerson[]` | `RUNNERS` | People for the default third page's avatar group. Names alone give colored initials; add `source` for photos. |
| `onGetStarted` | `() => unknown` | – | The last page's Get started button. Return a promise (for example saving a "seen onboarding" flag) to show a spinner. |
| `onSignIn` | `() => void` | – | "Sign in" link under the pager, for people who already have an account. Hidden when omitted. |
| `onSkip` | `() => void` | – | Skip at the top. Defaults to jumping to the last page; pass `onGetStarted` to leave right away. |
| `labels` | `{ next?: string; done?: string; skip?: string }` | – | Localized pager labels. |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

## Accessibility

- The page dots are one adjustable element named 'Welcome to {appName}': swipe up or down on them with VoiceOver or TalkBack, or use the arrow keys on the web (from page-dots-onboarding). Page content, including its buttons, stays outside it.
- The default art is labelled: the ring as 'Weekly goal, 18 of 25 kilometers', the chart with its range; the avatar group reads its names.
- The app name at the top is plain text; Sign in is a link with a 44 pt touch target from hitSlop.

## Motion

- Pages follow the finger with parallax, the worm dot stretches between dots and Next grows into Get started (from page-dots-onboarding).
- Each default page's art plays when its page settles: the progress ring fills to 72 %, the sparkline morphs from flat into eight rising weeks, and the avatar stack fans out on the smooth spring. Leaving a page resets its art, so coming back plays it again.
- Reduced motion: the pager jumps between pages and the art changes in place without travel.

## Haptics

- select when a page settles and tap on Next, Get started and Skip (from page-dots-onboarding). The art plays no haptics.

## Performance

- All pages stay mounted; the art is SVG and views. Only the settled index re-renders the page list.

## Notes for AI

- Pass onGetStarted (may return a promise) and onSignIn; navigate inside them.
- pages replaces the default running-app pages entirely; each page needs key and title, optional description and illustration.
- people only feeds the default third page. Images come in through props; the component bundles none.
- Render it as the whole route with the header hidden; it handles safe areas itself.

## Related

- [Onboarding pager](https://goodui.dev/native/components/page-dots-onboarding.md): A full-screen onboarding pager: pages follow the finger 1:1 with parallax on their content, the page dot stretches toward the next page like a worm, and the Next button grows with the swipe into a full-width Get started on the last page.
- [Sign up screen](https://goodui.dev/native/components/sign-up-screen.md): A complete sign-up screen: name, email and a password with a live strength meter whose segments fill and recolor while each rule's check draws itself in, a terms checkbox and an async Create account button.
- [Sign in screen](https://goodui.dev/native/components/sign-in-screen.md): A complete sign-in screen: email and password, forgot password, an async Sign in button that gathers into a spinner and opens into a check, or shakes together with the password field when the credentials are rejected, and Continue with Apple or Google.
- [Progress ring](https://goodui.dev/native/components/progress-ring.md): A circular progress ring that fills on a spring, laps itself past 100 % with a gap that lifts the lap off the ring, and bounces once with a success haptic when it completes.
- [Sparkline](https://goodui.dev/native/components/sparkline.md): A small line or area chart that draws itself in and morphs to new data; press and drag to scrub, and a dot rides the curve while the line beyond your finger dims and every point ticks.
- [Avatar](https://goodui.dev/native/components/avatar.md): A photo that fades in over initials on a color picked from the name, with a presence dot and a story ring whose accent arc sweeps in when there is something new and away once seen; AvatarGroup stacks people with a +N counter and fans out on tap.

## Guidance for AI tools

Welcome screen: A complete first-run welcome: an onboarding pager with parallax pages and a worm page dot, where each page's art plays as it settles (a weekly ring fills, a distance chart draws, a group of runners fans out), Get started and a Sign in link. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt