Accessible, scrollable tab navigation bar component with optional URL synchronization, overflow scroll shadows, and support for both controlled and URL-driven active tab state.
## Key Components
### `TabNavigation`
The primary exported component that renders a horizontal scrollable tab strip. Supports two operating modes:
- **Controlled mode** — driven by `activeTab` / `onTabChange` props
- **URL sync mode** — reads/writes the active tab from search params (e.g. `?tab=overview`), enabling deep linking and browser back/forward navigation
### `TabItem`
Interface describing each tab entry:
| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | ✅ | Unique identifier used in state and URL |
| `label` | `string` | ✅ | Visible tab text |
| `icon` | `SVGComponent` | ❌ | Icon rendered beside the label |
| `indicator` | `'success' \| 'warning' \| 'error'` | ❌ | Status badge dot |
| `component` | `ComponentType` | ❌ | Optional content component reference |
### `TabNavigationUrlSyncOptions`
Configuration object for URL synchronization:
- `paramName` — query param name (default: `'tab'`)
- `replaceState` — use `history.replace` instead of `push` (default: `true`)
## Usage Example
```typescript
// Controlled mode
// URL sync mode with render prop
{(activeTab) => }
// Render prop with the pending flag. The tab BODY is deferred
// (`useDeferredValue`), so the underline moves instantly while the body keeps
// showing the previous tab until the new one is ready — no Suspense-fallback
// flash. `isStale` is true during that window; mark the body so stale data
// doesn't read as fresh data.
{(activeTab, { isStale }) => (
)}
// Stretched tabs with forced gradients
```
## Notes
- Horizontal mouse wheel scrolling is intercepted and normalized across deltaMode variants (pixel, line, page)
- On mount, the active tab snaps instantly into view (`auto`); subsequent changes scroll smoothly
- Left/right fade gradients appear automatically on overflow, or can be forced via `showLeftGradient` / `showRightGradient`
- Source: [`tab-navigation.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tab-navigation.tsx)