react-native-spoiler-view

Telegram-style spoiler content for React Native, rendered with native particles.

Features

• Controlled and uncontrolled reveal state
• Touch-origin circular reveal
• Three particle depth/opacity tiers
• Hidden descendants are blocked from touch, VoiceOver, and TalkBack
• Runtime-safe configuration with bounded particle work
• Platform-native particle rendering on iOS and Android
• Shared Android ambient texture work instead of per-view simulation
• Core Animation ambient particles on iOS

Compatibility

The package is maintained against two integration lanes:

| Lane | React Native | React | Reanimated | Gesture Handler | | --- | --- | --- | --- | --- | | Legacy | 0.73.x | 18.x | 3.15.5 | 2.18.x | | Current | 0.86.x | 19.x | 4.5.x + Worklets 0.10.x | 3.x |

Reanimated 4 requires React Native's New Architecture and react-native-worklets. Select dependency versions that support your React Native version rather than installing unrelated latest majors.

Installation

Install the component and the compatible native peers:

npm install react-native-spoiler-view \
  react-native-reanimated \
  react-native-gesture-handler

For Reanimated 4, also install Worklets:

npm install react-native-worklets

React Native Community CLI apps using Reanimated 4 must put the Worklets plugin last in babel.config.js:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: ['react-native-worklets/plugin'],
};

Wrap the application near its root with GestureHandlerRootView:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <YourApp />
    </GestureHandlerRootView>
  );
}

Follow the native installation instructions for Reanimated and Gesture Handler, then run CocoaPods for iOS.

Usage

Uncontrolled

import { Text } from 'react-native';
import { SpoilerView } from 'react-native-spoiler-view';

<SpoilerView accessibilityRevealLabel="Hidden message">
  <Text>This is a secret message.</Text>
</SpoilerView>;

The component owns its reveal state. Tapping toggles between hidden and revealed.

Controlled

const [revealed, setRevealed] = useState(false);

<SpoilerView
  revealed={revealed}
  onReveal={() => setRevealed(true)}
  onHide={() => setRevealed(false)}
  accessibilityRevealLabel="Hidden account number"
>
  <Text>1234 5678 9012 3456</Text>
</SpoilerView>;

In controlled mode, callbacks request a state change. The component animates only when the revealed prop changes, so a parent may accept or reject the request without visual desynchronization.

Custom particles

<SpoilerView
  config={{
    particleCount: 300,
    particleColor: 'rgba(255, 100, 100, 1)',
    particleSizeRange: [0.5, 1.5],
    revealDuration: 400,
  }}
>
  <Image source={secretImage} />
</SpoilerView>

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | children | ReactNode | required | Content hidden by the spoiler | | revealed | boolean | uncontrolled | Parent-owned reveal state | | enabled | boolean | true | Enables reveal/hide gestures | | onReveal | () => void | — | Reveal request callback | | onHide | () => void | — | Hide request callback | | config | Partial<SpoilerConfig> | — | Particle and animation overrides | | style | StyleProp<ViewStyle> | — | Container style | | accessibilityRevealLabel | string | Hidden content | Label announced while hidden | | accessibilityRevealHint | string | Double tap to reveal | Reveal action hint | | accessibilityHideLabel | string | Hide content | Action label exposed while revealed | | accessibilityHideHint | string | Double tap to hide | Hide action hint |

Configuration

interface SpoilerConfig {
  particleCount: number;                // Default target/cap 180; maximum 1000
  particleDensity?: number;             // Default 0.055 per logical px², capped at 1000 total
  particleSizeRange: [number, number];  // Default [0.45, 0.8]
  particleColor: string;                // Default rgba(80, 80, 80, 1)
  overlayColor: string;                 // Default transparent
  noiseSpeed: number;                   // Ambient motion speed, default 0.3
  driftAmount: number;                  // Maximum ambient drift, default 1
  revealDuration: number;               // Default 500 ms
}

Unsafe numeric inputs are normalized at runtime. Particle work is always capped by MAX_PARTICLE_COUNT, which is exported for consumers that expose configuration controls. Providing particleCount without particleDensity opts into a fixed target. With density, particleCount is the per-view cap, keeping the canonical dust adaptive without allowing a large spoiler to monopolize the frame budget.

Development

npm install
npm run check

The example application is the maintained iOS and Android integration harness.

License

MIT