# React Native Empty State

> A React Native empty state for iOS, Android and the web: an icon, a heading, what to do next and an action, for empty lists, no search results and first runs.

# EmptyState

What a screen shows when there's nothing in it yet: an icon, a heading, what to do next, and a button to do it.

```tsx
import { EmptyState } from 'patine-ui';
```

```tsx live
import { Button, EmptyState } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <EmptyState
      icon={<Icon name="search" size={28} />}
      title="No results for “sneakers”"
      description="Try another word, or clear the filters."
      action={<Button variant="outline">Clear filters</Button>}
    />
  );
}
```

## Example: an inbox with nothing left

A support inbox: when every conversation is handled, the list gives way to an empty state that says so and offers the next useful thing. Archive the last two to see it.

```tsx live
import { useState } from 'react';
import { Button, EmptyState, List, ListItem, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const OPEN = [
  { id: 1, from: 'Lena Novak', subject: 'Refund for order #20417' },
  { id: 2, from: 'Omar Haddad', subject: 'Login link expired' },
];

export default function Example() {
  const [open, setOpen] = useState(OPEN);
  return (
    <VStack style={{ width: '100%', maxWidth: 440, minHeight: 260 }}>
      {open.length ? (
        <List title="Assigned to you">
          {open.map((c) => (
            <ListItem
              key={c.id}
              title={c.subject}
              description={c.from}
              trailing={
                <Button size="sm" variant="outline" onPress={() => setOpen((all) => all.filter((x) => x.id !== c.id))}>
                  Archive
                </Button>
              }
            />
          ))}
        </List>
      ) : (
        <EmptyState
          icon={<Icon name="checkCheck" size={28} color="success" />}
          title="You’re all caught up"
          description="New conversations assigned to you show up here. The unassigned queue has 7 waiting."
          action={<Button variant="outline" onPress={() => setOpen(OPEN)}>Open the queue</Button>}
        />
      )}
    </VStack>
  );
}
```

## First run

Two actions: the main one first, and a quieter one for people who want to look around.

```tsx live
import { Button, EmptyState } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <EmptyState
      icon={<Icon name="folderPlus" size={28} />}
      title="Create your first project"
      description="Projects keep your files, tasks and people in one place."
      action={
        <>
          <Button>New project</Button>
          <Button variant="ghost">Import from Trello</Button>
        </>
      }
    />
  );
}
```

## Errors

An empty state also covers a screen that failed to load: say what happened and offer a retry.

```tsx live
import { useState } from 'react';
import { Button, EmptyState } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [retrying, setRetrying] = useState(false);
  return (
    <EmptyState
      icon={<Icon name="wifiOff" size={28} />}
      title="You're offline"
      description="Check your connection. Your drafts are saved on this device."
      action={
        <Button
          loading={retrying}
          onPress={() => {
            setRetrying(true);
            setTimeout(() => setRetrying(false), 1200);
          }}
        >
          Try again
        </Button>
      }
    />
  );
}
```

## Inside a card or a list

It fills whatever it's in, so it works in a card or a tab as well as a whole screen.

```tsx live
import { Button, Card, CardDescription, CardHeader, CardTitle, EmptyState } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <Card style={{ maxWidth: 420, width: '100%' }}>
      <CardHeader>
        <CardTitle>Team members</CardTitle>
        <CardDescription>People who can edit this workspace.</CardDescription>
      </CardHeader>
      <EmptyState
        icon={<Icon name="users" size={28} />}
        title="Just you so far"
        description="Invite people by email. They'll get access once they accept."
        action={<Button variant="outline">Invite people</Button>}
      />
    </Card>
  );
}
```

## Custom icon and content

`icon` takes any node, such as an illustration; an emoji string is drawn large in a tinted circle. `children` sit between the text and the action.

```tsx live
import { View } from 'react-native';
import { Badge, Button, EmptyState, HStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <EmptyState
      icon={
        <View style={{ width: 72, height: 72, borderRadius: 20, backgroundColor: '#EEF2FF', alignItems: 'center', justifyContent: 'center' }}>
          <Icon name="cart" size={36} color="primary" />
        </View>
      }
      title="Your cart is empty"
      description="Popular right now:"
      action={<Button>Start shopping</Button>}
    >
      <HStack gap="xs" wrap justify="center">
        {['Linen shirts', 'Sneakers', 'Gift cards'].map((tag) => (
          <Badge key={tag} variant="outline">{tag}</Badge>
        ))}
      </HStack>
    </EmptyState>
  );
}
```

## Accessibility

The title is a level 3 heading. The icon is hidden from screen readers, so the title and description must say everything.

## Props

EmptyState also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Required. |
| `description` | `string` | — | What to do about it. |
| `icon` | `ReactNode` | — | An emoji (drawn large in a circle) or any node. |
| `action` | `ReactNode` | — | One or two Buttons. |
| `children` | `ReactNode` | — | Anything else, between the text and the action. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `Design` | from `PatineProvider` | The look to follow. |
