Open the Map Builder. The interactive USA map loads automatically in the centre of the screen. The left sidebar contains all the customisation panels — each one can be expanded by clicking its header.
To begin, simply click any state on the map to select it. A chip appears at the top of the sidebar showing the selected state and its current fill colour. From there you can set a colour, add information, or configure what happens when a visitor clicks that state in the final published map.
The top bar gives you quick access to global actions.
| Control | What it does |
|---|---|
| Search box | Type a state name or two-letter code (e.g. CA or California) to select that state without clicking the map. |
| Undo Ctrl+Z | Reverses your last action. Multiple levels of history are kept. |
| Redo Ctrl+Y | Re-applies an undone action. |
| Reset | Resets all states to their default colours and clears all customisations. You will be asked to confirm before anything is wiped. |
| Preview | Opens a full-screen preview of how the map will look and behave for an end user — hover effects, tooltips, and click actions all work in Preview mode. |
| Export | Opens the Export pricing modal so you can download your finished map. |
This panel appears automatically when a state is selected. It lets you attach rich data to each state that will be shown inside the interactive tooltip or detail card when a visitor interacts with the map.
| Field | Description |
|---|---|
| Capital | The state capital city, shown in the tooltip and detail card. |
| Population | Any population figure or statistic you want to display. |
| Custom fields | Click + Add custom field to add any number of key/value pairs (e.g. "GDP", "Governor", "Unemployment rate"). They appear in both the tooltip and the state card. |
| Notes | A free-text description or any note about the state. |
| Image URL | A URL to any image (state flag, photo, chart). Displayed at the top of the detail card and optionally in the tooltip. |
| Link URL | A URL that the detail card's "Learn more" button will point to. |
| Link text | The label for the link button (defaults to "Learn more"). |
The On click radio buttons control what happens when a visitor clicks this state in the published map:
Click View state card at the bottom of the panel to preview exactly what the detail modal will look like for the selected state.
The Colour panel controls the fill colour of the currently selected state (or all states at once).
A row of preset swatches is shown for instant one-click styling. Click All themes › to open the full Themes panel, which contains a larger library of curated colour schemes — clicking any theme applies it to every state at once.
A grid of preset colours for quick individual state colouring. Click any swatch to apply it to the selected state immediately.
As you use the custom colour picker, your most recently used colours appear here for quick reuse.
Use the colour wheel or type a hex value directly (e.g. #e63946), then click Apply to set the colour on the selected state.
In addition to a solid fill you can apply a repeating pattern over the state's colour:
Use the Size slider to control the density of the pattern.
Apply to all sets every state to the currently active colour and pattern. Reset all removes any custom colour from every state, returning them to the default fill.
The tooltip is the small pop-up that appears when a visitor hovers over a state in the published map.
Uncheck Show tooltip to hide it entirely for all states.
| Setting | Description |
|---|---|
| Background | The tooltip background colour. |
| Text | The text colour inside the tooltip. |
| Border | Toggle the border on/off and set its colour. |
| Opacity | How transparent the tooltip is (0 = invisible, 100 = fully opaque). |
| Radius | Corner rounding of the tooltip box in pixels. |
| Shadow | Drop shadow size in pixels. |
Toggle individual checkboxes to control which pieces of state information appear inside the tooltip: Capital, Population, Notes, Custom fields, and Image / Flag.
Controls the visual effect applied to a state when the user's cursor moves over it.
| Setting | Description |
|---|---|
| Fill | The highlight colour on hover. Enable Auto to have the builder calculate a slightly lighter or darker shade of each state's current colour automatically. |
| Border | Colour of the state outline that appears on hover. |
| Border width | Thickness of the hover border in pixels. |
| Shadow | Drop shadow distance, X offset, Y offset, blur radius, and colour — combine these for a glow or lift effect. |
Sets the colour and appearance of the area behind the map SVG itself.
| Setting | Description |
|---|---|
| Colour | The background fill colour of the map container. |
| Opacity | Set to 0 to make the background fully transparent — useful if you want the map to sit on top of a coloured section of your page. |
| Map shadow | A soft drop shadow cast by the entire map area, giving it a floating appearance. |
| Shadow colour | The colour of that outer shadow. |
Adds a title and optional subtitle displayed directly on the map, above the states.
| Setting | Description |
|---|---|
| Title | Main heading text (e.g. "US Election Results 2024"). |
| Subtitle | Smaller secondary line below the title, useful for a source credit or date. |
| Align | Left, Center, or Right alignment of the title block. |
| Colour | Text colour of both title and subtitle. |
| Visible | Toggle to show or hide the title overlay without deleting the text. |
Controls the thin lines drawn between states (the state borders on the SVG map).
| Setting | Description |
|---|---|
| Colour | Colour of all state border lines. |
| Width | Stroke thickness from 0 (invisible) to 3. Use 0 to remove borders entirely for a borderless look. |
Overlays text labels directly on each state shape. Labels can show the state abbreviation, the full name, or any custom value you choose.
| Setting | Description |
|---|---|
| Show labels | Tick to enable labels on all states. |
| Type | Code shows the two-letter abbreviation (CA, TX…). Full name shows the complete state name. |
| Value | Override the label for the currently selected state with any custom text (e.g. a percentage, a number, or any short string). Click Clear to remove the override for that state. |
| Size | Font size of the labels in pixels. |
| Color | Text colour for all labels. |
| Font | Font family: Sans-serif, Arial, Helvetica, Georgia (serif), or Courier (mono). |
| Bold / Outline | Toggle bold weight or a thin outline stroke around the letters for legibility on dark backgrounds. |
Instead of typing values one state at a time, paste a CSV or JSON block into the Import Values text area and click Apply. The format is a two-column CSV where the first column is the two-letter state code and the second column is the label value:
NJ,56%
MA,45%
CA,38%
TX,61%Or as a JSON object:
{"NJ":"56%","MA":"45%","CA":"38%","TX":"61%"}You can also click Example › to load a pre-filled sample, or use Load file to import a .csv, .json, or .txt file from your computer. Click Clear all to remove all custom label values at once.
Automatically colours all states based on a dataset — ideal for choropleth maps (e.g. election results, population density, unemployment rates).
Paste a two-column CSV or a JSON object mapping state codes to numeric values, then click Parse:
AL,5
CA,120
TX,98
NY,87Or as JSON:
{"AL":5,"CA":120,"TX":98,"NY":87}You can also click Load file to read a file from your computer. Click Example › to see sample data in both numeric and percentage formats.
After parsing data, set your gradient scale:
Click Apply Scale to colour every state according to its data value and the gradient you have defined. Click Clear to remove the imported data.
Your work is held in memory while the page is open. To preserve it across sessions, use the Project panel.
.json file to your computer containing all state colours, fill patterns, info fields, label overrides, and every style setting..json file and restores your map exactly as it was.History controls are also described here: use Ctrl+Z / Ctrl+Y or the arrow buttons in the toolbar to step backwards and forwards through your recent changes.
When your map is ready, open the Export Map panel in the sidebar and click Export Map ›. A modal appears with three export options:
| Format | Price | Best for |
|---|---|---|
| Interactive HTML Map | $5 | Embedding a fully interactive map (hover, tooltips, click actions) on any website. |
| 3 Interactive HTML Maps | $10 | If you need to export multiple different maps — credits never expire. |
| Static Map Image | $1 | A high-quality PNG & JPEG snapshot for presentations, reports, or print. No interactivity. |
Checkout is handled securely by Lemon Squeezy. After payment you will receive your download link directly from them.
The exported .html file is fully self-contained. All map data, styles, and JavaScript are baked into that single file — it makes no external network requests and requires no server-side processing. You can host or embed it anywhere.
Upload the file to any web host, then drop an <iframe> into your page pointing to its URL:
<iframe
src="https://yourdomain.com/my-map.html"
width="100%"
height="600"
style="border:none; border-radius:8px;"
loading="lazy"
title="Interactive USA Map"
></iframe>Adjust height to suit your layout. The map is fully responsive and will scale to fill the iframe's width.
Because the file is self-contained, you can also paste its entire contents directly into a page's HTML instead of using an iframe. Open the .html file in a text editor, copy everything inside the <body> tag, and paste it into your page where you want the map to appear. Make sure your page does not already define conflicting CSS variable names.
Any static file host will work. Some free and easy options:
.html file to a GitHub repository, enable Pages in the repository settings, and share the generated URL (e.g. https://yourusername.github.io/my-repo/my-map.html).
To make the iframe fill its container while preserving the map's aspect ratio, use a CSS aspect-ratio wrapper:
<div style="position:relative; width:100%; aspect-ratio:16/10;">
<iframe
src="https://yourdomain.com/my-map.html"
style="position:absolute; inset:0; width:100%; height:100%; border:none;"
title="Interactive USA Map"
></iframe>
</div>16/11 or 3 / 2 in CSS will give a near-perfect fit without letterboxing.
You can also open the .html file directly in a browser from your desktop (no server needed) by double-clicking it. This is useful for a quick check before uploading. All interactivity works in this mode.