Styling

<mapvx-website> renders in your page’s regular DOM, not in a Shadow DOM, and it ships a required global stylesheet, styles.css. This page covers what you can customize (two colors, the font and the card grid) and how the component’s CSS and your page’s CSS affect each other.

CSS variables

:root {
  --mapvx-secondary-orange: #b41500; /* default #EE5845 */
  --mapvx-secondary-blue: #053a96; /* default #2C57A0 */
}

To change the colors at runtime, set the variables on the root element. The interface updates right away; the route line and the route icon take the new color the next time a route is drawn.

document.documentElement.style.setProperty('--mapvx-secondary-orange', '#b41500')

These two variables are the only supported theming API. Keep in mind:

• The “Deals + Events” banners on a place profile take their text and border color from the color in the first style attribute of the banner content, or use #EE5845 when there is none. They do not follow --mapvx-secondary-orange.
• There is no dark theme. The component paints a white background and dark text whatever the visitor’s color scheme is.
• styles.css also defines more than 100 --definitions-* custom properties on :root (colors, font shorthands, a shadow), and the card grid uses --card-width and --card-gap. These are internal: they can be renamed or removed in any release. To change the grid, use the card-width and rows-per-page attributes instead.

Fonts

The component loads no web fonts: styles.css has no @font-face rules and no font URLs. Its text uses 'Open Sans', sans-serif, so it renders in Open Sans only when your page loads that font or the visitor’s system has it; otherwise the browser’s generic sans-serif is used.

You have two options:

• Load Open Sans yourself. The component uses the weights 400, 600 and 700. For example, from Google Fonts (or self-host the same files):

  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700&display=swap"
    rel="stylesheet"
  />

• Use your page’s font. With inherit-font-family="true" the component uses the font-family it inherits from <mapvx-website> and its ancestors:

  <style>
    mapvx-website {
      display: block;
      width: 100%;
      font-family: 'Inter', system-ui, sans-serif;
    }
  </style>
   
  <mapvx-website
    api-key="YOUR_API_KEY"
    institution-id="YOUR_INSTITUTION_ID"
    inherit-font-family="true"
  ></mapvx-website>

  Only the exact string "true" turns it on; a bare inherit-font-family attribute counts as false. See boolean attributes.

Either way, only the font family changes. Font sizes and weights stay as designed and are set in pixels, so your root font-size does not change the component’s text size. Map labels are drawn by the map renderer with their own glyphs, so neither option changes them. Icons are inline SVG and need no icon font.

Text inside many of the component’s buttons, including the place cards, the Back buttons and the route controls, has no font family of its own. Browsers give buttons their own default font (for example Arial in Chrome on Windows), so that text shows neither Open Sans nor your page’s font, with or without inherit-font-family, unless your CSS already sets font-family: inherit on buttons, as many CSS resets do. To make it follow the component’s font, add:

mapvx-website button {
  font-family: inherit;
}

Sizing

mapvx-website {
  display: block;
  width: 100%;
}

• Width. The component fills the width of its container. <mapvx-website> itself has no default styles, so it is display: inline. Give it display: block and, inside a flex row or a grid track sized to its content, an explicit width: the component measures its own width for its layout, and without one it can collapse to zero width.
• Height. The height comes from the content, so you do not need to set one. Do not give the element a fixed height such as 100vh: the map does not stretch to fill it, and content taller than that height overflows the element’s box.

The map areas have these heights, depending on the component’s width:

The grid view has no map; its height depends on the number of rows and the card size.

Opening a place profile smoothly scrolls your page so the top of <mapvx-website> sits at the top of the viewport. If your page has a fixed or sticky header, add scroll-margin-top so the header does not cover the component:

mapvx-website {
  display: block;
  width: 100%;
  scroll-margin-top: 80px; /* height of your fixed header */
}

Responsive behavior

The layout adapts to the width of the component, not the width of the viewport: it uses container queries  on its own container. A 600px column on a desktop screen gets the narrow layout, and a full-width component on a large tablet gets the wide one.

The number of cards per page is computed when the list is rendered. It is not recalculated when the window is resized, only when the list is shown again (for example after switching between grid and map view, or after returning from a place) or when card-width or rows-per-page changes. Test the component at the width it will have on your page.

Layout options

Two attributes shape the card grid. Both can be changed at runtime; parsing details are in numeric attributes.

<mapvx-website
  api-key="YOUR_API_KEY"
  institution-id="YOUR_INSTITUTION_ID"
  card-width="280"
  rows-per-page="3"
></mapvx-website>

Cards per page are floor((list width + gap) / (card width + gap)) × rows-per-page, where the gap between columns is 13px in the grid view and 8px in the map view. For example, a 1,200px wide grid with card-width="280" fits 4 columns of about 290px each, so rows-per-page="3" shows 12 cards per page. With the defaults the same grid shows 4 columns and 8 cards per page.

• The same settings apply to the grid view, the card list in map view and the search results.
• In map view on components wider than 1024px, the list takes half the width, so each row fits fewer cards and there are more pages.
• card-width replaces both defaults, including the 170px narrow one, so a large value can leave a single column on phones.
• At 640px or less, the map view shows the cards of the current page in one horizontally scrolling row.

Style isolation

The component does not use Shadow DOM. Its markup is part of your page, inside <mapvx-website>.

• The component’s styles stay inside. They are injected at runtime as <style> elements in <head> and scoped with generated attributes, so they do not match your elements. If your site sends a Content Security Policy, these tags need 'unsafe-inline' or a nonce: see Security and privacy.
• Your styles reach inside. Rules with element or universal selectors (button, input, a, img, h1 to h3, *) match the component’s elements too. The component’s own rules usually win for the properties they set, because a class plus the scoping attribute is more specific than a bare element selector. Every other property comes from your rule, and more specific or !important rules override the component. Inherited properties such as color, letter-spacing or text-transform also flow in from ancestors wherever the component does not set them.

Typical sources are CSS resets and frameworks (*, ::before, ::after with box-sizing) and site-wide button, input, a or heading styles. Scope those rules so they skip the component with :not():

/* Before: also restyles every button inside <mapvx-website> */
button {
  border-radius: 999px;
  text-transform: uppercase;
}
 
/* After: skips everything inside <mapvx-website> */
button:not(mapvx-website *) {
  border-radius: 999px;
  text-transform: uppercase;
}
 
/* Universal resets: :where() keeps the specificity at zero, like the original * */
:where(*:not(mapvx-website *)),
:where(*:not(mapvx-website *))::before,
:where(*:not(mapvx-website *))::after {
  box-sizing: border-box;
}

Or scope your content styles to a wrapper and place the component outside it:

<main class="article">
  <!-- Your content styles target .article h3, .article a, .article button -->
</main>
 
<section class="directory">
  <mapvx-website api-key="YOUR_API_KEY" institution-id="YOUR_INSTITUTION_ID"></mapvx-website>
</section>

Do not style the component’s internals. Its class names, DOM structure and --definitions-* tokens are internal and can change between releases; for example, the map marker wrapper class changed from .lazarillo-marker to .mapvx-marker in 1.0.0 (see migration from 0.x). The supported customization is the two CSS variables and the attributes, plus the button font-family rule under Fonts.

Keep <mapvx-website> in the main document rather than inside a shadow root of your own: the rules in styles.css do not reach into shadow trees. If your styles still show up inside the component, see Troubleshooting.

Global styles

styles.css is required (see package contents) and applies to the whole document, not only to the component. It contains the :root design tokens, the MapLibre GL styles, the MapVX map SDK styles, the Font Awesome 7 core CSS, and the marker and banner rules. It has no html, body or bare element rules, so it does not restyle your typography. These parts can affect the rest of your page:

/* .store-locator-map is the container of your own map */
.store-locator-map .maplibregl-control-container {
  display: block;
}

More things to avoid on your page:

• The ids map, current-location-marker, route-icon and ids ending in -marker: the component creates elements with these ids, so a #map rule in your CSS also styles the component’s map.
• Custom properties that start with --definitions-.
• A second copy of Font Awesome’s core CSS with a different version. Besides styles.css, the component injects Font Awesome’s core CSS at runtime in a <style id="fa-auto-css"> tag, which it inserts before the first <style> or <link> in <head>. When your page loads another Font Awesome version, both versions’ rules apply to the same class names, and the one that comes last wins where they differ. See Troubleshooting.

For a MapLibre map of your own that lost its controls, see also Troubleshooting.