WebGL 3D Object
Use When
- A hero, feature block, or product moment needs one strong 3D object.
- The visual should show real geometry, lighting, highlights, and edges.
- A faceted mesh should float or rotate subtly inside a web layout.
- CSS transforms, SVG illusions, or flat gradients are not enough.
Rules
- Use real 3D geometry:
IcosahedronGeometry, DodecahedronGeometry, BoxGeometry, custom BufferGeometry, or a glTF mesh.
- Use a perspective camera so the object has depth and scale.
- Use PBR material:
MeshStandardMaterial or MeshPhysicalMaterial.
- Tune
metalness, roughness, and emissive to match the brand mood.
- Light the object with at least one directional light plus ambient or hemisphere fill.
- Animate transforms only: subtle rotation, bobbing, or parallax.
- Handle resize and dispose geometry/material/renderer on teardown.
HTML And CSS
<div class="webgl-object-shell">
<canvas class="webgl-object-canvas" data-webgl-3d-object></canvas>
</div>
.webgl-object-shell {
position: relative;
width: min(100%, 720px);
aspect-ratio: 1 / 1;
}
.webgl-object-canvas {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
display: block;
}
Three.js Object Recipe
import * as THREE from "three";
function initWebGL3DObject(canvas, options = {}) {
if (!canvas) return () => {};
const renderer = new THREE.WebGLRenderer({
canvas,
antialias: true,
alpha: true,
});
renderer.setClearColor(0x000000, 0);
renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, options.maxDpr || 1.75));
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = options.exposure || 1.05;
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(38, 1, 0.1, 100);
camera.position.set(0, 0.15, 5.2);
const geometry = new THREE.IcosahedronGeometry(options.radius || 1.35, options.detail || 1);
const material = new THREE.MeshStandardMaterial({
color: options.color || 0x8aa4ff,
metalness: options.metalness ?? 0.48,
roughness: options.roughness ?? 0.34,
emissive: options.emissive || 0x101833,
emissiveIntensity: options.emissiveIntensity ?? 0.22,
flatShading: true,
});
const object = new THREE.Mesh(geometry, material);
object.castShadow = true;
object.receiveShadow = true;
scene.add(object);
const ambient = new THREE.AmbientLight(0xffffff, 0.38);
scene.add(ambient);
const key = new THREE.DirectionalLight(0xffffff, 2.15);
key.position.set(3.4, 4.2, 4.8);
key.castShadow = true;
key.shadow.mapSize.set(1024, 1024);
scene.add(key);
const rim = new THREE.DirectionalLight(options.rimColor || 0x7dd3fc, 0.82);
rim.position.set(-4.2, 1.2, -2.8);
scene.add(rim);
const shadowPlane = new THREE.Mesh(
new THREE.PlaneGeometry(5.2, 5.2),
new THREE.ShadowMaterial({ opacity: 0.18 })
);
shadowPlane.position.set(0, -1.65, 0);
shadowPlane.rotation.x = -Math.PI / 2;
shadowPlane.receiveShadow = true;
scene.add(shadowPlane);
const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
let rafId = 0;
function resize() {
const width = Math.max(1, canvas.clientWidth);
const height = Math.max(1, canvas.clientHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, options.maxDpr || 1.75));
renderer.setSize(width, height, false);
camera.aspect = width / height;
camera.updateProjectionMatrix();
}
function render(time = 0) {
const t = time * 0.001;
object.rotation.x = -0.16 + Math.sin(t * 0.45) * 0.06;
object.rotation.y = t * 0.28;
object.rotation.z = Math.sin(t * 0.32) * 0.08;
object.position.y = reduceMotion ? 0 : Math.sin(t * 0.8) * 0.08;
renderer.render(scene, camera);
if (!reduceMotion) rafId = requestAnimationFrame(render);
}
function handleResize() {
cancelAnimationFrame(rafId);
resize();
render();
}
resize();
render();
window.addEventListener("resize", handleResize);
return () => {
cancelAnimationFrame(rafId);
window.removeEventListener("resize", handleResize);
geometry.dispose();
material.dispose();
shadowPlane.geometry.dispose();
shadowPlane.material.dispose();
renderer.dispose();
};
}
const cleanupObject = initWebGL3DObject(
document.querySelector("[data-webgl-3d-object]"),
{
color: 0x8aa4ff,
rimColor: 0x7dd3fc,
metalness: 0.48,
roughness: 0.34,
emissive: 0x101833,
}
);
Material Defaults
- Premium metal:
metalness: 0.45-0.7, roughness: 0.25-0.45.
- Soft ceramic:
metalness: 0.0-0.15, roughness: 0.38-0.62.
- Glow-tinted tech object: low
emissive with emissiveIntensity: 0.12-0.35.
- Faceted object: set
flatShading: true; smooth product object: set it to false.
Lighting Defaults
- Key light: directional, high front-side angle, strongest source.
- Ambient fill: low intensity so shadows stay visible.
- Rim light: brand-tinted or cool light from behind to reveal edges.
- Shadows: enable only when the object needs grounded depth; keep map size moderate.
Motion Defaults
- Rotation: slow, continuous, and secondary to the page content.
- Floating:
0.04 to 0.12 units on Y.
- Reduced motion: render a still frame or only allow direct interaction.
- Avoid camera movement unless the object is the main interaction.
Avoid
- CSS 3D transforms pretending to be WebGL.
- Unlit materials when the ask is real lighting and depth.
- Flat planes with gradients instead of actual geometry.
- Strong bloom or particles that hide the form.
- High DPR, huge shadow maps, or too many lights on mobile.
- Letting the object compete with foreground copy or CTAs.
Quick Checks
- The object has visible form, edges, highlights, and shadows.
- The material uses
metalness, roughness, and optional emissive.
- Directional and ambient lights are both present.
- The camera is perspective, not orthographic by accident.
- Resize does not stretch the object.
- Geometry, material, event listeners, RAF, and renderer are cleaned up.
1---2name: webgl-3d-object3description: Create a real 3D WebGL object with geometric mesh depth, physically based material, directional and ambient lighting, perspective camera, subtle rotation, and floating motion. Use when a page needs a faceted 3D hero object or product-like visual with real lighting instead of CSS transform tricks.4metadata:5 source: https://skillmd.com/skills/mengto/webgl-3d-object6---78# WebGL 3D Object910## Use When11- A hero, feature block, or product moment needs one strong 3D object.12- The visual should show real geometry, lighting, highlights, and edges.13- A faceted mesh should float or rotate subtly inside a web layout.14- CSS transforms, SVG illusions, or flat gradients are not enough.1516## Rules171. Use real 3D geometry: `IcosahedronGeometry`, `DodecahedronGeometry`, `BoxGeometry`, custom `BufferGeometry`, or a glTF mesh.182. Use a perspective camera so the object has depth and scale.193. Use PBR material: `MeshStandardMaterial` or `MeshPhysicalMaterial`.204. Tune `metalness`, `roughness`, and `emissive` to match the brand mood.215. Light the object with at least one directional light plus ambient or hemisphere fill.226. Animate transforms only: subtle rotation, bobbing, or parallax.237. Handle resize and dispose geometry/material/renderer on teardown.2425## HTML And CSS2627```html28<div class="webgl-object-shell">29 <canvas class="webgl-object-canvas" data-webgl-3d-object></canvas>30</div>31```3233```css34.webgl-object-shell {35 position: relative;36 width: min(100%, 720px);37 aspect-ratio: 1 / 1;38}3940.webgl-object-canvas {41 position: absolute;42 inset: 0;43 width: 100%;44 height: 100%;45 display: block;46}47```4849## Three.js Object Recipe5051```js52import * as THREE from "three";5354function initWebGL3DObject(canvas, options = {}) {55 if (!canvas) return () => {};5657 const renderer = new THREE.WebGLRenderer({58 canvas,59 antialias: true,60 alpha: true,61 });62 renderer.setClearColor(0x000000, 0);63 renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, options.maxDpr || 1.75));64 renderer.outputColorSpace = THREE.SRGBColorSpace;65 renderer.toneMapping = THREE.ACESFilmicToneMapping;66 renderer.toneMappingExposure = options.exposure || 1.05;67 renderer.shadowMap.enabled = true;68 renderer.shadowMap.type = THREE.PCFSoftShadowMap;6970 const scene = new THREE.Scene();71 const camera = new THREE.PerspectiveCamera(38, 1, 0.1, 100);72 camera.position.set(0, 0.15, 5.2);7374 const geometry = new THREE.IcosahedronGeometry(options.radius || 1.35, options.detail || 1);75 const material = new THREE.MeshStandardMaterial({76 color: options.color || 0x8aa4ff,77 metalness: options.metalness ?? 0.48,78 roughness: options.roughness ?? 0.34,79 emissive: options.emissive || 0x101833,80 emissiveIntensity: options.emissiveIntensity ?? 0.22,81 flatShading: true,82 });8384 const object = new THREE.Mesh(geometry, material);85 object.castShadow = true;86 object.receiveShadow = true;87 scene.add(object);8889 const ambient = new THREE.AmbientLight(0xffffff, 0.38);90 scene.add(ambient);9192 const key = new THREE.DirectionalLight(0xffffff, 2.15);93 key.position.set(3.4, 4.2, 4.8);94 key.castShadow = true;95 key.shadow.mapSize.set(1024, 1024);96 scene.add(key);9798 const rim = new THREE.DirectionalLight(options.rimColor || 0x7dd3fc, 0.82);99 rim.position.set(-4.2, 1.2, -2.8);100 scene.add(rim);101102 const shadowPlane = new THREE.Mesh(103 new THREE.PlaneGeometry(5.2, 5.2),104 new THREE.ShadowMaterial({ opacity: 0.18 })105 );106 shadowPlane.position.set(0, -1.65, 0);107 shadowPlane.rotation.x = -Math.PI / 2;108 shadowPlane.receiveShadow = true;109 scene.add(shadowPlane);110111 const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;112 let rafId = 0;113114 function resize() {115 const width = Math.max(1, canvas.clientWidth);116 const height = Math.max(1, canvas.clientHeight);117 renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, options.maxDpr || 1.75));118 renderer.setSize(width, height, false);119 camera.aspect = width / height;120 camera.updateProjectionMatrix();121 }122123 function render(time = 0) {124 const t = time * 0.001;125 object.rotation.x = -0.16 + Math.sin(t * 0.45) * 0.06;126 object.rotation.y = t * 0.28;127 object.rotation.z = Math.sin(t * 0.32) * 0.08;128 object.position.y = reduceMotion ? 0 : Math.sin(t * 0.8) * 0.08;129130 renderer.render(scene, camera);131 if (!reduceMotion) rafId = requestAnimationFrame(render);132 }133134 function handleResize() {135 cancelAnimationFrame(rafId);136 resize();137 render();138 }139140 resize();141 render();142 window.addEventListener("resize", handleResize);143144 return () => {145 cancelAnimationFrame(rafId);146 window.removeEventListener("resize", handleResize);147 geometry.dispose();148 material.dispose();149 shadowPlane.geometry.dispose();150 shadowPlane.material.dispose();151 renderer.dispose();152 };153}154155const cleanupObject = initWebGL3DObject(156 document.querySelector("[data-webgl-3d-object]"),157 {158 color: 0x8aa4ff,159 rimColor: 0x7dd3fc,160 metalness: 0.48,161 roughness: 0.34,162 emissive: 0x101833,163 }164);165```166167## Material Defaults168- Premium metal: `metalness: 0.45-0.7`, `roughness: 0.25-0.45`.169- Soft ceramic: `metalness: 0.0-0.15`, `roughness: 0.38-0.62`.170- Glow-tinted tech object: low `emissive` with `emissiveIntensity: 0.12-0.35`.171- Faceted object: set `flatShading: true`; smooth product object: set it to `false`.172173## Lighting Defaults174- Key light: directional, high front-side angle, strongest source.175- Ambient fill: low intensity so shadows stay visible.176- Rim light: brand-tinted or cool light from behind to reveal edges.177- Shadows: enable only when the object needs grounded depth; keep map size moderate.178179## Motion Defaults180- Rotation: slow, continuous, and secondary to the page content.181- Floating: `0.04` to `0.12` units on Y.182- Reduced motion: render a still frame or only allow direct interaction.183- Avoid camera movement unless the object is the main interaction.184185## Avoid186- CSS 3D transforms pretending to be WebGL.187- Unlit materials when the ask is real lighting and depth.188- Flat planes with gradients instead of actual geometry.189- Strong bloom or particles that hide the form.190- High DPR, huge shadow maps, or too many lights on mobile.191- Letting the object compete with foreground copy or CTAs.192193## Quick Checks194- The object has visible form, edges, highlights, and shadows.195- The material uses `metalness`, `roughness`, and optional `emissive`.196- Directional and ambient lights are both present.197- The camera is perspective, not orthographic by accident.198- Resize does not stretch the object.199- Geometry, material, event listeners, RAF, and renderer are cleaned up.