Getting Started

Prerequisites

React 18+ project with Tailwind CSS v4
shadcn/ui configured in your project

Installation

Install a map using the shadcn CLI. Here we'll use the USA map as an example, but the same command works for any map. This pulls the component directly into your project — no npm package, no version lock.

bash

npx shadcn@latest add @shadcnmaps/usa

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.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'

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 RegionId } from '@/components/shadcnmaps/maps/usa'

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

  return (
    <div>
      <p>{selected ? `Selected: ${selected}` : 'Click a state'}</p>
      <USAMap
        onRegionClick={({ region }) =>
          setSelected((prev) =>
            prev === region.id ? null : (region.id as RegionId)
          )
        }
      />
    </div>
  )
}

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