Documentation · npm package · Quick start · Core exports · Contributing

snappycart

snappycart is a headless React cart package for teams that want full control over cart UX without building cart state from scratch.

It gives you the core cart engine, optional UI components, and a clean integration path, so you can move faster without getting locked into a heavy commerce platform.

Where to go next

New to snappycart?

• Why snappycart exists
• What you get out of the box
• Who snappycart is built for

Ready to use it?

• Install the package
• Build your first cart flow
• Explore the docs
• See the core exports

Want to work on the repo?

• Understand the repo structure
• Contribute
• Review the license

Why snappycart?

Most cart solutions are either too basic or too opinionated.

snappycart gives you the core cart engine and UI building blocks, so you can ship your own cart UX without fighting a framework.

• Headless by default: bring your own UI, or use the included drawer and cart icon
• Type-safe: first-class TypeScript types and predictable APIs
• Composable: works with different React app architectures, from small SPAs to larger storefronts
• Focused: solves cart state cleanly without dragging in a full commerce platform
• Built to grow: structured for future extensions without forcing a rewrite

Features

• cart primitives: addItem, removeItem, increment, decrement, setQuantity, clear
• React context and hook: CartProvider, useCart
• optional UI components: CartDrawer, CartIcon
• flexible product model with support for custom metadata
• derived cart values like totalItems and subtotal

Core exports

| Export | Type | Purpose | | --- | --- | --- | | CartProvider | Provider | Wraps your app with cart state | | useCart | Hook | Access cart actions and derived state | | CartDrawer | UI component | Optional ready-made cart drawer | | CartIcon | UI component | Optional cart trigger |

Who it is for

| Audience | Why snappycart fits | | --- | --- | | React developers | Add cart functionality without adopting a full commerce platform | | Frontend engineers | Keep full control over UI while reusing solid cart state logic | | Product teams | Ship custom cart flows faster with a lightweight foundation | | Contributors | Improve the package, tests, demo app, or docs in an open repo |

📦 Installation

For package consumers:

npm install snappycart

To use the provided styles:

import "snappycart/styles.css";

Quick Start

1. Wrap your app with CartProvider

import { CartProvider } from "snappycart";

export function App() {
    return (
        <CartProvider>
            <Storefront />
        </CartProvider>
    );
}

2. Add products to the cart with useCart

import { useCart } from "snappycart";

export function AddToCartButton() {
    const { addItem } = useCart();

    return (
        <button
            onClick={() =>
                addItem(
                    {
                        id: "sku_123",
                        name: "Coffee Beans",
                        price: 12.99,
                        imageUrl: "/images/coffee-beans.jpg",
                    },
                    1
                )
            }
        >
            Add to cart
        </button>
    );
}

3. Use the optional cart UI

import { useState } from "react";
import { CartDrawer, CartIcon, useCart } from "snappycart";
import "snappycart/styles.css";

export function Storefront() {
    const [open, setOpen] = useState(false);
    const { totalItems } = useCart();

    return (
        <>
            <CartIcon onClick={() => setOpen(true)} />
            <CartDrawer
                open={open}
                onClose={() => setOpen(false)}
                title={`Your cart (${totalItems})`}
            />
        </>
    );
}

4. Access cart state anywhere

import { useCart } from "snappycart";

export function CartSummary() {
    const { items, subtotal, totalItems, clear } = useCart();

    return (
        <section>
            <p>Total items: {totalItems}</p>
            <p>Subtotal: £{subtotal.toFixed(2)}</p>
            <button onClick={clear}>Clear cart</button>

            <ul>
                {items.map((item) => (
                    <li key={item.product.id}>
                        {item.product.name} × {item.quantity}
                    </li>
                ))}
            </ul>
        </section>
    );
}

Documentation

Explore the docs for setup, usage, and UI customization:

📂 Getting Started ⤴

📂 Theming ⤴

For contribution workflow and repository-specific guidance, see CONTRIBUTING.md.

Repository structure

This repository is a workspace monorepo. Not every folder matters to every contributor.

Folder guide

• packages/snappycart
  The publishable npm package. This is the main folder for developers working on snappycart itself.

• apps/demo
  Demo app for testing and showcasing the package in a real UI.

• apps/documentation
  Documentation site source. Most package users do not need this folder.

• cypress
  Cypress testing setup and support files.

• playwright
  Playwright testing setup.

• .github/workflows
  CI and automation workflows.

snappycart/
├── apps/
│   ├── demo/
│   └── documentation/
├── packages/
│   └── snappycart/
├── cypress/
├── playwright/
├── .github/
│   └── workflows/
├── CONTRIBUTING.md
├── README.md
├── SECURITY.md
└── package.json

Quick orientation

If you are using snappycart in your own app, the main thing you care about is:

packages/snappycart

If you are contributing to docs, go to:

apps/documentation

If you are contributing tests, you will mostly care about:

• cypress
• playwright
• packages/snappycart
• apps/demo

Contributing

snappycart is developed in the open, and contributions are welcome.

You can contribute through:

• bug fixes
• test coverage
• docs improvements
• package enhancements
• demo improvements
• CI and workflow polish

Start here:

Your first pull request ↗

GitHub Issues ↗

Good first issues ↗

Contributing guide ↗

Security policy ↗

If you cloned the repository locally for development, install dependencies from the root and build the workspaces before working across the repo:

npm install
npm run build

You can then either work from the repo root with workspace commands, or move into a specific workspace and run that folder’s local scripts.

License

snappycart is MIT licensed ↗