SplitFlap

An animated split-flap display component for React, featuring smooth CSS animations and flexible state management with gurx.

Features

• Split-flap display animation using pure CSS (no heavy animation libraries)
• Flexible usage patterns: auto-generation, render props, or manual control
• Per-card imperative API (pause, resume, skip)
• TypeScript support with full type definitions
• Customizable character sets (including Unicode and emoji support)
• Lightweight and performant

Installation

npm install splitflap

Peer Dependencies

This package requires the following peer dependencies:

npm install react react-dom @mdxeditor/gurx

Quick Start

import { SplitFlapBoard } from 'splitflap'

function App() {
  return <SplitFlapBoard message="HELLO WORLD" />
}

That's it! The components prop is optional and uses sensible defaults.

Custom Styling

To customize the appearance, provide your own components:

import { SplitFlapBoard, DEFAULT_COMPONENTS } from 'splitflap'

const customComponents = {
  ...DEFAULT_COMPONENTS,
  Flap: ({ char, position, face, style, ...props }) => {
    const effectivePosition = face === 'back' ? 'bottom' : position
    return (
      <div
        {...props}
        style={{
          width: '100%',
          height: '100%',
          overflow: 'hidden',
          display: 'flex',
          alignItems: effectivePosition === 'top' ? 'flex-end' : 'flex-start',
          justifyContent: 'center',
          backgroundColor: '#2a2d34',
          color: 'white',
          ...style,
        }}
      >
        <span
          style={{
            fontSize: '2rem',
            lineHeight: 1,
            userSelect: 'none',
            transform: effectivePosition === 'top' ? 'translateY(50%)' : 'translateY(-50%)',
          }}
        >
          {char}
        </span>
      </div>
    )
  },
}

function App() {
  return (
    <SplitFlapBoard
      message="HELLO WORLD"
      components={customComponents}
      animationDuration={100}
    />
  )
}

Usage Patterns

1. Auto-generation (Recommended)

The simplest approach - just provide a message:

<SplitFlapBoard
  message="HELLO"
  animationDuration={70}
  onCardComplete={(char, index) => console.log(`Card ${index} done`)}
  onAllComplete={() => console.log('All cards completed!')}
/>

Optionally provide custom components for styling:

<SplitFlapBoard
  message="HELLO"
  components={customComponents}
  animationDuration={70}
/>

2. Render Prop Pattern

For more control over individual cards:

<SplitFlapBoard
  message="HELLO"
  animationDuration={70}
  cards={(index) => (
    <SplitFlapCard
      targetChar={message[index]}
      components={customComponents}
      className={index % 2 === 0 ? 'even' : 'odd'}
    />
  )}
/>

3. Manual Control

Full control over card rendering and layout:

<SplitFlapBoard message="HELLO" animationDuration={100}>
  <div className="flex gap-2">
    <SplitFlapCard targetChar="H" components={components} />
    <SplitFlapCard targetChar="E" components={components} />
    <SplitFlapCard targetChar="L" components={components} />
    <SplitFlapCard targetChar="L" components={components} />
    <SplitFlapCard targetChar="O" components={components} />
  </div>
</SplitFlapBoard>

Imperative API

Control individual cards programmatically:

const cardRef = useRef<SplitFlapCardHandle>(null)

<SplitFlapCard
  ref={cardRef}
  targetChar="A"
  components={components}
  onComplete={() => console.log('Done!')}
/>

// Control the card
cardRef.current?.pause()   // Pause animation
cardRef.current?.resume()  // Resume animation
cardRef.current?.skip()    // Skip to target immediately

API Reference

SplitFlapBoard Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | message | string | Required | The message to display | | components | SplitFlapCardComponents | Required (auto-gen) | Component configuration for rendering cards | | animationDuration | number | 70 | Animation duration per flip in milliseconds | | characterSet | string \| string[] | DEFAULT_CHARACTER_SET | Available characters for animation | | pause | boolean | false | Whether to pause all animations | | onAllComplete | () => void | - | Callback when all cards complete | | onCardComplete | (char: string, index: number) => void | - | Callback for individual card completion | | cards | (index: number) => ReactNode | - | Render prop for custom card rendering |

SplitFlapCard Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | targetChar | string | Required | The target character to display | | components | SplitFlapCardComponents | Required | Component configuration | | animationDuration | number | From provider | Override animation duration | | characterSet | string \| string[] | From provider | Override character set | | onComplete | () => void | - | Callback when card reaches target |

SplitFlapCardComponents Interface

interface SplitFlapCardComponents {
  Container: React.ComponentType<ContainerProps>
  Flap: React.ComponentType<FlapProps>
  SplitLine: React.ComponentType<SplitLineProps>
}

Character Sets

Default Character Set

Includes A-Z, 0-9, common punctuation, and Katakana characters.

Custom Character Sets

Use strings for simple sequences:

<SplitFlapBoard
  message="123"
  characterSet="0123456789"
  components={components}
/>

Or arrays for complex characters:

<SplitFlapBoard
  message="Hello"
  characterSet={['H', 'e', 'l', 'o', '👋', '🌍']}
  components={components}
/>

Examples

See the examples/ directory for a complete demo with various styling options.

License

MIT