# Vessel

A glass of liquid as a gauge. It pours in when the value rises, sloshes when the page jolts and rings when tapped, lit like lab glassware in a photograph.

Object · With a Pass · https://tactileui.dev/objects/vessel

> The code and styling for this object come with the Pass. Sign in if you have one. Sign in: https://tactileui.dev/auth/sign-in The price: https://tactileui.dev/pricing

## Anatomy

Shallow water heightfield, Volume conserving flux, Fixed step symplectic, Inertial forcing, Poured stream, Rising bubbles, Baked per pixel shading, Beer lambert liquid, Volume graduations, Sleeping loop, Synthesised tap tone, Progressive bake, Backdrop watch, Dark field lighting, Element tracked progress, Nucleated fizz

## Usage notes

Show a quantity as something a visitor already understands with their hands: how full a glass is. Reading progress that fills as the page is read, an upload that pours in, a fundraising goal, a level: the number is exact and announced, the liquid makes it felt.

## Options

| Option | Type | Description |
| - | - | - |
| shape | enum | A tumbler, a round-bottomed flask in its cork ring, a reagent bottle, a test tube: standing, or lying across the page as a progress bar. |
| liquid | enum | Honey is slow and heavy; mercury is a mirror with small, tight waves. |
| level | number | The value, as a share of the glass by volume. Changing it pours in or drains. |
| driver | enum | Value: you set it (setLevel). Scroll: it fills as the page is read, and sloshes when the scroll jolts. |
| viscosity | number | How quickly a slosh dies away. |
| waveSpeed | number | Wave speed |
| slosh | number | How hard a scroll jolt or a shove of the glass throws the liquid. |
| bubbles | boolean | Carried in by a pour, stirred up by a hard slosh. |
| graduations | boolean | Graduations |
| readout | boolean | The value written on the glass’s marking patch. |
| tint | enum | Glass |
| finish | enum | The enamel the graduations and patch are printed in. Auto prints in the page’s own markings (lit from within on Phosphor and Night); without them, bone on a dark stage and ink on a light one. |
| light | number | 0 is from above, clockwise. |
| size | number | The glass’s height (or its length, lying down). |
| sound | boolean | Synthesised; the note falls as the glass fills. Starts only after a tap. |
| tilt | boolean | On a phone the surface stays level as you tilt it. Asks permission on iOS. |
| intro | boolean | Pour in on first view |
| label | text | The accessible name. Empty uses “Reading progress” or “Level”. |

## Methods

- level
- value
- state
- setLevel
- tap
- fizz
- tiltTo
- update
- destroy

## States

1. **At rest**: The level stands still and flat; the loop is asleep and costs nothing.
2. **First paint**: A half-resolution draft is on screen within a task of the glass being created, resized or reconfigured.
3. **Pouring in**: When the value rises a stream falls from above the rim, lands, dents the surface and carries bubbles down; the level rises only once it has landed, at a pour's rate.
4. **Draining**: When the value falls the level drops at once, smoothly, from below.
5. **Sloshing**: A scroll jolt, or a sideways drag that slides the glass, tilts the effective gravity: the liquid piles against a wall, swings back, and settles.
6. **Tapped**: A tap on the glass sends a ripple across from where it landed, reflecting off the walls; with the tap tone on, the glass rings a note that falls as it fills.
7. **Tilted**: With device tilt on, a phone leaned in the hand keeps the surface level while the glass leans; that slope is a rest state and the loop sleeps on it.
8. **Scroll-driven**: The level is the reading progress of the page or a scroller; the value and its announcement follow the scroll exactly.
9. **Fizzing**: While a host asks (fizz), bubbles rise in trains off a handful of sites on the floor (processing, brewing) and the loop sleeps once fizz(0) has let the last one pop.
10. **Backdrop changed**: A theme switch or a new stage colour is noticed on the ancestors (or given as the backdrop option); the glass re-bakes for it, lit dark-field on a dark stage (bright edges, a luminous seam where the liquid meets the glass) and its markings reprint in bone or ink.
11. **Lying down**: The tube held across the page as a bar: its column slumps toward the bottom of the bore and leans further while it advances; a scroll jolt sloshes it across the bore.
12. **Off screen or hidden**: The loop pauses; a returning tab advances one clamped frame, so nothing is launched.
13. **Reduced motion**: The true level with a still, flat surface on first paint: no pour, no stream, no bubbles, no frames requested. It repaints only when the value changes.

## How it works

Original. Canvas 2D only; the glass is shaded per pixel into sprites when its size or options change, so no image ships.