Map Styling

CSS Variables & ::part() Selectors

Use CSS custom properties for quick theming and ::part() selectors for full styling control from the host page.

Overview

Mapsemble exposes two layers of styling customization:

  1. CSS Custom Properties — simple variable overrides for colors, sizes, and spacing. These pierce the Shadow DOM boundary, so they work from any ancestor element.
  2. ::part() selectors — full CSS control over structural elements inside the Shadow DOM. Any CSS property works, no constraints.

Use variables for quick brand-matching. Use ::part() when you need complete control.

CSS Custom Properties

Set these on the embed element or any ancestor. They apply to both iframe and Shadow DOM embeds.

Layout & spacing

Variable Default Description
--mapsemble-gap 1.25rem Gap between cards and layout elements
--mapsemble-outer-padding = --mapsemble-gap Outer container padding
--mapsemble-radius 0.75rem Border radius for cards, filters, and panels
--mapsemble-sheet-collapsed-height 4rem Mobile bottom sheet collapsed height

Colors

Variable Default Description
--mapsemble-button-color #3b82f6 Primary button/accent color
--mapsemble-button-color-hover #2563eb Primary button hover state
--mapsemble-button-color-dark #3b82f6 Button color in dark mode
--mapsemble-button-color-hover-dark #2563eb Button hover in dark mode
--mapsemble-background-color per map Container background color
--mapsemble-background-color-dark per map Container background in dark mode

Filters

Variable Default Description
--mapsemble-filter-active-bg derived from button color Active filter chip background
--mapsemble-filter-active-bg-hover derived from button color Active filter chip hover
--mapsemble-filter-active-text derived from button color Active filter chip text
--mapsemble-filter-active-border = --mapsemble-button-color Active filter chip border
--mapsemble-filter-border-color per map Filter element border color
--mapsemble-filter-border-width per map Filter element border width

The --mapsemble-filter-active-* variables are automatically derived from --mapsemble-button-color via color-mix(). Override them individually to customize active filters independently of the button color.

Pager

Variable Default Description
--mapsemble-pager-size 1.5rem Page button width and height
--mapsemble-pager-radius 9999px (circle) Page button border radius
--mapsemble-pager-bg light gray Inactive button background
--mapsemble-pager-bg-hover slightly darker gray Inactive button hover background
--mapsemble-pager-color currentColor Inactive button text color
--mapsemble-pager-active-bg = --mapsemble-button-color Active page button background
--mapsemble-pager-active-color white Active page button text color

Example: quick theming

<mapsemble-embed style="
    --mapsemble-button-color: #e11d48;
    --mapsemble-radius: 0;
    --mapsemble-pager-radius: 4px;
    --mapsemble-pager-size: 2rem;
"></mapsemble-embed>

::part() selectors

For full CSS control, structural elements expose part attributes. Use ::part() from the host page — any CSS property works, no variable constraints.

Available parts

Part name Element Description
container Map wrapper Outermost map container
map Map viewport Contains the MapLibre canvas
cards Cards wrapper Cards section container
cards-grid Card grid Card grid/list layout
card Card Individual card element
pager Pagination nav Pagination navigation bar
pager-button Page button Any pager button (prev, next, page number)
pager-button-active Active page Currently active page button

The active page button has both pager-button and pager-button-active, so ::part(pager-button) matches all buttons including the active one.

Example: restyle the pager

mapsemble-embed::part(pager) {
    gap: 0.75rem;
}

mapsemble-embed::part(pager-button) {
    width: 2rem;
    height: 2rem;
    border-radius: 4px;
    background: transparent;
    border: 1px solid #d4d4d8;
}

mapsemble-embed::part(pager-button-active) {
    background: var(--mapsemble-button-color);
    border-color: var(--mapsemble-button-color);
    color: white;
}

Example: style cards

mapsemble-embed::part(card) {
    box-shadow: 0 2px 12px rgb(0 0 0 / 0.1);
    border-radius: 12px;
}

mapsemble-embed::part(cards-grid) {
    gap: 2rem;
}

Combining both approaches

Variables and ::part() work together. Use variables for the common settings and ::part() for detailed overrides:

/* Theme color via variable */
mapsemble-embed {
    --mapsemble-button-color: #7c3aed;
}

/* Detailed pager restyle via ::part */
mapsemble-embed::part(pager-button) {
    background: transparent;
    border: 1px solid #d4d4d8;
    font-weight: 400;
}

mapsemble-embed::part(pager-button-active) {
    background: var(--mapsemble-button-color);
    border-color: var(--mapsemble-button-color);
    color: white;
    font-weight: 600;
}

Notes

  • ::part() only works with Shadow DOM embeds (embed: 'shadow' in Mapsemble.init()). Iframe embeds cannot use ::part().
  • CSS custom properties work with both iframe and Shadow DOM embeds.
  • For per-map scoping without Shadow DOM, use the .map-id-<MAP_ID> class on the map wrapper.