# React Native Motion Effects (Pro)

> React Native motion effects for iOS, Android and the web, in the spirit of Magic UI: rolling numbers with locale and currency, confetti bursts and cannons, shimmering text, a shine border, an infinite marquee, typing text, text reveal, blur fade and stagger, a pulsing beacon and an animated counter badge. Native driver, reduce motion respected, no dependencies. Part of Patine Pro.

# Motion effects Pro

The small moments that make an app feel made with care: a revenue figure that rolls into place, confetti on a first sale, a "Thinking…" that shimmers, a plan card with light running round its border, customer logos that scroll by. Each one runs on the native driver where React Native has it, needs no dependency beyond `react-native-svg`, and holds still when the OS asks to reduce motion.

```tsx
import { RollingNumber, Confetti, ShimmerText, ShineBorder, Marquee, TypingText, TextReveal, BlurFade, Stagger, Beacon, CounterBadge } from '@patine-ui/pro';
```

```tsx live
import { useRef, useState } from 'react';
import { View } from 'react-native';
import { Button, Text } from 'patine-ui';
import { Confetti, RollingNumber } from '@patine-ui/pro';

export default function Example() {
  const confetti = useRef(null);
  const [revenue, setRevenue] = useState(48250.4);
  return (
    <View style={{ gap: 12, minHeight: 200 }}>
      <Text size="sm" color="textSecondary">Revenue this month</Text>
      <RollingNumber value={revenue} currency="USD" size="3xl" />
      <Button
        style={{ alignSelf: 'flex-start' }}
        onPress={() => {
          setRevenue((r) => r + 1999);
          confetti.current?.fire();
        }}
      >
        Close a $1,999 deal
      </Button>
      <Confetti ref={confetti} />
    </View>
  );
}
```

## Example: an order placed

A checkout's last step: the button shimmers while the payment goes through, then confetti, and the points balance rolls up to its new total.

```tsx live
import { useRef, useState } from 'react';
import { View } from 'react-native';
import { Button, Text } from 'patine-ui';
import { Confetti, RollingNumber, ShimmerText } from '@patine-ui/pro';

export default function Example() {
  const confetti = useRef(null);
  const [state, setState] = useState<'ready' | 'paying' | 'done'>('ready');
  const [points, setPoints] = useState(1240);
  const pay = () => {
    setState('paying');
    setTimeout(() => {
      setState('done');
      setPoints((p) => p + 107);
      confetti.current?.fire({ mode: 'burst', origin: { x: 0.5, y: 0.4 } });
    }, 1400);
  };
  return (
    <View style={{ width: '100%', maxWidth: 380, height: 260, borderRadius: 16, borderWidth: 1, borderColor: '#8883', padding: 20, gap: 12, justifyContent: 'center' }}>
      <Text weight="semibold" size="lg">{state === 'done' ? 'Order #20418 placed' : 'Total €107.00'}</Text>
      <View style={{ flexDirection: 'row', alignItems: 'baseline', gap: 6 }}>
        <RollingNumber value={points} startValue={1240} size="xl" color="primary" />
        <Text color="textSecondary">points</Text>
      </View>
      {state === 'paying' ? (
        <ShimmerText>Confirming your payment…</ShimmerText>
      ) : (
        <Button disabled={state === 'done'} onPress={pay}>
          {state === 'done' ? 'Paid' : 'Pay €107.00'}
        </Button>
      )}
      <Confetti ref={confetti} />
    </View>
  );
}
```

## RollingNumber

Each digit rolls in its own column, like an odometer, to the new value. It formats by locale (separators, currency, percent, compact) with `Intl.NumberFormat`, and screen readers hear the number once. It rolls in from `startValue` (0) on mount; set `startValue={value}` to show it still.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button } from 'patine-ui';
import { RollingNumber } from '@patine-ui/pro';

export default function Example() {
  const [n, setN] = useState(12840);
  return (
    <View style={{ gap: 14 }}>
      <RollingNumber value={n} size="2xl" />
      <RollingNumber value={n * 1.37} locale="de-DE" currency="EUR" size="xl" />
      <RollingNumber value={n / 50000} format={{ style: 'percent', maximumFractionDigits: 1 }} size="xl" color="success" />
      <RollingNumber value={n * 120} format={{ notation: 'compact' }} size="xl" color="primary" />
      <Button variant="outline" style={{ alignSelf: 'flex-start' }} onPress={() => setN((v) => v + Math.round(Math.random() * 5000))}>
        Add sales
      </Button>
    </View>
  );
}
```

## Confetti

Place `Confetti` over the area it should fill (it never blocks touches) and call `ref.current.fire()`. A **burst** comes from a point, a **cannon** from both bottom corners, a **rain** from the top edge. Pieces tumble, flutter and fall with air drag; shots overlap if you fire again.

```tsx live
import { useRef } from 'react';
import { View } from 'react-native';
import { Button } from 'patine-ui';
import { Confetti } from '@patine-ui/pro';

export default function Example() {
  const ref = useRef(null);
  return (
    <View style={{ height: 280, borderRadius: 16, borderWidth: 1, borderColor: '#8883', alignItems: 'center', justifyContent: 'center', gap: 10 }}>
      <Button onPress={() => ref.current?.fire({ mode: 'burst', origin: { x: 0.5, y: 0.5 } })}>Burst</Button>
      <Button variant="outline" onPress={() => ref.current?.fire({ mode: 'cannon' })}>Cannons</Button>
      <Button variant="ghost" onPress={() => ref.current?.fire({ mode: 'rain' })}>Rain</Button>
      <Confetti ref={ref} />
    </View>
  );
}
```

For a whole-screen celebration, put it last in your screen's root view. `autoFire` throws once on mount, for a "You're in" screen.

## ShimmerText

A light sweeps across the letters while something works: an assistant thinking, a report generating, a search running. Plain text once `active` turns false.

```tsx live
import { View } from 'react-native';
import { ShimmerText } from '@patine-ui/pro';

export default function Example() {
  return (
    <View style={{ gap: 12 }}>
      <ShimmerText>Thinking…</ShimmerText>
      <ShimmerText size="lg" color="text">Searching 2,418 files for “refund policy”</ShimmerText>
      <ShimmerText size="sm" duration={1400}>Generating your quarterly report</ShimmerText>
    </View>
  );
}
```

## ShineBorder

A border with light running round it: the recommended plan, an AI input, a featured card. `'beam'` sends a comet of the colors round the edge; `'gradient'` turns the whole edge through them.

```tsx live
import { View } from 'react-native';
import { Button, Text } from 'patine-ui';
import { ShineBorder } from '@patine-ui/pro';

export default function Example() {
  return (
    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 16 }}>
      <ShineBorder style={{ width: 260 }}>
        <View style={{ padding: 20, gap: 6 }}>
          <Text size="sm" color="primary" weight="semibold">MOST POPULAR</Text>
          <Text size="2xl" weight="semibold">$24 / mo</Text>
          <Text size="sm" color="textSecondary">Unlimited projects, SSO, audit log.</Text>
          <Button style={{ marginTop: 8 }}>Start free trial</Button>
        </View>
      </ShineBorder>
      <ShineBorder variant="gradient" borderWidth={2} radius={28} colors={['#8B5CF6', '#EC4899', '#F59E0B', '#10B981']} style={{ width: 260, alignSelf: 'flex-start' }}>
        <View style={{ paddingHorizontal: 18, height: 52, justifyContent: 'center' }}>
          <Text color="textSecondary">Ask AI anything…</Text>
        </View>
      </ShineBorder>
    </View>
  );
}
```

## Marquee

A row that scrolls by on its own: customer logos, testimonials, a live ticker. It repeats its children to never show a gap, moves at `speed` points a second, stops under the pointer on the web, and fades its edges into `fadeColor`. Screen readers hear it once.

```tsx live
import { View } from 'react-native';
import { Text, useTheme } from 'patine-ui';
import { BrandIcon, Marquee } from '@patine-ui/pro';

const LOGOS = ['stripe', 'vercel', 'linear', 'notion', 'figma', 'github', 'slack', 'shopify'];

export default function Example() {
  const theme = useTheme();
  return (
    <View style={{ gap: 16 }}>
      <Marquee fadeColor={theme.colors.background} accessibilityLabel="Trusted by Stripe, Vercel, Linear, Notion, Figma, GitHub, Slack and Shopify" gap={40}>
        {LOGOS.map((name) => (
          <BrandIcon key={name} name={name} size={28} variant="mono" />
        ))}
      </Marquee>
      <Marquee reverse speed={30} fadeColor={theme.colors.background}>
        {['“Shipped our app in a week.” — Ana, Lumen', '“The tour cut our drop-off by a third.” — Leo, Fieldnote', '“Feels native on every phone.” — Kai, Orbit'].map((q) => (
          <Text key={q} color="textSecondary">{q}</Text>
        ))}
      </Marquee>
    </View>
  );
}
```

## TypingText and TextReveal

`TypingText` types a line a letter at a time with a blinking caret; give `words` to type, erase and type the next. `TextReveal` brings a headline in a word (or letter) at a time. Both read as one sentence to screen readers.

```tsx live
import { View } from 'react-native';
import { Text } from 'patine-ui';
import { TextReveal, TypingText } from '@patine-ui/pro';

export default function Example() {
  return (
    <View style={{ gap: 20 }}>
      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
        <Text size="xl" weight="semibold">Build apps that</Text>
        <TypingText words={['feel native.', 'ship faster.', 'look premium.']} size="xl" weight="semibold" color="primary" />
      </View>
      <TextReveal size="2xl">Welcome back, Maya. You have 3 reviews waiting.</TextReveal>
      <TextReveal by="letter" size="lg" weight="medium" color="textSecondary" delay={600}>Everything is in sync.</TextReveal>
    </View>
  );
}
```

## BlurFade and Stagger

Content that fades and rises into place, clearing a soft blur on the web. Wrap a list in `Stagger` to bring its items in one after another. Both start when `visible` turns true, so you can hold them until a section scrolls into view.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button, Card, CardDescription, CardTitle } from 'patine-ui';
import { Stagger } from '@patine-ui/pro';

const FEATURES = [
  ['Offline first', 'Edits sync when you are back online.'],
  ['Real-time', 'See teammates’ cursors as they type.'],
  ['Secure', 'SSO, SCIM and an audit log on every plan.'],
];

export default function Example() {
  const [key, setKey] = useState(0);
  return (
    <View style={{ gap: 12 }}>
      <Stagger key={key} step={90} style={{ gap: 10 }}>
        {FEATURES.map(([title, body]) => (
          <Card key={title} style={{ padding: 16 }}>
            <CardTitle>{title}</CardTitle>
            <CardDescription>{body}</CardDescription>
          </Card>
        ))}
      </Stagger>
      <Button variant="outline" style={{ alignSelf: 'flex-start' }} onPress={() => setKey((k) => k + 1)}>Replay</Button>
    </View>
  );
}
```

## Beacon and CounterBadge

`Beacon` is a dot with rings spreading from it: a live indicator, a driver on a map, a "new" mark. `CounterBadge` is an unread count that rolls to its new number and bumps when it goes up; it caps at "99+", can be a plain `dot`, and pins to the corner of what it wraps.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button, Text } from 'patine-ui';
import { Beacon, CounterBadge, Icon } from '@patine-ui/pro';

export default function Example() {
  const [count, setCount] = useState(3);
  return (
    <View style={{ gap: 20 }}>
      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>
        <Beacon color="success" size={8} accessibilityLabel="Live" />
        <Text size="sm" weight="medium">Live · 1,204 watching</Text>
      </View>
      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 28 }}>
        <CounterBadge count={count}>
          <Icon name="bell" size="lg" color="text" />
        </CounterBadge>
        <CounterBadge count={count * 40} tone="primary">
          <Icon name="mail" size="lg" color="text" />
        </CounterBadge>
        <CounterBadge count={1} dot>
          <Icon name="message" size="lg" color="text" />
        </CounterBadge>
        <Button size="sm" variant="outline" onPress={() => setCount((c) => c + 1)}>New message</Button>
      </View>
    </View>
  );
}
```

## Accessibility

- Numbers, typed and revealed text read as their final value or sentence, once, not letter by letter.
- Confetti, marquee copies and decorative rings are hidden from screen readers; give `Marquee` and `Beacon` an `accessibilityLabel` when they carry meaning.
- `CounterBadge` reads "3 new" by default; set `accessibilityLabel` for your wording.
- With the OS set to reduce motion, numbers and text show at once, loops hold still and no confetti flies.

## Props

### RollingNumber

| Prop | Type | Default |
| --- | --- | --- |
| `value` | `number` | |
| `startValue` | `number`: where it rolls from on mount | `0` |
| `locale` | `string` | the device's |
| `currency` | `string`, e.g. `'USD'` | |
| `decimals` | `number` | |
| `format` | `Intl.NumberFormatOptions`, wins over `currency` and `decimals` | |
| `size`, `weight`, `color` | text scale, weight, theme or CSS color | `'xl'`, `'semibold'`, `'text'` |
| `delay` | `number`, ms | `0` |
| `textStyle` | `TextStyle` | |

### Confetti

| Prop | Type | Default |
| --- | --- | --- |
| `ref` | `{ fire(options?) }`; options: `mode`, `count`, `origin {x, y}` (0–1), `colors` | |
| `mode` | `'burst' \| 'cannon' \| 'rain'` | `'burst'` |
| `colors` | `string[]` | the theme's primary and a festive mix |
| `count` | `number` per shot | 90, 70 a side, 120 |
| `duration` | `number`, seconds | `3` |
| `autoFire` | `boolean` | `false` |
| `onDone` | `() => void`, per shot | |

### ShimmerText, ShineBorder, Marquee

| Component | Props |
| --- | --- |
| `ShimmerText` | `children` (string), `active` (`true`), `duration` (`2000`), `size`, `weight`, `color` |
| `ShineBorder` | `variant` (`'beam'` \| `'gradient'`), `colors`, `borderWidth` (`1.5`), `radius`, `duration` (`4000`), `active`, `background`, `contentStyle` |
| `Marquee` | `speed` (`40` pt/s), `reverse`, `pauseOnHover` (`true`), `gap` (`32`), `fadeColor`, `accessibilityLabel` |

### TypingText, TextReveal, BlurFade, Stagger

| Component | Props |
| --- | --- |
| `TypingText` | `text` or `words`, `loop`, `speed` (`55` ms), `deleteSpeed` (`30`), `pause` (`1600`), `startDelay`, `cursor` (`true`), `onDone`, `size`, `weight`, `color` |
| `TextReveal` | `children` (string), `by` (`'word'` \| `'letter'`), `stagger`, `delay`, `visible`, `size`, `weight`, `color`, `textStyle` |
| `BlurFade` | `visible` (`true`), `delay`, `duration` (`500`), `offset` (`12`), `blur` (`6`, web) |
| `Stagger` | `step` (`70` ms), `delay`, `visible`, `offset` |

### Beacon, CounterBadge

| Component | Props |
| --- | --- |
| `Beacon` | `color` (primary), `size` (`10`), `rings` (`2`), `duration` (`1800`), `scale` (`3`), `active`, `accessibilityLabel` |
| `CounterBadge` | `count`, `max` (`99`), `dot`, `showZero`, `tone` (`'danger'` \| `'primary'` \| `'success'` \| color), `children`, `accessibilityLabel` |

## Related

- [Onboarding checklist](./onboarding-checklist): celebrates with `Confetti`.
- [Product tour](./product-tour): its hotspots pulse with `Beacon`.
- [Skeleton](./skeleton) and [Progress](./progress): loading states, free.
