# Semantic Cache Status Bar

Semantic Cache Status Bar [#semantic-cache-status-bar]

The **Semantic Cache Status Bar** complements the Cache Badge: a compact toolbar row for `useSemanticCache` showing entry count, hit-rate %, an icon-only clear-cache button (when entries > 0), and an enable/disable toggle (with a spinner while the embedding model loads). It pairs with a per-message `CachedAnnotation` ("Cached (38ms)"). Distinct from the Cache Badge (model-download cache), this surfaces semantic-cache hits on responses.

Preview [#preview]

```tsx
'use client';

import { useState } from 'react';

import {
  CachedAnnotation,
  SemanticCacheStatusBar,
} from '@/components/semantic-cache-status-bar';

/**
 * Demo for SemanticCacheStatusBar / CachedAnnotation. Toggle and clear are wired
 * to local state; in your app bind `stats` to useSemanticCache().stats and
 * `onClear` to cache.clear().
 */
export default function SemanticCacheStatusBarDemo() {
  const [enabled, setEnabled] = useState(true);
  const [entries, setEntries] = useState(24);

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <SemanticCacheStatusBar
        stats={{ entries, hitRate: 0.62 }}
        enabled={enabled}
        onToggle={setEnabled}
        onClear={() => setEntries(0)}
      />
      <div className="flex items-center gap-2 rounded-lg border border-border bg-card px-3 py-2 text-sm">
        <span className="flex-1">Paris is the capital of France.</span>
        <CachedAnnotation latencyMs={38} />
      </div>
    </div>
  );
}
```

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/semantic-cache-status-bar
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the cache `stats` you pass and emits clear/toggle — works with any backend. Recommended producer: `useSemanticCache` (backed by `createSemanticCache`) from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `semantic-cache-status-bar.tsx` — `SemanticCacheStatusBar` + `CachedAnnotation`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SemanticCacheStatusBar**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` | `object` | — | **Required.** Live cache stats (from `useSemanticCache`). |
| `enabled` | `boolean` | — | **Required.** Whether the cache is enabled. |
| `isLoading` | `boolean` | — | Whether the embedding model is still loading (shows a spinner). |
| `onToggle` | `function` | — | Fired when the enable/disable toggle is flipped. |
| `onClear` | `function` | — | Fired when the clear-cache button is pressed (shown when entries > 0). |

**CacheStatsLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` | `number` | — | **Required.** Number of cached entries. |
| `hitRate` | `number` | — | **Required.** Hit rate in the 0–1 range. |

Examples [#examples]

Bound to useSemanticCache [#bound-to-usesemanticcache]

```tsx
const { stats, cache } = useSemanticCache({ embeddingModel });
<SemanticCacheStatusBar
  stats={stats}
  enabled={enabled}
  isLoading={!cache}
  onToggle={setEnabled}
  onClear={() => cache?.clear()}
/>
```

Customization [#customization]

The hit-rate reads `stats.hitRate` (0–1) and renders as a percentage. The toggle is a themed switch; show the spinner via `isLoading` while the embedding model loads. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.