<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# SyncStatus

One line that says where the person's changes are: Saved, Saving…, Offline (kept on this device) or Couldn't save, each with its icon, and Retry while there is a problem. Screen readers hear it only when a problem starts and when it clears, so every save is not narrated. It keeps the height of its longest state, so a change never moves the page. When Retry goes away while it has focus (the save it started is under way), focus moves to the status line, so the person stays where they were rather than at the top of the page.

```tsx
import { SyncStatus } from "@/components/ouro/sync-status/sync-status";
```

## Example

```tsx
<SyncStatus status={navigator.onLine ? (pending ? "saving" : "saved") : "offline"} onRetry={flush} />
```

## Use instead when

- Use `toast()` instead to confirm a single action, and `Alert` for a problem that blocks the page.

## Props

Type: `SyncStatusProps`.

| Prop | Type | Description |
| --- | --- | --- |
| `className` | `string` | Layout only: margins, placement (`mt-3`). Appearance classes warn in development. |
| `labels` | `SyncStatusLabels` | The words for each state. |
| `onRetry` | `(() => void)` | Shows Retry while `offline` or `error`, and is called when it is pressed. |
| `ref` | `Ref<HTMLDivElement>` | Reaches the rendered element. |
| `status` (required) | `"error" \| "saved" \| "saving" \| "offline"` | `saved` once changes reached the server, `saving` while they travel, `offline` while they wait on this device, `error` when the server refused them. |

## Native attributes

Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `online`: Not a prop. Ouro UI says `status`: `<SyncStatus status="offline" />`.
- `state`: Not a prop. Ouro UI says `status`: `<SyncStatus status="saving" />`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: SyncStatus merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

## Types

### `SyncStatusLabels`

The words for each state, for apps in other languages or to say what is saved.

```ts
interface SyncStatusLabels {
  /** Once changes reached the server. @default "Saved" */
  saved?: string | undefined;
  /** While changes travel. @default "Saving…" */
  saving?: string | undefined;
  /** While changes wait on this device. @default "Offline: changes are kept on this device" */
  offline?: string | undefined;
  /** When the server refused the changes. @default "Couldn't save" */
  error?: string | undefined;
  /** The retry button's label. @default "Retry" */
  retry?: string | undefined;
}
```

[^layout-classes]: test:registry/ouro/components/ouro/sync-status/sync-status.test.tsx::SyncStatus > forwards a ref and div attributes, and lets app layout classes win verify:testExists(registry/ouro/components/ouro/sync-status/sync-status.test.tsx::SyncStatus > forwards a ref and div attributes, and lets app layout classes win)