Options

render(), mount(), update() and the React component all take the same options. Every one is optional.

render("inbox", {
  state: "loading",
  value: 0.4,
  crew: true,
});

state#

render("laptop", { state: "error" });

An unknown state throws. See states.

value#

render("wall", { state: "loading", value: rows.length / total });

Only loading builds by it. Values outside 0 to 1 are clamped. A value that is not a finite number counts as no value. See value.

rev#

render("door-frame", { state: "changed", rev: "2.4.1" });

Only changed draws it. Numbers are turned into strings. See rev.

figure#

render("ramp", { state: "loading", value: 0.5, figure: { value: 1.8, unit: "MB" } });

Only the figures listed with a measure below draw it. See figure.

crew#

render("stair", { state: "loading", value: 0.5, crew: true });

Draws the workers for the state: a carrier on the stair while it goes up, a sitter on top when it is done. See workers.

lettered#

render("door-frame", { state: "error", lettered: "Not here" });

A word or two, lettered in the library's own drawn capitals. Some figures keep a place for it, and four of them (the door frame, the ramp, the phone and the camera) point an arrow from the word to the work. The rest letter it in their top left corner.

The pen knows A to Z, the space and the full stop. Lower case is lettered as capitals, and anything else (digits, punctuation, other scripts) is left out of the drawing.

Keep it to about ten letters. The lettering is drawn at one size, and "Page not found anywhere" is already two thirds of a figure's width.

title#

render("inbox", { state: "empty", title: "No messages yet" });

The accessible name, written to the drawing's <title> and aria-label. With no title it is the figure's title and state: "Inbox, empty", "Wall, loading, 40 percent", "Laptop, something went wrong". See accessibility.

decorative#

render("bridge", { state: "success", decorative: true });

For a drawing next to text that already says what happened. It gets aria-hidden="true" and no title.

dir#

render("tin-can-line", { state: "error", dir: "rtl" });

Mirrors the drawing so it faces the way your page reads. Lettering and dimension figures still read left to right. See right to left.

color, crewColor and paperColor#

render("inbox", { state: "loading", crew: true, color: "#c2410c", crewColor: "#1c1917" });

<Ostraca name="inbox" state="loading" crew color="var(--accent-600)" crewColor="var(--text)" />

The colours of one drawing: color for the thing and everything drawn on it, crewColor for the workers, paperColor for the surface it sits on. Any CSS colour works, including var() and light-dark(). Each one sets its --ostraca-* token on that drawing only, so leave it out and the stylesheet's colour stays. Change one with update() or a new prop and the drawing takes it at once. Theming says which colours work.

Figures#

<!-- figures:start --> 34 figures on 8 shelves. Every figure draws all six states. Error says how it goes wrong: it leans off a plumb line or sags under a string. Measure is what figure carries, for the figures that draw one; the example is a sample, so pass your own.

Messages#

Inboxes, notifications, email and comments. Most products show their first empty screen here.

Files#

Keeping, finding, charting and throwing away.

People#

Teams, profiles, sign in and the first achievement.

Money#

Payments, balances, savings and receipts.

Shopping#

Carts, orders, shop fronts and food on the way.

Time#

Calendars, countdowns, reminders and time away.

Devices#

The computer and phone an app runs on, and what it asks of them.

Site#

The building site the library started from. Six subjects for lists, onboarding, integrations, live connections, missing pages and uploads.

Figures of your own join this list once you pass them to define(). The agent skill draws them. <!-- figures:end -->