React Split Flap

A React component that simulates the classic split-flap display effect, inspired by train stations and airport displays.

Live Demo
GitHub Repository

Features

• Realistic Flip Animation - Simulates authentic mechanical flipping effects
• Multiple Themes - Built-in light and dark themes
• Various Sizes - From small to extra-large size options
• Highly Customizable - Support for custom character sets, animation speed, etc.
• TypeScript Support - Complete type definitions
• LongFlap Component - Support for complex ReactNode content with ID-based switching

Installation

npm install react-split-flap
# or
yarn add react-split-flap

Quick Start

import React from 'react'
import { SplitFlap, Presets } from 'react-split-flap'

function App() {
  return <SplitFlap value="HELLO" chars={Presets.ALPHANUM} length={5} />
}

Components

SplitFlap - Character Display

Perfect for displaying strings with character-by-character flipping animation.

Props

Property	Type	Default	Description
value	string	-	Value to display
length	number	-	Number of digits to display. If set to 1, will display full value on one flap
chars	string[]	Presets.NUM	Available character set
padChar	string	' '	Padding character
padMode	'auto' | 'start' | 'end'	'auto'	'auto' will align number right and string left
digitWidth	number	-	Custom width for each digit (pixels)
timing	number	30	Animation interval (milliseconds)
hinge	boolean	true	Whether to show hinge line
theme	'default' | 'light' | 'dark'	'default'	Theme variant
size	'small' | 'medium' | 'large' | 'xlarge'	'medium'	Size variant
className	string	''	CSS class name
style	React.CSSProperties	-	Inline styles
background	string	-	Custom background color or gradient for the flaps
fontColor	string	-	Custom font color for the flap text
render	(children: ReactNode) => ReactNode	-	Custom render function

LongFlap - Complex Content Display

Perfect for displaying complex ReactNode components with ID-based switching, ideal for icons, styled content, and rich components.

Props

Property	Type	Default	Description
flaps	Array<{id: string | number, component: ReactNode}>	-	Array of flap items with ID and component
displayId	string | number	-	Current display ID to show
digitWidth	number	-	Custom width for the flap (pixels)
digitHeight	number	-	Custom height for the flap (pixels)
timing	number	60	Animation timing (milliseconds)
hinge	boolean	true	Whether to show hinge line
theme	'default' | 'light' | 'dark'	'default'	Theme variant
size	'small' | 'medium' | 'large' | 'xlarge'	'medium'	Size variant
className	string	''	CSS class name
style	React.CSSProperties	-	Inline styles
background	string	-	Custom background color or gradient for the flaps
fontColor	string	-	Custom font color for the flap text
render	(children: ReactNode) => ReactNode	-	Custom render function

When to use LongFlap vs SplitFlap

• Use SplitFlap when displaying strings or simple text with character-by-character flipping
• Use LongFlap when you need:
  • Complex ReactNode components (icons + text, styled content, etc.)
  • ID-based switching between predefined states
  • Single flap displaying rich content
  • Custom rendering of complex elements

Built-in Themes & Sizes

Sizes

• small - 20px
• medium - 36px (default)
• large - 54px
• xlarge - 84px

Themes

• default - Default styling
• light - Light theme
• dark - Dark theme

Usage Examples

SplitFlap Examples

Basic Counter

import React, { useState } from 'react'
import { SplitFlap, Presets } from 'react-split-flap'

function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <SplitFlap value={count.toString()} chars={Presets.NUM} length={3} className="medium light" padMode="start" />
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  )
}

Text Display

import React, { useState, useEffect } from 'react'
import { SplitFlap, Presets } from 'react-split-flap'

function TextCarousel() {
  const words = ['HELLO', 'WORLD', 'REACT']
  const [currentWord, setCurrentWord] = useState(words[0])

  useEffect(() => {
    let index = 0
    const interval = setInterval(() => {
      index = (index + 1) % words.length
      setCurrentWord(words[index])
    }, 2000)

    return () => clearInterval(interval)
  }, [])

  return <SplitFlap value={currentWord} chars={Presets.ALPHANUM} length={5} className="large dark" timing={20} />
}

Custom Styling

import React from 'react'
import { SplitFlap, Presets } from 'react-split-flap'

function CustomStyledFlap() {
  return (
    <SplitFlap
      value="CUSTOM"
      chars={Presets.ALPHANUM}
      length={6}
      size="large"
      background="linear-gradient(45deg, #ff6b6b, #4ecdc4)"
      fontColor="#ffffff"
      timing={50}
    />
  )
}

LongFlap Examples

Weather Display

import React, { useState } from 'react'
import { LongFlap } from 'react-split-flap'

/* Keep prop "flaps" constant. Will trigger <LongFlap /> re-render when changed. */
const weatherFlaps = [
  {
    id: 'sunny',
    component: (
      <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
        <span>☀️</span>
        <span>Sunny</span>
      </div>
    ),
  },
  {
    id: 'rainy',
    component: (
      <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
        <span>🌧️</span>
        <span>Rainy</span>
      </div>
    ),
  },
]

function WeatherDisplay() {
  const [currentWeather, setCurrentWeather] = useState('sunny')

  return <LongFlap flaps={weatherFlaps} displayId={currentWeather} digitWidth={200} size="large" theme="dark" />
}

Custom Styled LongFlap

import React from 'react'
import { LongFlap } from 'react-split-flap'

const styledFlaps = [
  {
    id: 'status1',
    component: <div style={{ fontSize: '24px', fontWeight: 'bold' }}>🚀 READY</div>,
  },
  {
    id: 'status2',
    component: <div style={{ fontSize: '24px', fontWeight: 'bold' }}>⚡ ACTIVE</div>,
  },
]

function CustomStyledLongFlap() {
  const [status, setStatus] = useState('status1')

  return (
    <LongFlap
      flaps={styledFlaps}
      displayId={status}
      digitWidth={250}
      digitHeight={80}
      background="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
      fontColor="#ffffff"
      timing={100}
      size="xlarge"
    />
  )
}

Development

Local Development

# Clone the project
git clone <repository-url>
cd react-split-flap

# Install dependencies
yarn install

# Build the package
yarn global add yalc
yarn dev:publish #use yalc to public local

# Start demo
cd demo
yarn install
yarn dev:hot #force vite use fresh package

Build

yarn build

License

MIT License

Contributing

Issues and Pull Requests are welcome!