info-flip-board

Credit: info-flip-board is inspired by magnum6actual/flipoff.

A responsive React split-flap information board with configurable messages, timing, colors, controlled and automatic modes, keyboard navigation, fullscreen support, and optional built-in sound.

Interactive board and timer demo · npm

Install

npm install info-flip-board

React and React DOM 18.2 or newer are peer dependencies. React 18 and React 19 are supported.

The package provides two React components:

• FlipOffBoard displays and rotates information messages.
• FlipOffTimer embeds an interactive countdown in a React application.

The component package contains no command-line runtime. Standalone timer and board commands are provided by the optional info-flip-board-cli package.

Usage

Import both the component and its published stylesheet:

import { FlipOffBoard } from 'info-flip-board';
import 'info-flip-board/styles.css';

const messages = [
  ['', 'ARRIVALS', 'ON TIME', 'PLATFORM 4', ''],
  ['', 'NEXT SERVICE', 'BOARDING NOW', 'HAVE A GOOD TRIP', ''],
];

export function InformationBoard() {
  return (
    <FlipOffBoard
      messages={messages}
      soundEnabled={false}
    />
  );
}

Message frames, rows, and looping

The outer messages array contains message frames. Each inner array contains the displayed rows for one frame:

const messages = [
  ['ARRIVALS', 'ON TIME', 'PLATFORM 4'],
  ['DEPARTURES', 'BOARDING', 'PLATFORM 7'],
];

With autoPlay enabled, the board loops through the frames. A single custom frame animates once but cannot rotate because there is no next frame:

// One frame containing three rows
const oneMessage = [['HELLO', 'WELCOME', 'PLEASE WAIT']];

Provide at least two distinct frames for a custom loop:

const customMessages = [
  ['HELLO CODER', 'WELCOME'],
  ['BUILD SOMETHING', 'AMAZING'],
  ['THANK YOU', 'SEE YOU SOON'],
];

<FlipOffBoard
  messages={customMessages}
  autoPlay
  messageInterval={3000}
/>

Providing currentMessageIndex enables controlled mode and disables automatic rotation because the parent application owns the active frame.

Countdown timer

FlipOffTimer renders an accurate split-flap countdown with Start, Pause, Resume, and Reset controls. Starting can request fullscreen because browsers only allow fullscreen from a user gesture.

import { FlipOffTimer } from 'info-flip-board';
import 'info-flip-board/styles.css';

export function PresentationTimer() {
  return (
    <FlipOffTimer
      durationSeconds={10 * 60}
      format="24"
      soundEnabled
      fullscreenOnStart
    />
  );
}

Timer durations must be whole seconds from 1 through 359999 (99:59:59). format="auto" displays MM:SS below one hour and HH:MM:SS otherwise. format="24" always displays HH:MM:SS.

The timer is a normal exported React component. Use FlipOffTimer in an installed application; use the CLI when you want a timer without creating an application.

Launch the standalone CLI

# Automatic MM:SS or HH:MM:SS format
npx --yes info-flip-board-cli@latest timer 10m

# Fixed HH:MM:SS format
npx --yes info-flip-board-cli@latest timer 10m --format 24

# Combined duration and disabled sound
npx --yes info-flip-board-cli@latest timer 1h30m15s --no-sound

# Alias form and no fullscreen request
npx --yes info-flip-board-cli@latest --timer 1m30s --no-fullscreen

# Serve without opening a browser
npx --yes info-flip-board-cli@latest timer 5m --no-open

# Combined options
npx --yes info-flip-board-cli@latest timer 1h30m \
  --format 24 \
  --no-sound \
  --no-fullscreen

Launch a board directly or from a JSON string[][] frame file:

npx --yes info-flip-board-cli@latest board "HELLO WORLD"
npx --yes info-flip-board-cli@latest board --file frames.json --interval 3000

[
  ["ARRIVALS", "ON TIME"],
  ["DEPARTURES", "BOARDING"]
]

If the CLI package is installed locally:

npm install --save-dev info-flip-board-cli
npx info-flip-board-cli timer 10m --format 24

Migration: releases using the split packages replace npx info-flip-board ... with npx info-flip-board-cli .... React imports continue to use info-flip-board.

Durations use case-insensitive whole-number h, m, and s segments in descending order.

| Valid | Meaning | | --- | --- | | 30s | 30 seconds | | 10m | 10 minutes | | 1h | 1 hour | | 1h30m | 1 hour and 30 minutes | | 1h30m15s | 1 hour, 30 minutes, and 15 seconds |

| Invalid | Reason | | --- | --- | | 10 | Unit is missing. | | 0m | Duration must be positive. | | 1m2h | Units are not in descending order. | | 1h60m | Minute segment is out of range. | | 60s | Second segment is out of range. | | 1h1h | Duplicate units are not allowed. |

The maximum is 99h59m59s. The CLI binds an available port on 127.0.0.1, opens the default browser, prints the local URL, and remains active until you press Ctrl+C.

| CLI option | Default | Description | | --- | --- | --- | | --format auto\|24 | auto | Select automatic or fixed HH:MM:SS display. | | --sound / --no-sound | sound on | Enable or disable the completion sound. | | --fullscreen / --no-fullscreen | fullscreen on | Control whether Start requests fullscreen. | | --no-open | browser opens | Print and serve the URL without launching a browser. |

Useful CLI checks:

npx --yes info-flip-board-cli@latest --help
npx --yes info-flip-board-cli@latest --version
npm view info-flip-board-cli@latest bin --json

If npx cached an older release:

npm cache clean --force
npm exec --yes --package=info-flip-board-cli@latest -- \
  info-flip-board-cli timer 10m --format 24

Controlled mode

import { useState } from 'react';
import { FlipOffBoard } from 'info-flip-board';
import 'info-flip-board/styles.css';

export function ControlledBoard() {
  const [index, setIndex] = useState(0);

  return (
    <FlipOffBoard
      messages={messages}
      currentMessageIndex={index}
      onMessageChange={setIndex}
      autoPlay={false}
    />
  );
}

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | cols | number | 22 | Number of columns. | | rows | number | 5 | Number of rows. | | messages | string[][] | Built-in quotes | Messages represented as arrays of rows. | | messageInterval | number | 4000 | Visible duration before automatic rotation, in milliseconds. | | scrambleDuration | number | 800 | Character scramble duration, in milliseconds. | | flipDuration | number | 300 | Tile settle duration, in milliseconds. | | staggerDelay | number | 25 | Delay between tile transitions, in milliseconds. | | charset | string | Alphanumeric set | Characters used during scrambling. | | scrambleColors | string[] | Built-in palette | Tile colors used during scrambling. | | accentColors | string[] | Built-in palette | Corner accent colors. | | soundEnabled | boolean | true | Enables the bundled flap sound. | | volume | number | 0.8 | Audio volume from 0 to 1. | | autoPlay | boolean | true | Rotates messages automatically in uncontrolled mode. | | currentMessageIndex | number | undefined | Enables controlled mode. | | onMessageChange | (index: number) => void | undefined | Reports requested message changes. | | showKeyboardShortcuts | boolean | true | Enables keyboard controls and the shortcut hint. |

Timer props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | durationSeconds | number | Required | Initial countdown duration from 1 through 359999 seconds. | | format | 'auto' \| '24' | 'auto' | Automatic width or fixed HH:MM:SS. | | soundEnabled | boolean | true | Plays one completion sound when browser audio is available. | | fullscreenOnStart | boolean | true | Requests fullscreen from the Start interaction. | | volume | number | 0.8 | Completion audio volume from 0 to 1. | | onStateChange | (state) => void | undefined | Reports ready, running, paused, and completed states. | | onComplete | () => void | undefined | Runs once when the countdown reaches zero. |

Keyboard controls

When showKeyboardShortcuts is enabled:

• Enter, Space, or ArrowRight: next message
• ArrowLeft: previous message
• F: toggle fullscreen
• M: toggle sound
• Escape: close shortcuts or leave fullscreen

Keyboard events originating from inputs and textareas are ignored.

Browser and static rendering

The package does not access browser globals during module evaluation, so it can be imported by server-rendered and static-build React tooling. Audio, keyboard listeners, and fullscreen behavior initialize only in the browser.

Audio playback requires a user gesture under modern browser autoplay policies. In Astro, hydrate the component with a client directive. In Docusaurus or similar static-rendering systems, render or hydrate the interactive component on the client.

The standalone CLI requires Node.js 20 or newer and opens a loopback-only HTTP server. If automatic browser launching is unavailable, the CLI prints the local URL for manual opening.

Development

npm install
npm run dev
npm run test
npm run lint
npm run build
npm run pack:check
npm run test:package

npm run validate runs linting, component tests, the library and site builds, package archive inspection, and packed-package tests against React 18 and React 19.

The library is written to dist/. The GitHub Pages site is written to site-dist/.

Publishing

1. Update package.json to the intended release version.
2. Run npm run validate.
3. Push the change and create a GitHub release tagged v<version>.
4. The release workflow verifies the tag, confirms the version is unpublished, rebuilds the package, and publishes the inspected archive with npm provenance.

The npm package uses GitHub trusted publishing configured for:

• Repository: abudhahir/info-flip-board
• Workflow: .github/workflows/release.yml
• Environment: no npm environment is required by the workflow

GitHub Pages setup

In the GitHub repository settings, set Pages → Build and deployment → Source to GitHub Actions. Pushes to main then build and deploy site-dist/ through .github/workflows/pages.yml.

License

MIT