Getting Started

Prerequisites

• React 18+
• Next.js 13+ (app router) or any React project with Tailwind CSS v4
• shadcn/ui 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.

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

This installs the following files:

Basic usage

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.

'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 — customize colors with CSS variables
• USA Map — full props reference and examples