Secret Sequence React

React hook & component for detecting directional sequences, key combos, and touch gestures — powered by secret-sequence-core.

This package provides React bindings for the Secret Sequence monorepo.
It wraps the core engine in a hook and a declarative component with full lifecycle management.

Installation

npm install secret-sequence-react secret-sequence-core

secret-sequence-core is a peer dependency.

Quick Start

Hook — useSecretSequence

import { useSecretSequence } from "secret-sequence-react"

function App() {
  const { progress } = useSecretSequence({
    sequences: [
      {
        id: "konami",
        sequence: ["up", "up", "down", "down", "left", "right", "left", "right"],
        onSuccess: () => alert("🎉 Konami Code activated!"),
      },
    ],
    enableTouch: true,
    touchOptions: { minDistance: 50, maxTime: 400 },
  })

  return <pre>{JSON.stringify(progress, null, 2)}</pre>
}

Component — <SecretSequence />

Invisible Mode (effect only)

import { SecretSequence } from "secret-sequence-react"

function App() {
  return (
    <SecretSequence
      sequences={[
        {
          id: "konami",
          sequence: ["up", "up", "down", "down", "left", "right", "left", "right"],
          onSuccess: () => console.log("🎉"),
        },
      ]}
      enableTouch={true}
      touchOptions={{ minDistance: 40 }}
    />
  )
}

With render prop

<SecretSequence
  sequences={[{ id: "code", sequence: ["up", "down"], onSuccess: fn }]}
>
  {({ progress, reset }) => (
    <div>
      <p>Progress: {JSON.stringify(progress)}</p>
      <button onClick={reset}>Reset</button>
    </div>
  )}
</SecretSequence>

Stratagem-Style Input

const { progress } = useSecretSequence({
  sequences: [
    {
      id: "orbitalStrike",
      sequence: ["right", "right", "up"],
      onSuccess: () => deployStrike(),
    },
  ],
  timeout: 2000,
})

Key Combo Shortcut

const { progress } = useSecretSequence({
  sequences: [
    {
      id: "shortcut",
      sequence: [{ key: "k", ctrl: true }],
      onSuccess: () => console.log("Shortcut triggered"),
    },
  ],
})

Touch Gesture Support

Swipe gestures on touch devices are automatically mapped to directional steps.

const { progress } = useSecretSequence({
  sequences: [
    {
      id: "swipe-pattern",
      sequence: ["up", "down", "left", "right"],
      onSuccess: () => alert("Swipe pattern detected!"),
    },
  ],
  enableTouch: true,
  touchOptions: {
    minDistance: 30,
    maxTime: 300,
    threshold: 1.5,
  },
})

API

useSecretSequence(options)

React hook that manages the engine lifecycle automatically.

Returns: { progress, reset }

| Return | Type | Description | | ---------- | -------------------------- | ----------------------------- | | progress | Record<string, number> | Current progress per sequence | | reset | () => void | Reset all sequence progress |

<SecretSequence /> Component

Declarative JSX wrapper over the useSecretSequence hook.

| Prop | Type | Description | | ------------------ | ----------------------------------------------------------------------- | ---------------------------------------- | | onProgressChange | (progress: Record<string, number>) => void | Callback fired on progress changes | | children | (state: { progress: Record<string, number>; reset: () => void }) => … | Optional render prop for progress/reset | | ...hookOptions | UseSecretSequenceOptions | All hook options (see below) |

Options (shared by hook & component)

| Option | Type | Default | Description | | -------------- | ------------------------ | ------- | ------------------------------------------------------ | | sequences | SecretSequenceConfig[] | — | Array of sequences to detect simultaneously | | timeout | number | 2000 | Milliseconds of inactivity before resetting progress | | enabled | boolean | true | Globally enable or disable detection | | enableTouch | boolean | true | Enable swipe gesture detection | | ignoreInputs | boolean | true | Ignore key events when focus is on input-like elements | | touchOptions | TouchConfig | — | Advanced touch configuration |

Configuration Types

SecretSequenceConfig

| Property | Type | Description | | ----------- | --------------------- | ------------------------------------------- | | id | string (optional) | Unique identifier (defaults to array index) | | sequence | SequenceStep[] | Ordered steps to detect | | onSuccess | () => void | Fired when the sequence completes |

Core Types

type Direction = "up" | "down" | "left" | "right"

type KeyCombo = {
  key: string
  ctrl?: boolean
  shift?: boolean
  alt?: boolean
  meta?: boolean
}

type SequenceStep = Direction | KeyCombo

TouchConfig

| Property | Type | Default | Description | | ------------- | -------- | ------- | ---------------------------------------------- | | minDistance | number | 30 | Minimum swipe distance (px) | | maxTime | number | 300 | Maximum swipe duration (ms) | | threshold | number | 1.5 | Axis dominance ratio to reject diagonal swipes |

SSR Compatibility

This package is safe to use in SSR environments such as Next.js or Remix.

The underlying engine guards against accessing window during server rendering and only attaches event listeners in the browser.

License

MIT © Diego Alonso