# Liquid Gauge

A quota as liquid in a circle: it rises to its level, sloshes and settles.

Tier: Free

## Installation

```bash
npx shadcn add @fetaui/liquid-gauge
```

## Usage

```tsx
import { LiquidGauge } from '@/components/fetaui/liquid-gauge'

export function Example() {
  return <LiquidGauge used={92.2} total={128} onAction={openStorage} />
}
```

## API

| Prop | Type | Default |
|---|---|---|
| used | number | required |
| total | number | required |
| unit | string | GB |
| label | string | Storage |
| icon | ReactNode | hard drive |
| warnAt | number | 0.9 |
| slosh | boolean | false |
| actionLabel | string | Manage storage |
| urgentActionLabel | string | Free up space |
| onAction | () => void |  |
| animated | boolean | true |

## When to use

- For one quota people check at a glance, like storage.

## When not to use

- For several numbers side by side: use a chart.
- For a task in progress: use Progress.

## Accessibility

- The gauge is a meter with the percent and free space as its text.
- Changes are announced politely.
- Almost full has a Badge and a label, never colour alone.
- The readout swaps to the inverse ink where the liquid covers it, so it reads at any level.

## Motion

- A new value springs the level over 1200 ms.
- The wave grows from 4 to 9 px and settles back while it tilts.
- Digits count to the new percent.
- On Mobile, the wave follows device tilt where the browser allows it. With a mouse, the liquid tips up to 6 degrees toward the pointer and settles when it leaves.
- A press splashes it: the wave kicks to 1.2 times its slosh height and sways back on a spring.
- At rest nothing loops.
- With reduced motion, the level jumps and the wave stays still.