# React Native Progress Bar & Spinner

> An accessible React Native progress bar and spinner for iOS, Android and the web: determinate or indeterminate, a thin iOS and Material track or an 8px web bar, and reduce motion respected.

# Progress & Spinner

`Progress` shows how far a task has got. Leave `value` out while the amount is unknown and a segment sweeps across instead (it holds still when the OS asks to reduce motion). `Spinner` is the platform's own activity indicator in a theme color.

```tsx
import { Progress, Spinner } from 'patine-ui';
```

```tsx live
import { useEffect, useState } from 'react';
import { Button, Card, CardContent, HStack, Progress, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [value, setValue] = useState(0);
  const [running, setRunning] = useState(true);
  useEffect(() => {
    if (!running || value >= 100) return;
    const id = setTimeout(() => setValue((v) => Math.min(100, v + 7)), 250);
    return () => clearTimeout(id);
  }, [running, value]);
  const done = value >= 100;
  return (
    <Card style={{ maxWidth: 380, width: '100%' }}>
      <CardContent style={{ paddingTop: 16, gap: 12 }}>
        <HStack gap="md" align="center">
          <Icon name="film" size={28} color="primary" />
          <VStack style={{ flex: 1 }}>
            <Text weight="medium">product-demo.mp4</Text>
            <Text size="sm" color="textSecondary">
              {done ? '48 MB · Uploaded' : `${Math.round((value / 100) * 48)} of 48 MB · ${running ? 'Uploading' : 'Paused'}`}
            </Text>
          </VStack>
          <Text weight="medium">{value}%</Text>
        </HStack>
        <Progress value={value} accessibilityLabel="Uploading product-demo.mp4" />
        <HStack gap="sm">
          {done ? (
            <Button size="sm" variant="outline" onPress={() => { setValue(0); setRunning(true); }}>Upload another</Button>
          ) : (
            <Button size="sm" variant="outline" onPress={() => setRunning((r) => !r)}>{running ? 'Pause' : 'Resume'}</Button>
          )}
        </HStack>
      </CardContent>
    </Card>
  );
}
```

## Example: a storage meter

`indicatorStyle` and `height` restyle the bar: here its color warns as the quota fills.

```tsx live
import { HStack, Progress, Text, VStack } from 'patine-ui';

const QUOTAS = [
  { label: 'Photos', used: 3.1, total: 15 },
  { label: 'Email', used: 9.8, total: 15 },
  { label: 'Drive', used: 14.2, total: 15 },
];

const color = (ratio: number) => (ratio > 0.9 ? '#DC2626' : ratio > 0.6 ? '#F59E0B' : '#10B981');

export default function Example() {
  return (
    <VStack gap="lg" style={{ maxWidth: 380, width: '100%' }}>
      {QUOTAS.map(({ label, used, total }) => (
        <VStack key={label} gap="xs">
          <HStack justify="space-between">
            <Text weight="medium">{label}</Text>
            <Text size="sm" color="textSecondary">{used} of {total} GB</Text>
          </HStack>
          <Progress value={used} max={total} height={10} indicatorStyle={{ backgroundColor: color(used / total) }} accessibilityLabel={`${label} storage`} />
        </VStack>
      ))}
    </VStack>
  );
}
```

## Determinate and indeterminate

Pass a `value` from 0 to `max` when you know how far along it is. Leave it out (or pass `null`) while you don't, such as while connecting, and a segment sweeps across.

```tsx live
import { Progress, Text, VStack } from 'patine-ui';

export default function Example() {
  return (
    <VStack gap="md" style={{ maxWidth: 360, width: '100%' }}>
      <Text size="sm" color="textSecondary">Connecting to the server…</Text>
      <Progress accessibilityLabel="Connecting" />
      <Text size="sm" color="textSecondary">Step 3 of 5</Text>
      <Progress value={3} max={5} accessibilityLabel="Onboarding, step 3 of 5" />
    </VStack>
  );
}
```

## Spinner

`Spinner` is the platform's activity indicator. `size` is `'small'`, `'large'` or a number, and `color` a theme color. Inside a button, use the button's own `loading` instead.

```tsx live
import { HStack, Spinner, Text } from 'patine-ui';

export default function Example() {
  return (
    <HStack gap="xl" align="center">
      <Spinner />
      <Spinner size="large" />
      <Spinner color="success" accessibilityLabel="Verifying" />
      <Spinner color="danger" />
      <HStack gap="sm" align="center">
        <Spinner color="textSecondary" accessibilityLabel="Loading messages" />
        <Text color="textSecondary">Loading messages…</Text>
      </HStack>
    </HStack>
  );
}
```

## Designs

iOS and Material draw a thin 4pt track, as their system progress views do; brand and web a rounder 8pt one.

```tsx live
import { Progress, Text, VStack } from 'patine-ui';

const DESIGNS = { brand: 'Brand', ios: 'iOS', material: 'Material', web: 'Web' } as const;

export default function Example() {
  return (
    <VStack gap="sm" style={{ maxWidth: 360, width: '100%' }}>
      {Object.entries(DESIGNS).map(([design, label]) => (
        <VStack key={design} gap="xs">
          <Text size="xs" color="textSecondary">{label}</Text>
          <Progress design={design as keyof typeof DESIGNS} value={65} accessibilityLabel={label} />
        </VStack>
      ))}
    </VStack>
  );
}
```

## Accessibility

Both have the `progressbar` role. Progress reports its percentage (`aria-valuenow`) and is `aria-busy` while indeterminate; name it with `accessibilityLabel`. Spinner is named "Loading" unless you pass your own `accessibilityLabel`.

## Props

### Progress

Progress also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | — | From 0 to `max`. Leave it out while unknown. |
| `max` | `number` | `100` | |
| `height` | `number` | 4 (iOS, Material), 8 (brand, web) | The track's height. |
| `indicatorStyle` | `StyleProp<ViewStyle>` | — | The filled part. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `Design` | from `PatineProvider` | The look to follow. |

### Spinner

Spinner also takes `ActivityIndicator` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `keyof Theme['colors']` | `'primary'` | A theme color. |
| `size` | `'small' \| 'large' \| number` | `'small'` | |
| `accessibilityLabel` | `string` | `'Loading'` | |
