# HTML > Allows you put DOM elements in your Tres.js scene. This component allows you to project HTML content to any object in your scene. TresJS will automatically update the position of the HTML content to match the position of the object in the scene. 🚀 Works seamlessly with both **PerspectiveCamera** and **OrthographicCamera** — the active camera is automatically detected by the `` component. ## Usage ```vue ``` ## Occlusion By default, the HTML content will be visible through other objects in the scene. You can use the `occlude` prop to make the HTML content occlude other objects in the scene. Html can be hidden behind one or more objects in your scene using the `occlude` prop. ```vue ``` If `occlude`, then `` will be hidden by any objects that pass in front of its position.
Demo code ```html

Move camera

 ```
You can also choose which object or objects should occlude the HTML content by passing either a single object ref or an array of object refs to the `occlude` prop: ### Single occluder ```vue ```
Demo code ```html

Move camera

 ```
### Multiple occluders ```vue ``` OR ```vue ``` In the demo below, a `v-for` loop generates multiple spheres around the cube. All resulting **Mesh** instances are collected into an array and passed to the **occlude** prop, allowing each sphere to occlude the HTML content. This demo also uses the **on-occlude** event, which is triggered whenever the occlusion state changes. Here, the event updates a **reactive value** to control element styles — for example, toggling between *light* and *dark* themes.
Demo code ```html

Move camera

 ```
### Blending Occlusion `` can hide behind geometry as if it was part of the 3D scene using this mode. It can be enabled by using "blending" as the occlude prop. ```vue ``` The **demo below ⬇️** *(left black example)* shows a **basic usage example**.
Demo code ```vue ```
## Custom Geometry By default, when using `occlude="blending"`, occlusion works correctly only with **rectangular HTML elements** (using a `PlaneGeometry`). For *non-rectangular content*, you can use the **geometry** prop to provide a matching custom geometry. In the **demo above ⬆️** *(middle yellow example)*, a [`CircleGeometry`](https://threejs.org/docs/#api/en/geometries/CircleGeometry) is used as a **custom geometry**. - The `geometry` prop only defines the **occlusion shape** in 3D and does not modify your HTML content. - You can provide any [`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry), for example to simulate **CSS-like styles** such as `border-radius` using a rounded rectangle or squircle geometry (see [`RoundedRectangle / Squircle geometry`](https://discourse.threejs.org/t/roundedrectangle-squircle/28645) for example). ### Custom Material You can also assign material properties to the HTML content using the `material` prop. In the **demo above ⬆️** *(right red example)*, a **custom material** is used with shadow. The `material` prop is only available when `occlude="blending"` is **enabled**. Enable shadows using the **castShadow** and **receiveShadow** props. Shadows are supported **only** when using a **custom material**. By default, shadows do **not** work with *MeshBasicMaterial* or *ShaderMaterial*.
## Using `` The native Vue [``](https://vuejs.org/guide/built-ins/transition) component works seamlessly with ``. This means you can **animate** how your projected HTML content *enters* and *leaves* the scene, exactly as you would in a regular Vue application. All **standard interactions** are supported just like on a regular HTML element — **hover effects**, **events**, and *any kind of DOM interaction* are fully possible.
Demo code ```vue ```
### Using `iframes` You can achieve pretty cool results with the `Html` component by using iframes. For example, you can use an iframe to display a YouTube video in your scene or a webpage with a 3D model.
Demo code ```html ```
The demos use `:z-index-range="[28, 0]"` simply to ensure the HTML elements stay below the documentation header (which uses `z-index: 30`). **This value is for the docs only — you can ignore it or adjust it as needed.** ## Props
Prop Description Default
as Wrapping HTML element . 'div'
wrapperClass The className of the wrapping element. element.
prepend Projects content behind the canvas. false
center Adds a transform: translate(-50%, -50%) .
➡️ Ignored in transform mode. 		false
fullscreen Aligns to the upper-left corner and fills the screen.
➡️ Ignored in transform mode. 		false
distanceFactor Children are scaled by this factor and also by distance to a PerspectiveCamera , or zoom when using an OrthographicCamera .
zIndexRange Defines the Z-order range . [16777271, 0]
portal Reference to a target container (for rendering into a different DOM node). container.
transform If true , applies matrix3d transformations — the element appears as if it is inside the 3D scene. false
sprite Renders as a sprite .
➡️ Only in transform mode. 		false
calculatePosition Callback function to override the default positioning logic.
Type: (object: Object3D, camera: Camera, size: { width: number; height: number }) => [number, number, number]
Receives the related 3D object, the active camera, and the current viewport size, and must return [x, y, z] pixel coordinates for placing the HTML element.
➡️ Ignored in transform mode. 		Default calculatePosition
occlude Enables occlusion. Possible values:
- true → Occlusion against all scene objects
- Ref[] → Occlusion is enabled only against the specified objects.
- 'blending' → Uses a blending-based occlusion method (CSS-like depth blending).
geometry Custom geometry to be used. PlaneGeometry
material Custom shader material used for the occlusion mesh.
Only applies when occlude="blending" is enabled (an occlusion mesh is created).
Ignored in raycast occlusion modes ( true , object refs).
transparentMaterial Enables transparent rendering for the occlusion material.
Only applies when occlude="blending" creates an occlusion mesh.
Ignored in raycast occlusion modes ( true , object refs). 		false
## Events
Event Description
onOcclude Called when the occlusion state changes.
## Exposed properties
Property Type Description
instance Ref Reference to the root used by .
isVisible Ref Reactive value that indicates whether the HTML content is currently visible or occluded .
occlusionMesh Ref Reference to the occlusion mesh created when occlude="blending" is enabled . Used internally for geometry-based occlusion.
## Caveats - ✨ When using ****, if the `` component is **overlapping** or **inside a 3D object**, it will be considered **occluded** and therefore **hidden**. To avoid this, **adjust the position** of the `` component in your scene. - 🎨 When using ****, the HTML content is no longer **selectable** because it is rendered **behind the canvas**. This is required to achieve the blending effect. - ⚙️ When using a **custom material** with occlusion in `blending` mode, there are a few important requirements to ensure the HTML content renders correctly ⬇️
See more information 1. If you provide your own material, it must be **transparent** (`transparent: true`) with an **opacity < 1**. 2. If you are not providing a custom material, enable **transparentMaterial** so the internal shader becomes transparent. 3. The occlusion mesh requires a **fully transparent canvas background**; otherwise, thin borders or halo artifacts may appear. 4. To compensate for the transparent canvas, you may **reapply your previous clear-color as a CSS background** on the `html`, `body`, or a wrapper `div`.
- 🔶 When using **transparentMaterial**, overlapping `` elements (especially multiple `occlude="blending"` instances) may cause **z-index or depth-order artifacts**. This happens because the occlusion mesh uses transparency in the WebGL layer while the DOM element uses CSS stacking order. - 🔵 To avoid thin border artifacts when using `occlude="blending"`, make sure your `` is fully transparent:```vue ```
Prop Description Default
as Wrapping html element. 'div'
wrapperClass The className of the wrapping element.
prepend Project content behind the canvas. false
center Adds a -50%/-50% CSS transform. Ignored in transform mode false
fullscreen Aligns to the upper-left corner, fills the screen. Ignored in transform mode false
distanceFactor Children will be scaled by this factor, and also by distance to a PerspectiveCamera / zoom by an OrthographicCamera.
zIndexRange Z-order range. [16777271, 0]
portal Reference to target container.
transform If true, applies matrix3d transformations. false
sprite Renders as sprite, but only in transform mode. false
calculatePosition Override default positioning function. Ignored in transform mode
occlude Can be true , Ref[] , 'raycast' , or 'blending' . True occludes the entire scene.
geometry Custom geometry to be use PlaneGeometry
material Custom shader material to be use
## Events
Event Description
onOcclude Called when the occlusion state changes.