# Liquid log

> The card is the vessel you log into: tap + and a drop falls into a live surface, the ripple runs to the walls, then the level rises.

Water and habit trackers are usually a ring and a plus button, and a tap just makes the ring jump. Liquid log has no gauge: the card is the vessel. Liquid fills it from the bottom with a live surface that sways gently while the card is on screen, a pale meniscus, and the body drawn in fine engraved lines that deepen toward the bottom. Tap + and the amount leaves the button as a drop that stretches with its speed, arcs up and falls into the surface: a splash kicks up, the ripple runs out to the card’s walls and back, a few bubbles rise, and only then does the level rise and the total roll, so you see your tap land. Wherever the liquid covers the words they turn light, cut exactly along the moving waterline, so the total never gets lost. Hold + and drops keep coming, faster and faster; the whole hold is one log to undo. Past the goal the card is full and a deeper liquid rises from the bottom for the second lap. Undo lifts a drop out of the surface and drops it back into the button. Run a pointer along the waterline and it leaves a small wake. The total is yours: pass value and add in onLog, or leave it uncontrolled; the level settles on your value once the drops are in, so a log your server refuses simply drains away.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/liquid-log.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/liquid-log
- Registry item (source): https://hairlineui.com/r/liquid-log.json

## Usage

```tsx
import { LiquidLog } from "@/components/liquid-log";

<LiquidLog title="Water" goal={2000} step={250} unit="ml" defaultValue={750} />
```

## Saved to your database

Controlled: add the amount optimistically and post it; undo posts a negative entry.

```tsx
"use client";
import * as React from "react";
import { Droplet } from "lucide-react";
import { LiquidLog } from "@/components/liquid-log";

export function WaterCard({ initial }: { initial: number }) {
  const [ml, setMl] = React.useState(initial);
  const save = (amount: number) =>
    fetch("/api/water", { method: "POST", body: JSON.stringify({ amount }) }).then((r) => {
      if (!r.ok) {
        setMl((v) => v - amount);
        throw new Error("Not saved");
      }
    });
  return (
    <LiquidLog
      title="Water"
      icon={<Droplet />}
      value={ml}
      goal={2000}
      step={250}
      unit="ml"
      onLog={(amount) => {
        setMl((v) => v + amount);
        return save(amount);
      }}
      onUndo={(amount) => {
        setMl((v) => v - amount);
        return save(-amount);
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `goal` | `number` | – | The day’s target; the card is full at it. |
| `value / defaultValue` | `number` | `0` | The total, controlled or not. |
| `step` | `number` | `goal / 8` | What one tap logs. |
| `onLog` | `(amount) => Promise<unknown> \| void` | – | Called for every tap and every drop of a hold. Throw or reject to refuse it. |
| `onUndo` | `(amount) => Promise<unknown> \| void` | – | Called with the last log’s amount. A controlled card without it hides Undo. |
| `title / icon / unit` | `string / ReactNode / string` | – | The label, a small icon, and the unit after the figures. |
| `color` | `string` | `"var(--chart-1)"` | The liquid: any CSS colour. Words under it pick light or dark from it. |
| `format / locales` | `Intl.NumberFormatOptions / string` | – | How the figures are written. |

## States

- **arrive**: In view for the first time, the liquid rises from the bottom to the value on a soft spring and the figures roll up.
- **log**: A drop is tossed from the + (520ms) and falls into the surface left of the middle, a different spot each time. On impact the surface is struck and the ripple travels to the walls and reflects; three splash drops kick up and fall back, three bubbles rise; then the level rises and the total and percent roll.
- **read**: The words are drawn twice: in ink above the waterline and light below it, each clipped to the same moving curve every frame.
- **pour**: Holding + logs again after 460ms, then every 320ms getting 14% quicker down to 140ms; release ends the hold, which is one entry in Undo.
- **over**: At 100% the card is full and the surface flattens against the top; a deeper liquid then rises from the bottom.
- **undo**: Undo opens at the top right after the first log. Pressed, the surface lifts and a drop arcs back into the button while the level falls.
- **sway**: While the card is on screen the still surface swells slowly (two long waves, under 3px), so the liquid never reads as a flat block; it stops off screen.
- **wake**: A mouse moving along the waterline pushes small ripples ahead of it.
- **refused**: If onLog throws or rejects, the button shakes and the level settles back on your value.
- **reduced motion**: No drops, waves, sway or bubbles: the level and figures change in place.

## What it handles

A ring with a plus button jumps when you tap, so you can’t tell whether the tap counted, and the figure sits beside a picture instead of in it.

- **You see the tap land**: A drop falls into the surface, the ripple runs to the walls, then the level rises.
- **The figure lives in it**: Words under the waterline turn light, cut along the moving surface.
- **Hold to pour**: Holding + keeps the drops coming, faster and faster; the hold is one log to undo.
- **Past the goal**: The card fills and a deeper liquid rises from the bottom for the second lap.
- **Your total stays the truth**: Controlled or not; it settles on your value, so a refused log drains away.
- **Keyboard and screen readers**: A named + button, a meter with the total and goal in words, each log announced.

## Replaces

a progress ring, a water tracker, a habit tracker, a stepper, an undo button, a goal gauge

## Where it fits

- **Water and habit trackers**: Glasses of water, cups of coffee, minutes of reading toward the day’s goal.
- **Savings jars**: Putting money aside toward a target in fixed steps.
- **Fundraising**: Adding a donation or pledge toward a campaign goal.
- **Credits and fuel**: Topping up a balance and seeing how full it is.

## Notes

- The + is a button named for what it logs (“Log 250 ml”); Enter and Space log once. The figures are a role="meter" with the total, the goal and the percent in words; the light copy under the waterline is hidden from screen readers; each log and undo is announced politely.
- One canvas draws the liquid, drops, splash and bubbles; the surface is forty springs that pull on their neighbours and reflect at the walls. The loop runs only while the card is on screen (for the sway) or the surface is moving, and the theme’s colours are read again when the theme changes.
- The level is a spring from ui-interaction-motion.ts, which installs with it. Undo lists only this visit’s logs; a hold is one entry.
- Installs Number roll and Text morph. With reduced motion there are no drops or waves and the level changes in place.

License: MIT (https://hairlineui.com/license#components)
