# Hello Wave

> An animated waving hand emoji component with smooth rotation animation and customizable sizes.

**BNA UI** — a React Native / Expo component library.
These components render through `react-native`, not the DOM: there are no HTML
elements, no Tailwind classes and no Radix primitives. Source is copied into your
project and imported through `@/components/ui/*`, `@/components/charts/*`,
`@/hooks/*` and `@/theme/*`. Colours come from the `useColor` hook rather than
hardcoded hex; sizing tokens (`HEIGHT`, `FONT_SIZE`, `BORDER_RADIUS`, `CORNERS`)
come from `@/theme/globals`.

- Docs: https://ui.ahmedbna.com/docs/components/hello-wave
- Markdown: https://ui.ahmedbna.com/docs/components/hello-wave.md
- Structured JSON (props, usage, source, examples): https://ui.ahmedbna.com/r/ai/hello-wave.json
- Install payload (source plus every file it imports): https://ui.ahmedbna.com/r/hello-wave.json
- Install: `npx bna-ui add hello-wave`
- npm dependencies: `react-native-reanimated`, `react-native-worklets`
- Registry dependencies: `mode-provider`, `useColorScheme`, `colors`, `useColor`, `globals`, `text`, `view`
- Preview recording: https://demo.ahmedbna.com/0151-hello-wave-demo.mov

---

**Example:** An animated waving hand emoji with size variants

```tsx
// components/demo/hello-wave/hello-wave-demo.tsx
import { HelloWave } from '@/components/ui/hello-wave';
import React from 'react';

export function HellowWaveDemo() {
  return <HelloWave>👋</HelloWave>;
}
```

## Installation

### CLI

```bash
npx bna-ui add hello-wave
```

### Manual

**1.** Install the following dependencies:

```bash
npx expo install react-native-reanimated
```

**2.** Copy and paste the following code into your project.

```tsx
// components/ui/hello-wave.tsx
import { Text } from '@/components/ui/text';
import { View } from '@/components/ui/view';
import { useEffect } from 'react';
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withRepeat,
  withSequence,
  withTiming,
} from 'react-native-reanimated';

interface HelloWaveProps {
  size?: 'sm' | 'md' | 'lg';
  children?: React.ReactNode;
}

const sizeVariants = {
  sm: {
    fontSize: 20,
    lineHeight: 24,
    marginTop: -4,
  },
  md: {
    fontSize: 28,
    lineHeight: 32,
    marginTop: -6,
  },
  lg: {
    fontSize: 36,
    lineHeight: 40,
    marginTop: -8,
  },
};

export function HelloWave({ children = '👋', size = 'md' }: HelloWaveProps) {
  const rotationAnimation = useSharedValue(0);

  useEffect(() => {
    rotationAnimation.value = withRepeat(
      withSequence(
        withTiming(25, { duration: 150 }),
        withTiming(0, { duration: 150 })
      ),
      4 // Run the animation 4 times
    );
  }, [rotationAnimation]);

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [
      {
        rotate: `${rotationAnimation.value}deg`,
      },
    ],
  }));

  const sizeStyle = sizeVariants[size];

  return (
    <View style={{ alignItems: 'center', justifyContent: 'center' }}>
      <Animated.View style={animatedStyle} accessibilityLabel='waving hand'>
        {typeof children === 'string' ? (
          <Text style={sizeStyle}>{children}</Text>
        ) : (
          children
        )}
      </Animated.View>
    </View>
  );
}
```

**3.** Update the import paths to match your project setup.

## Usage

```tsx
import { HelloWave } from '@/components/ui/hello-wave';
```

```tsx
<HelloWave />
```

```tsx
<HelloWave size='lg' />
```

```tsx
<HelloWave size='sm'>🙋‍♀️</HelloWave>
```

## Examples

#### Default

**Example:** Default animated waving hand emoji

```tsx
// components/demo/hello-wave/hello-wave-demo.tsx
import { HelloWave } from '@/components/ui/hello-wave';
import React from 'react';

export function HellowWaveDemo() {
  return <HelloWave>👋</HelloWave>;
}
```

## API Reference

### HelloWave

An animated component that displays a waving hand emoji with rotation animation and customizable sizes.

| Prop       | Type                   | Default | Description                                         |
| ---------- | ---------------------- | ------- | --------------------------------------------------- |
| `size`     | `'sm' \| 'md' \| 'lg'` | `'md'`  | Controls the size of the emoji and animation scale. |
| `children` | `React.ReactNode`      | `'👋'`  | Content to animate - typically an emoji string.     |

## Size Variants

The component includes three predefined size variants:

| Size | Font Size | Line Height | Use Case                    |
| ---- | --------- | ----------- | --------------------------- |
| `sm` | 20px      | 24px        | Inline text, compact spaces |
| `md` | 28px      | 32px        | Default size, most contexts |
| `lg` | 36px      | 40px        | Headers, prominent display  |

## Animation Details

- **Duration**: 150ms for each rotation phase
- **Rotation Range**: 0° to 25° and back to 0°
- **Repetitions**: 4 complete wave cycles
- **Timing**: Runs automatically on component mount
- **Easing**: Uses default timing function for smooth animation

## Customization

### Custom Content

You can pass any content as children, not just the default wave emoji:

```tsx
<HelloWave>🙋‍♀️</HelloWave>
<HelloWave>✨</HelloWave>
<HelloWave size="lg">🎉</HelloWave>
```

### Custom Components

For more complex customization, you can pass React components:

```tsx
<HelloWave>
  <CustomIcon name='wave' />
</HelloWave>
```

### Styling

The component uses a centered container layout. For additional styling, wrap the component:

```tsx
<View style={{ margin: 16 }}>
  <HelloWave size='lg' />
</View>
```

## Technical Notes

- Uses `react-native-reanimated` for smooth 60fps animations
- Animation runs on the UI thread for better performance
- Automatically starts animation when component mounts
- Uses `useSharedValue` and `useAnimatedStyle` for optimal performance
- Size variants include margin adjustments for proper vertical alignment
- Supports both string content and React components as children

## Accessibility

The HelloWave component:

- Uses semantic emoji that screen readers can interpret
- Maintains proper text sizing for accessibility
- Works with system accessibility settings
- Animation doesn't interfere with screen reader functionality
- Proper font sizing scales with system text size preferences