Animation

All animations in HeroUI Native are built with react-native-reanimated and gesture control is handled by react-native-gesture-handler. It's worth familiarizing yourself with these libraries if you want more control over animations.

The animation Prop

Every animated component in HeroUI Native exposes a single animation prop that controls all animations for that component. This prop allows you to modify animation values, timing configurations, layout animations, or completely disable animations.

Approach: If you're working with animations, first look for the animation prop on the component you're using.

Modifying Animations

You can customize animations by passing an object to the animation prop. Each component exposes different animation properties that you can modify. The approach is simple: if you want to slightly change the animation behavior of already written animations in components, we provide all necessary values for modification. If you want to write your own animations without relying on our written ones, you must create your own custom components with animations.

Example 1: Simple Value Modification

Modify animation values like scale, opacity, or colors:

import {Switch} from 'heroui-native';

<Switch
  animation={{
    scale: {
      value: [1, 0.9], // [unpressed, pressed]
    },
    backgroundColor: {
      value: ['#172554', '#eab308'], // [unselected, selected]
    },
  }}>
  <Switch.Thumb />
</Switch>;

Example 2: Timing Configuration

Customize animation timing and easing:

import {Accordion} from 'heroui-native';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Trigger>
      <Accordion.Indicator
        animation={{
          rotation: {
            value: [0, -180],
            springConfig: {
              damping: 60,
              stiffness: 900,
              mass: 3,
            },
          },
        }}
      />
    </Accordion.Trigger>
  </Accordion.Item>
</Accordion>;

Example 3: Layout Animations (Entering/Exiting)

Customize entering and exiting animations using Reanimated's layout animations:

import {Accordion} from 'heroui-native';
import {FadeInRight, FadeInLeft, ZoomIn} from 'react-native-reanimated';
import {Easing} from 'react-native-reanimated';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Content
      animation={{
        entering: {
          value: FadeInRight.delay(50).easing(Easing.inOut(Easing.ease)),
        },
      }}>
      Content here
    </Accordion.Content>
  </Accordion.Item>
</Accordion>;

Disabling Animations

You can disable animations at different levels using the animation prop.

Disable Options

• animation={false} or animation="disabled": Disable animations for the specific component only
• animation="disable-all": Disable all animations including children (only available at root level)
• animation={true} or animation={undefined}: Use default animations

Component-Level Disabling

Disable animations for a specific component:

<Switch>
  <Switch.Thumb animation={false} />
</Switch>

Root-Level Disabling (disable-all)

The "disable-all" option is only available at the root level of compound components. When used, it disables all animations including children, even if those children are not part of the compound component structure:

// Disables all animations including Button components inside Card
<Card animation="disable-all">
  <Card.Body>
    <Card.Title>$450</Card.Title>
    <Card.Description>Living room Sofa</Card.Description>
  </Card.Body>
  <Card.Footer className="gap-3">
    <Button variant="primary">Buy now</Button>
    <Button variant="ghost">Add to cart</Button>
  </Card.Footer>
</Card>

Important: "disable-all" cascades down to all child components, including standalone components like Button, Spinner, etc., not just compound component parts.

Global Animation Configuration

You can disable all HeroUI Native animations globally using the HeroUINativeProvider:

import {HeroUINativeProvider} from 'heroui-native';

<HeroUINativeProvider
  config={{
    animation: 'disable-all',
  }}>
  <App />
</HeroUINativeProvider>;

This will disable all animations across your entire application, regardless of individual component animation prop settings.

Accessibility

Reduce motion is handled automatically under the hood. When a user enables "Reduce Motion" in their device accessibility settings, all animations are automatically disabled globally. This is handled by the GlobalAnimationSettingsProvider which checks useReducedMotion() from react-native-reanimated.

You don't need to do anything - the library respects the user's accessibility preferences automatically.

Animation State Management

We keep disabled state of animations under control internally to ensure they look nice without unpredictable lags or jumps. When animations are disabled, components immediately jump to their final state rather than animating, preventing visual glitches or intermediate states.

Children Render Function

Many components support a render function pattern for children, which is particularly handy when working with state like isSelected:

import {Switch} from 'heroui-native';

<Switch
  isSelected={isSelected}
  onSelectedChange={setIsSelected}>
  {({isSelected, isDisabled}) => (
    <Switch.Thumb>{isSelected ? <CheckIcon /> : <XIcon />}</Switch.Thumb>
  )}
</Switch>;

This pattern allows you to conditionally render content based on component state, making it easy to create dynamic UIs that respond to selection, disabled states, and other component properties.

Next Steps

• Learn about Styling approaches
• View Theming documentation
• Explore Colors documentation