diff --git a/docs/api-reference/space/data-layers.md b/docs/api-reference/space/data-layers.md
index 090db45..e53cbb8 100644
--- a/docs/api-reference/space/data-layers.md
+++ b/docs/api-reference/space/data-layers.md
@@ -13,7 +13,10 @@ Some options correspond to generic behaviours that are shared by all interactive
 ```ts
 space.addDataLayer({
   // ...layerDefinition,
-  tooltip?: (dataElement: object) => string,
+  tooltip?: (dataElement: object) => string | HTMLString,
+  tooltipTemplate?: string,
+  tooltipContainerStyle?: string,
+  persistentTooltip?: boolean,
   onClick?: (dataElement: object, event: PointerEvent) => void,
   onHover?: (dataElement: object, event: LimitedPointerEvent) => void,
   onHoverOut?: (dataElement: object, event: LimitedPointerEvent) => void
@@ -21,7 +24,17 @@ space.addDataLayer({
 ```
 
 - `...layerDefinition` - refer to the [overview](./overview#data-layers) page.
-- `tooltip` - _optional_ - is taking the newly hovered data element as argument and should return the content of the tooltip to render. It is called once when the pointer starts to hover a data element. Built-in tooltips are text only, newlines are supported by using [multi-line template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#multi-line_strings). If you need HTML/CSS in your tooltips, check the [custom tooltips example](/examples/custom-tooltips/).
+- `tooltip` - _optional_ - is taking the newly hovered data element as argument and should return the content of the tooltip to render. It is called once when the pointer starts to hover a data element. Built-in tooltips support string and "HTML as string" values.
+  - For string values, newlines are supported by using [multi-line template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#multi-line_strings).
+  - For HTML values, both HTML and CSS are supported, the value will be sanitized to prevent XSS attacks.
+  - If you need complete control over the tooltip content (e.g. for a React component), check the [tooltips example](/examples/tooltips/).
+- `tooltipTemplate` - _optional_ - is a fully featured template string used to generate the tooltip content based on the data for the hovered element.
+  - It is powered by [Handlebars](https://handlebarsjs.com/) and you may refer to the full templating documentation [here](https://handlebarsjs.com/guide/). 
+  - It supports HTML, nested fields access, conditionals, loops, and more.
+  - A custom helper lets you use fallback default values: `{{fallback [my field] 'default value'}}`.
+  - Without this helper, we use `'-'` as a default value for all fields.
+- `tooltipContainerStyle` - _optional_ - lets you override the style of the tooltip container with inline CSS.
+- `persistentTooltip` - _optional_ - set this to `true` to turn tooltips into small cards that are all visible at once instead of on hover. Persistent tooltips are automatically positioned on the center of the data element they're attached to. They disappear when the camera is moving and reappear when it stops. They are only displayed for the top visible level. They only work for data elements with a non null or undefined `id`. _Default value: false_
 - `onClick` - _optional_ - is taking the data element that was clicked as argument, as well as the Javascript [pointer event](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) that triggered the click. It is called each time a click or tap event happens.
 - `onHover` - _optional_ - is taking the newly hovered data element as argument, as well as a limited (due to the rendering engine's internals) "pointer event" that triggered the handler. The limited event only includes the coordinates within the viewer of the pointer at the time when the event was triggered. The handler is called once when the pointer starts to hover a data element.
 - `onHoverOut` - _optional_ - is taking the previously hovered data element as argument, as well as the same limited "pointer event" as for `onHover`. The handler is called once when the pointer stops hovering a data element.
diff --git a/src/pages/examples/custom-tooltips/card.png b/src/pages/examples/custom-tooltips/card.png
deleted file mode 100644
index 6cbb1fa..0000000
Binary files a/src/pages/examples/custom-tooltips/card.png and /dev/null differ
diff --git a/src/pages/examples/index.js b/src/pages/examples/index.js
index f5dbd0f..6e5a364 100644
--- a/src/pages/examples/index.js
+++ b/src/pages/examples/index.js
@@ -32,7 +32,7 @@ import { iot } from './iot'
 import { propertyManagement } from './property-management'
 import { controlledCamera } from './controlled-camera'
 import { seeThroughWalls } from './see-through-walls'
-import { customTooltips } from './custom-tooltips'
+import { tooltipsOptions } from './tooltips'
 import { airQuality } from './air-quality'
 import { embeddedEditor } from './embedded-editor'
 
@@ -46,7 +46,7 @@ const projects = [
   addDataElements,
   stackingPlan,
   warehouseBins,
-  customTooltips,
+  tooltipsOptions,
   controlledCamera,
   seeThroughWalls,
   embeddedEditor
diff --git a/src/pages/examples/tooltips/card.png b/src/pages/examples/tooltips/card.png
new file mode 100644
index 0000000..889f88a
Binary files /dev/null and b/src/pages/examples/tooltips/card.png differ
diff --git a/src/pages/examples/custom-tooltips/index.js b/src/pages/examples/tooltips/index.js
similarity index 58%
rename from src/pages/examples/custom-tooltips/index.js
rename to src/pages/examples/tooltips/index.js
index 34b84b8..61c0386 100644
--- a/src/pages/examples/custom-tooltips/index.js
+++ b/src/pages/examples/tooltips/index.js
@@ -4,11 +4,11 @@ import StackblitzProject from '../../../components/StackblitzProject'
 
 import { FEATURES } from '../_categories'
 
-export const customTooltips = {
-  slug: 'custom-tooltips',
-  title: 'Custom tooltips',
+export const tooltipsOptions = {
+  slug: 'tooltips',
+  title: 'All tooltips options',
   category: FEATURES,
-  description: `Programmatically control HTML elements to overlay data elements. This gives you 100% control over your tooltips. And you can react to camera movements.`,
+  description: `Get an overview of all the ways to use tooltips, from simple text tooltips to fully controlled custom elements. And even through programmatic control.`,
   stackblitzProjects: [
     // {
     //   lang: 'Javascript',
@@ -22,8 +22,8 @@ export const customTooltips = {
     // },
     {
       lang: 'React',
-      id: 'smplr-custom-tooltips',
-      openFile: 'SpaceViewer.tsx',
+      id: 'smplr-tooltips',
+      openFile: 'index.tsx',
       default: true
     }
   ],
@@ -31,5 +31,5 @@ export const customTooltips = {
 }
 
 export default function () {
-  return <StackblitzProject project={customTooltips} />
+  return <StackblitzProject project={tooltipsOptions} />
 }