---
name: bijection-timeline
description: "Evaluate and integrate the Timeline component with Bijection."
---

# Timeline

Undo, redo and named checkpoints

- Package: @bijectionhq/timeline
- Category: Collaboration
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/timeline/tree/4c390f91c6279d50dbff441f98b216a3ce1e3833
- Upstream: https://github.com/MeshanKhosla/convex-timeline/tree/3c5a1740eb2e5107d0837adad7b213ccf036a01c
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/timeline

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/timeline.git
cd timeline
git checkout 4c390f91c6279d50dbff441f98b216a3ce1e3833
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-timeline. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Timeline

## Instructions

A Convex component that provides undo/redo state management with automatic pruning and named checkpoints. It maintains a linear history of state snapshots organized by scope, allowing developers to navigate backward and forward through application state. The component includes configurable capacity limits to prevent unbounded growth and supports persistent checkpoints that survive timeline pruning operations.

### Installation

```bash
npm install convex-timeline
```

## Use cases

• **Document editors** - Add undo/redo functionality to text editors, drawing applications, or form builders where users need to revert changes
• **Multi-step workflows** - Enable users to backtrack through complex processes like onboarding flows, surveys, or configuration wizards
• **Collaborative editing** - Maintain state history per document or user session with automatic cleanup to manage storage costs
• **Game state management** - Track player actions or game board states with the ability to rewind to previous moves or save checkpoint states
• **Draft management** - Allow users to experiment with changes while preserving known good states through named checkpoints

## How it works

The component stores state snapshots in a linear timeline organized by scope, with each scope maintaining its own independent history. You create a `Timeline` instance from your component configuration and can either use it directly with scope parameters or create scoped facades using `forScope()` for cleaner APIs.

Core operations include `push()` to add new state, `undo()`/`redo()` to navigate the timeline, and checkpoint methods like `createCheckpoint()` and `restoreCheckpoint()`. When you push new state after undoing, the component automatically prunes forward history to match standard editor behavior. This prevents accessing unreachable redo states while saving storage space.

Checkpoints are stored separately from timeline nodes, ensuring they persist even when nodes get pruned due to capacity limits or branching. Restoring a checkpoint creates a new undoable node rather than jumping back in time, protecting the restored state from future pruning operations. You can configure global or per-prefix capacity limits using `maxNodesPerScope` to control storage usage across different types of content.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Timeline is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-timeline)
- [GitHub repository](https://github.com/MeshanKhosla/convex-timeline)
- [Live demo](https://todo-timeline.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-timeline)
- [Convex documentation](https://docs.convex.dev)