<kaleidr-map>, the element

<kaleidr-map> is the declarative way to mount a Kaleidr product. You write the element with attributes, and it mounts itself when it enters the document and tears itself down when it leaves. It is defined by kaleidr.js, so the page must load that script.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

The element is a thin wrapper: it turns its attributes into options and calls Kaleidr.mount on itself. Anything the element can do, Kaleidr.mount can do. The reverse is not true: the element cannot take a live map object, and it does not give you the handle.

Use the element when	Use Kaleidr.mount when
The embed is static markup.	You need the handle, for setCamera, setStyle, setTheme or destroy.
A CMS or template writes the HTML.	You attach chat to your own map, which needs the map option.
You want removal from the document to clean up for you.	A framework controls when things mount and unmount.

Attributes

Attribute names are kebab-case. The matching mount options are camelCase.

Attribute	Mount option	Products	Required	Default	Observed after mount	Description
product	product	all	yes	none	no	chat, viewer, editor or tile.
publishable-key	publishableKey	chat, editor, tile	yes, except chat on a published map	none	no	Your kld_pk_… key. Not used by viewer.
share-id	shareId	viewer, chat	viewer: yes	none	no	Viewer: the published map's id. Chat with no key: the published map that provides the chat.
map-id	mapId	viewer	no	none	no	Alias of share-id.
style-id	styleId	tile, editor	recommended on tile	the organization's default basemap; on editor, then kaleidr-morning	no	A basemap style id or a style URL.
map-target	mapTarget	chat	no	none	no	A CSS selector for a <kaleidr-map> viewer or tile element the assistant should drive.
contained	contained	chat	no	off	no	Docks the panel inside this element. The element must be positioned and sized.
lang	lang	chat	no	the page's <html lang> when that is a well-formed language tag, otherwise English	no	The language the panel answers in, as a BCP 47 tag such as en, ko or pt-BR. See Chat language.
chat-title	title	chat	no	the panel's own title	no	The title in the panel's header. The attribute is chat-title, not title: title on an element is HTML's hover tooltip.
placeholder	placeholder	chat	no	the panel's own placeholder	no	The placeholder text of the panel's input.
layout	layout	viewer	no	map	no	bar mounts the chat bar, which also reads chat-title, placeholder, theme and lang, with its own defaults: see the viewer options.
prompt	prompt	viewer	no	none	no	A question to put to the map's Kaleidr AI when the map opens; on a chat bar, the field's pre-filled text.
prompt-param	promptParam	viewer	no	none	no	Reads prompt from that query parameter of the page's URL, when the visitor came from a page of the same origin.
prompts	prompts	viewer chat bar	no	none	no	Example questions, separated by |.
accent	accent	viewer chat bar	no	#2da84a	no	A CSS color.
results-url	resultsUrl	viewer chat bar	no	none	no	Sends visitors to that page with ?q=<question>.
center	center	viewer, tile, editor	no	product default	yes	"longitude,latitude", for example "-0.1276,51.5072".
zoom	zoom	viewer, tile, editor	no	product default	yes	A number. At mount, viewer and tile use it only together with center.
pitch	pitch	viewer, tile, editor	no	product default	yes	Tilt in degrees.
bearing	bearing	viewer, tile, editor	no	product default	yes	Rotation in degrees.
theme	theme	chat, editor	no	none	yes (acts on chat only)	A JSON object string. Chat: CSS custom properties. Editor: the 17 theme keys.
flag	enabled	all	no	none	no	Per-element arm of the enable gate.
base	base	all	no	https://cdn.kaleidr.com	no	Origin product bundles load from. Honored only for the Kaleidr CDN (https://cdn.kaleidr.com), the origin kaleidr.js was loaded from, or the page's own origin; any other value is ignored with a console warning. See the base override.
viewer-base	viewerBase	viewer, tile	no	https://map-embed.kaleidr.com	no	Origin the iframe loads from.
api-base	apiBase	chat, editor, tile	no	https://api.kaleidr.com/inference-api	no	Where the session exchange and product requests go. Must include /inference-api.
tile-base	tileBase	editor	no	https://tile.kaleidr.com	no	Host that style ids are resolved against.

api-key is a deprecated alias of publishable-key. The four …-base attributes are for testing against another deployment and are not needed in production.

Boolean attributes

flag and contained are read as booleans:

Written as	Read as
contained (no value), contained=""	true
"true", "1", "yes", "on"	true
"false", "0", "no", "off"	false
attribute absent	not set
anything else	ignored, with a console warning

Words are matched without regard to case or surrounding spaces, so a template that renders flag="False" still switches the element off. Because a bare attribute is true, a template that can render an empty value (flag="") switches the element on. Render an explicit false.

Number and camera attributes

zoom, pitch and bearing are parsed as numbers. center is two numbers separated by a comma, longitude first. A value that does not parse is ignored without a message, and the product's default is used.

Attributes after mount

The element reads its attributes once, when it enters the document. After that, only five are observed:

Attribute changed	viewer	tile	editor	chat
center, zoom, pitch, bearing	The map jumps to the new camera.	The map jumps to the new camera.	The map jumps to the new camera.	Console warning. Nothing happens.
theme	Console warning.	Console warning.	Console warning. The editor reads its theme at mount only.	The panel is restyled.
Any other attribute	Nothing.	Nothing.	Nothing.	Nothing.

A camera change made through attributes is never animated. For an animated move, mount with Kaleidr.mount and call handle.setCamera({ …, duration: 800 }).

When one camera attribute changes, the element sends all the camera attributes it currently has. Changing only zoom on an element that also has center re-applies that center.

To change share-id, style-id, publishable-key, product, flag, contained, lang, chat-title or placeholder, replace the element: remove it and insert a new one with the new attributes. On a tile, handle.setStyle swaps the style without a remount, but only for a map mounted with Kaleidr.mount.

// Show a different published map in the same place.
const old = document.querySelector('kaleidr-map');
const next = old.cloneNode(false);
next.setAttribute('share-id', 'ANOTHER_MAP_ID');
old.replaceWith(next);

Lifecycle

Event	What the element does
It enters the document	Reads its attributes and mounts. For chat, editor and tile this starts a session exchange.
It is in the document before kaleidr.js loads	Nothing until the script loads. Then it mounts.
It leaves the document	Destroys the mount: removes what it added and stops the session renewals.
It enters the document again	Reads its attributes again and mounts again, with a new session exchange.
It is moved to another parent	Leaves and enters: destroyed, then mounted again.
Its product is missing or not one of the four	Logs [kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" and does not mount. Setting product afterwards does nothing.

What follows from this:

• Set attributes before you insert the element. If you build the element in JavaScript, set every attribute and then append it. An element appended first mounts with what it had at that moment.

  const el = document.createElement('kaleidr-map');
  el.setAttribute('product', 'tile');
  el.setAttribute('publishable-key', 'kld_pk_live_…');
  el.setAttribute('style-id', 'kaleidr-night');
  el.style.cssText = 'display:block; height:480px';
  document.getElementById('slot').appendChild(el); // mounts here

• A remount is not free. A tile element that mounts again counts another map load. An editor element that mounts again has lost its edits. A chat element that mounts again starts a new conversation. Code that re-creates or re-orders DOM nodes, such as a list re-render in a framework, can trigger this without you noticing. See Framework integration.

• A hidden element still mounts. display:none does not delay the mount, so a tile in a closed tab panel still starts a session.

• The element shows its children until a map replaces them. Anything you put inside the element is displayed. A viewer or tile mount replaces the element's contents with its iframe once the product has loaded, so children there work as a loading placeholder, and stay as a fallback when the mount fails or is held by the enable gate. A chat or editor element never removes them. Leave the element empty unless you want that.

Sizing

<kaleidr-map> is display:block by default, so a height on it applies:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="height:480px"></kaleidr-map>

Three things to know about that default:

• Your own display always wins. An inline style, any rule in your stylesheet and the hidden attribute all override it. If your CSS sets display:inline on the element, height stops applying.
• It needs nothing from your Content Security Policy. The default is not delivered as a <style> tag or a style attribute, so it works under a policy without 'unsafe-inline'.
• Safari before 16.4 does not get it. In a browser that cannot apply the default, the element stays inline and ignores width and height. The snippets in these docs keep display:block in the style attribute for that reason: it is harmless where the default applies and it is what sizes the element where it does not.

So the form used throughout these docs is:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

or, once for the whole site:

kaleidr-map { display: block; height: 480px; }

Product	Sizing behavior
viewer, tile	The iframe is 100% of the element's width. Its height is 100% of the element when the element has a height at mount time, otherwise a fixed 500 pixels. The mount sets position:relative (when the element has no inline position) and overflow:hidden on the element.
editor	The editor is 100% of the element's width and height. With no height, nothing is visible.
chat	Without contained, the panel is a fixed window at the top-left of the viewport and the element's size does not matter. With contained, the panel docks inside the element, which needs position:relative (or another positioning) and a size.

The 500-pixel fallback is decided once, at mount. An element that had no height at that moment keeps a 500-pixel iframe even if you size it later.

If your Content Security Policy forbids inline style attributes, size the element from a stylesheet. The element's own block default is not affected by that policy.

Handle matrix

The element does not expose a handle. To call these methods, mount with Kaleidr.mount, which returns one.

Method	chat	viewer	editor	tile
destroy()	yes	yes	yes	yes
setCamera(camera)	not supported	yes	yes	yes
setTheme(theme)	yes	not supported	not supported	not supported
setStyle(style)	not supported	not supported	not supported	yes
send(text)	not supported	yes	not supported	not supported

Every handle has all four methods. A method marked "not supported" does nothing when called and logs a console warning. It does not throw. That behavior is part of the /embed/v1 contract.

Per product:

• chat: setTheme restyles the panel. setCamera is not supported because the chat does not own a map: the assistant moves the map it is attached to when it answers, and you move your own map with your map library's API.
• viewer: setCamera moves the published map.
• editor: setCamera moves the editor's map. The theme and the basemap are fixed at mount.
• tile: setCamera moves the map, and setStyle swaps the basemap in place.

setCamera takes { center, zoom, pitch, bearing, duration }. All fields are optional, center is [longitude, latitude], and duration is in milliseconds. The full description is in kaleidr.js.

Chat and map-target

A chat can drive two kinds of map:

• Your own map (Mapbox GL JS, MapLibre GL JS, Google Maps, Leaflet). A map object cannot be written in an attribute, so this needs Kaleidr.mount with the map option. See the Chat reference.

• A Kaleidr viewer or tile element on the same page. Point map-target at it with a CSS selector:

  <div style="position:relative">
    <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
                 style-id="kaleidr-morning"
                 style="display:block; height:480px"></kaleidr-map>
  
    <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
                 map-target="#basemap"
                 style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
  </div>

  The order of the two elements does not matter. The chat looks up its target when it needs it.

With neither map nor map-target, the chat is a panel with no map.

The wrapper and the chat element's styles place the panel over the map. Each declaration is explained in Theming and layout. Chat on a published map is covered in Chat on a published map.

Console messages

Message	Meaning
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	product is missing or misspelled. The element does not mount.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).	flag or contained has a value outside the accepted words. The message names the attribute: flag="…" or contained="…".
[kaleidr] base "<value>" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.	The base attribute names an origin that is not accepted. The product still loads, from the default CDN.
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	The element is held by its flag. Replace the element without it to mount.
[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …	A camera attribute changed on a chat element.
[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …	The theme attribute changed on a viewer, tile or editor element.

Mount failures are logged as [kaleidr:<product>] …. They are listed in kaleidr.js.

Not available

• Events. The element dispatches no DOM events.
• Properties or methods. The element has no setCamera, no handle property and no ready promise.
• Re-reading attributes. Apart from the five observed ones, a change after mount is ignored.

Related

• kaleidr.js, the loader
• Framework integration
• Viewer, Tile, Editor and Chat references