# shadcnmaps — Full Documentation

> Interactive SVG map components for React. No dependencies, pure Tailwind.

---

# Getting Started

## Prerequisites

- React 18+
- Next.js 13+ (app router) or any React project with Tailwind CSS v4
- [shadcn/ui](https://ui.shadcn.com) configured in your project

## Installation

Install the USA map using the shadcn CLI. This pulls the component directly into your project — no npm package, no version lock.

```bash
npx shadcn add https://shadcnmaps.com/r/usa-map.json
```

This installs the following files:

| File | Description |
| --- | --- |
| `components/shadcnmaps/map.tsx` | Core SVG renderer |
| `components/shadcnmaps/map-context.tsx` | Shared state context |
| `components/shadcnmaps/map-region.tsx` | Individual region (path) |
| `components/shadcnmaps/map-tooltip.tsx` | Hover/click tooltip |
| `components/shadcnmaps/map-marker.tsx` | SVG marker overlay |
| `components/shadcnmaps/map-listbox.tsx` | Accessible keyboard listbox |
| `components/shadcnmaps/types.ts` | Shared TypeScript types |
| `components/shadcnmaps/maps/usa-map.tsx` | `USAMap` component |
| `components/shadcnmaps/map-data/usa.ts` | SVG path data for all 50 states + DC |

## Basic usage

```tsx
import { USAMap } from '@/components/shadcnmaps/maps/usa-map'

export default function Page() {
  return <USAMap />
}
```

That's it. The map is interactive out of the box — hover states, tooltips, and full keyboard navigation are included by default.

## Build a state selector

This example builds a clickable state selector that highlights the selected state and shows a tooltip with the state name.

```tsx
'use client'

import { useState } from 'react'
import { USAMap, type StateId } from '@/components/shadcnmaps/maps/usa-map'

export function StatePicker() {
  const [selected, setSelected] = useState<StateId | null>(null)

  return (
    <div>
      <p>{selected ? `Selected: ${selected}` : 'Click a state'}</p>
      <USAMap
        regions={
          selected ? [{ id: selected, className: 'fill-map-region-selected' }] : []
        }
        onRegionClick={({ region }) =>
          setSelected((prev) => (prev === region.id ? null : region.id as StateId))
        }
        renderTooltip={(region) => <span>{region.name}</span>}
      />
    </div>
  )
}
```

### How it works

- `regions` — per-region overrides. Pass `className` to change fill color, `tooltipContent` for custom tooltip content, or any `MapRegionData` field.
- `onRegionClick` — fired on click and on keyboard Enter/Space. Receives `{ region, nativeEvent }`.
- `renderTooltip` — renders a tooltip that follows the cursor. Receives the full `MapRegionData` for the hovered/clicked region.
- `fill-map-region-selected` — a Tailwind color class backed by the `--map-region-selected` CSS variable. Swap it for any color class.

### Keyboard navigation

The map is fully keyboard accessible — no extra setup needed. Tab to focus the map, then use arrow keys to navigate between states, Enter/Space to select, and Escape to clear.

## Next steps

- [Theming](/overview/theming) — customize colors with CSS variables
- [USA Map](/maps/usa-map) — full props reference and examples

---

# API Reference

All pre-configured map components (USAMap, WorldMap, etc.) share a common set of props inherited from the core `Map` component. Each map may also expose map-specific props documented on its own page.

## Map Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `regions` | `RegionOverride[]` | `[]` | Per-region overrides for className, tooltipContent, disabled, and display fields. |
| `disabledRegions` | `string[]` | `[]` | Region IDs to mark as non-interactive. |
| `onRegionClick` | `(event: RegionEvent) => void` | — | Fired on click or keyboard Enter/Space. |
| `onRegionEnter` | `(event: RegionEvent) => void` | — | Fired on mouse enter or focus. |
| `onRegionLeave` | `(event: RegionEvent) => void` | — | Fired on mouse leave or blur. |
| `onMarkerClick` | `(event: MarkerEvent) => void` | — | Fired when a marker is clicked. |
| `markers` | `MapMarkerData[]` | `[]` | SVG markers to overlay on the map. |
| `renderTooltip` | `(region: MapRegionData) => ReactNode` | — | Custom tooltip renderer. Falls back to region name. |
| `showLabels` | `boolean` | `true` | Show abbreviation labels inside each region. |
| `showTooltips` | `boolean` | `true` | Enable tooltip on hover and click. |
| `className` | `string` | — | Class applied to the root SVG element. |
| `aria-label` | `string` | `Map name` | Accessible label for the map. |

## Types

### RegionEvent

```typescript
interface RegionEvent {
  region: MapRegionData
  nativeEvent: MouseEvent | TouchEvent | FocusEvent | KeyboardEvent
}
```

### MarkerEvent

```typescript
interface MarkerEvent {
  id: string
  nativeEvent: MouseEvent | TouchEvent | FocusEvent | KeyboardEvent
}
```

### RegionOverride

```typescript
interface RegionOverride {
  id: string
  name?: string
  abbreviation?: string
  labelX?: number
  labelY?: number
  metadata?: Record<string, unknown>
  className?: string
  labelClassName?: string
  tooltipContent?: ReactNode
  disabled?: boolean
}
```

### MapRegionData

```typescript
interface MapRegionData {
  id: string
  name: string
  path: string
  abbreviation?: string
  labelX?: number
  labelY?: number
  metadata?: Record<string, unknown>
}
```

### MapMarkerData

```typescript
interface MapMarkerData {
  id: string
  x: number
  y: number
  content: ReactNode
  tooltipContent?: ReactNode
  label?: string
  disabled?: boolean
}
```

---

# Theming

All map colors are driven by CSS variables, registered as Tailwind theme colors. Override them globally in your CSS or inline per-component via `className`.

## CSS variables

These variables are injected into your project when you install any map component.

### Region colors

| Variable | Tailwind class | Description |
| --- | --- | --- |
| `--map-region` | `fill-map-region` | Default region fill |
| `--map-region-hover` | `fill-map-region-hover` | Fill on hover |
| `--map-region-selected` | `fill-map-region-selected` | Fill when selected |
| `--map-region-disabled` | `fill-map-region-disabled` | Fill when disabled |

### Stroke colors

| Variable | Tailwind class | Description |
| --- | --- | --- |
| `--map-region-stroke` | `stroke-map-region-stroke` | Default border between regions |
| `--map-region-stroke-hover` | `stroke-map-region-stroke-hover` | Border on hover |
| `--map-region-focus-ring` | `stroke-map-region-focus-ring` | Keyboard focus ring color |

### Label colors

| Variable | Tailwind class | Description |
| --- | --- | --- |
| `--map-label` | `text-map-label` | Abbreviation label color |
| `--map-label-hover` | — | Label color on hover |
| `--map-label-selected` | — | Label color when selected |

## Override globally

Add overrides to your `globals.css` after the shadcn import:

```css
:root {
  --map-region: oklch(60% 0.15 145);
  --map-region-hover: oklch(50% 0.18 145);
  --map-region-selected: oklch(45% 0.22 145);
}
```

## Dark mode

Dark mode values are included by default. Override them in the `.dark` selector:

```css
.dark {
  --map-region: oklch(55% 0.12 145);
}
```

## Per-region colors

Pass any Tailwind color class to a region via the `regions` prop:

```tsx
<USAMap
  regions={[
    { id: 'CA', className: 'fill-emerald-500 hover:fill-emerald-600' },
    { id: 'TX', className: 'fill-amber-500 hover:fill-amber-600' },
  ]}
/>
```

## Choropleth pattern

For data-driven coloring, compute `className` dynamically:

```tsx
const regions = data.map(({ id, value }) => ({
  id,
  className: value > threshold ? 'fill-blue-600' : 'fill-blue-200',
}))

<USAMap regions={regions} />
```

---

## Maps

- [USA Map](https://shadcnmaps.com/llms/usa-map.md): Interactive SVG map of the United States with all 50 states and DC. Supports click, hover, keyboard navigation, tooltips, and custom markers.

## Examples

- [Choropleth](https://shadcnmaps.com/llms/choropleth.md): Color-code map regions by data values.
- [Markers](https://shadcnmaps.com/llms/markers.md): Overlay custom SVG markers on the map.
- [Region Click](https://shadcnmaps.com/llms/region-click.md): Respond to region clicks on the map.