Koala UI

Document Chain

Pro

The documents behind one purchase, side by side: request, order, receipt, invoice and payment, each with its status, linked to the next.

  1. Done
    €4,820.00
  2. Done
    €4,820.00
  3. Done
    3 of 3 lines
  4. Exception
    €4,905.60
  5. Not created yet
    Payment Not scheduled

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add document-chain

Usage#

The chain draws the documents you give it and fetches nothing. Map each stage of your lineage to a step, and put a connector between two steps. With Next.js, pass Link through asChild so moving between documents stays client side.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Get the code

Have a license? Unlock it here

Anatomy#

import {  DocumentChain,  DocumentChainStep,  DocumentChainLink,  DocumentChainLabel,  DocumentChainId,  DocumentChainMeta,  DocumentChainCount,  DocumentChainConnector,} from "@/components/ui/document-chain"

Compact#

variant="compact" fits the chain on one small line for a table row or a page header. The id stands in for the type, which a screen reader still hears, and the meta drops out.

SupplierAmountDocuments
Ferretería Nadal€4,905.60
  1. Done
    Order PO-02231
  2. Done
    Receipt GR-000883 receipts
  3. Exception
    Invoice FV-0193
  4. Not created yet
    Payment
Papelera Montseny€612.40
  1. Done
    Order PO-02240
  2. Done
    Receipt GR-00091
  3. Done
    Invoice FV-0201
  4. In progress
    Payment PAY-0577
Transports Ebre€1,180.00
  1. Done
    Order PO-02218
  2. Not created yet
    Receipt
  3. Blocked
    Invoice FV-0188
  4. Not created yet
    Payment

Vertical#

orientation="vertical" stacks the chain for a side panel, with the connectors running down the status marks.

  1. Done
    €4,820.00
  2. Done
    €4,820.00
  3. Done
    3 of 3 lines
  4. Exception
    €4,905.60
  5. Not created yet
    Payment Not scheduled

States#

A step carries one of six states. current is the stage the purchase is waiting on; the document you are looking at is selected, a separate prop, so the two never compete.

  1. Done
    Request PR-00412Approved
  2. In progress
    Order PO-02231Sent to supplier
  3. Pending
    Receipt GR-00090Expected Nov 6
  4. Exception
    Invoice FV-0193Price over PO
  5. Blocked
    Payment PAY-0581IBAN changed
  6. Not created yet
    Credit note None yet

Connectors#

A connector is solid once the step before it is done and dashed while it is not. Mark a link that does not hold, such as an invoice that matches no receipt, as broken.

Linked
  1. Done
    Order PO-02231
  2. Done
    Invoice FV-0193
Expected
  1. Done
    Order PO-02231
  2. Pending
    Invoice FV-0193
Mismatch
  1. Done
    Order PO-02231
  2. Exception
    Invoice FV-0193

Several documents#

A partial delivery leaves several receipts, a split bill several invoices. Show the count, and wrap it in a DropdownMenuTrigger to list them.

  1. Done
    Order PO-02240€9,310.00
  2. In progress
    Invoice FV-0199€3,102.00 of €9,310.00

API reference#

DocumentChain

The ordered list that holds the steps and connectors. On a narrow screen a horizontal chain scrolls sideways with faded edges instead of overflowing the page. Every part accepts className, merged last.

PropTypeDefaultDescription
variant"default" | "compact""default"Stacked label, id and meta, or a single small line for table rows and headers.
orientation"horizontal" | "vertical""horizontal"A strip, or a column for side panels.
aria-labelstring"Document chain"Names the list for a screen reader. Say whose documents they are.
Data attributeDescription
data-variantdefault or compact.
data-orientationhorizontal or vertical.

DocumentChainStep

One stage of the chain. Draws its status mark and lays out whatever parts you put in it.

PropTypeDefaultDescription
status"done" | "current" | "pending" | "exception" | "blocked" | "missing""pending"The state of the stage. missing is a stage with no document yet, drawn as a quiet placeholder.
selectedbooleanfalseThe document on screen. Gets a faint chip and sets aria-current="page" on its link.
statusLabelstring-The status as read by a screen reader. Use it to translate.
Data attributeDescription
data-statusThe stage status.
data-selectedPresent on the selected step.

DocumentChainLink

Makes the whole step clickable. Wrap the label and id in it; the status is attached as its description.

PropTypeDefaultDescription
asChildbooleanfalseRenders your own element, such as a Next.js Link or a button, instead of an a.

DocumentChainLabel

The document type, such as Order or Invoice. In the compact variant it is read out but hidden when the step has an id.

DocumentChainId

The document number, in tabular numerals.

DocumentChainMeta

A short fact, such as an amount or a date. Hidden in the compact variant.

DocumentChainCount

How many documents the stage holds. On its own it is text; put it in a DropdownMenuTrigger or PopoverTrigger with asChild and it becomes a button that lists them.

PropTypeDefaultDescription
count*number-The number of documents.
childrenReactNode-What they are, such as "receipts". Read out but hidden in the compact variant.

DocumentChainConnector

The line between two steps. Hidden from screen readers.

PropTypeDefaultDescription
status"complete" | "pending" | "broken"-Solid, dashed, or dashed in red with a break. When unset it is solid after a done step and dashed after any other.
Data attributeDescription
data-statusThe connector status, when set.

FAQ#

No. It draws any lineage of documents: quote, contract and renewal, or claim, assessment and payout. The type names are yours.