Horizontal scroll galleries with parallax results have turn into a staple of contemporary internet design. You’ve most likely seen numerous tutorials on this impact, and for good motive. It’s visually putting and provides depth to what would in any other case be a easy picture carousel.
However right here’s the factor: most implementations are purely DOM-based, utilizing CSS transforms and JavaScript to maneuver parts round. Whereas this works superb for easy circumstances, it could possibly shortly turn into janky if you’re coping with a number of photographs, heavy parallax calculations, and {smooth} animations all working on the primary thread.
You’ve most likely come throughout Camille Mormal’s portfolio a shocking instance of how fluid and performant a horizontal gallery will be. What units it aside? It’s all rendered in WebGL. The smoothness comes from offloading the heavy lifting to the GPU, the place these operations thrive.
This obtained me considering: what if we may construct this impact step-by-step, beginning with a conventional 2D DOM method after which elevating it to WebGL? Not solely would this present the efficiency advantages, however it could additionally demystify how these results really work beneath the hood.
On this tutorial, we’ll create a horizontal parallax gallery in two methods:
- The 2D method: utilizing HTML, CSS, and JavaScript with customized {smooth} scrolling and parallax transforms
- The WebGL method: utilizing Three.js to render every thing on the GPU with shader-based parallax for buttery-smooth efficiency
We’ll preserve dependencies minimal (solely Three.js for the 3D half) and concentrate on understanding the core mechanics: how {smooth} scrolling works, how parallax is calculated, and the way to synchronize DOM measurements with WebGL rendering.
Let’s dive in.
The Preliminary Setup
For this tutorial, we’ll preserve issues easy and centered. No advanced construct instruments or heavy dependencies simply Vite for quick growth and Three.js for the WebGL half in a while.
Venture construction
Right here’s what our challenge appears to be like like:
├── css/
│ └── base.css
├── public/
│ ├── 1.webp
│ ├── 2.webp
│ └── ... (10 photographs complete)
├── src/
│ ├── gallery/
│ │ └── gallery.css
│ ├── utils/
│ │ └── math.ts
│ └── important.ts
├── index.html
└── package deal.jsonDependencies
{
"dependencies": {
"three": "^0.170.0"
},
"devDependencies": {
"typescript": "^5.6.3",
"vite": "^6.0.3",
"vite-plugin-glsl": "^1.3.0"
}
}That’s it. We’re utilizing:
- Vite for bundling and dev server
- TypeScript for sort security
- Three.js (we’ll add this later for the WebGL model)
- vite-plugin-glsl to import shader information (additionally for later)
HTML Construction
Let’s begin with the markup for our gallery. It’s intentionally easy, a wrapper and a container with photographs:
!["Image]("1.webp")
!["Image]("2.webp")
A number of issues to notice:
- The
loadingclass on the physique, we’ll take away this as soon as photographs are preloaded draggable="false"prevents the default drag habits- We’re wrapping photographs in
Base CSS
The CSS does a lot of the heavy lifting for structure. Right here’s the important construction:
.gallery__wrapper {
top: 100vh;
width: 100vw;
overflow: hidden;
place: relative;
}
.gallery__image__container {
show: flex;
hole: 2rem;
top: 100%;
width: max-content;
will-change: remodel;
}
.gallery__media {
place: relative;
overflow: hidden;
top: 60vh;
aspect-ratio: 4 / 3;
flex-shrink: 0;
}
.gallery__media__image {
place: absolute;
prime: 0;
left: 0;
width: 100%;
top: 100%;
object-fit: cowl;
will-change: remodel;
}Key particulars:
.gallery__wrapperis our viewport, it hides overflow.gallery__image__containermakes use ofshow: flexandwidth: max-contentso it expands primarily based on content materialwill-change: remodelhints to the browser that we’ll be remodeling these parts (optimization)- Every picture wrapper (
.gallery__media) hasoverflow: hiddenthat is essential for the parallax impact later. The photographs inside will transfer, however the container clips them.
Organising TypeScript
We’ll create a easy utility file for math features we’ll want:
// src/utils/math.ts
export operate lerp(begin: quantity, finish: quantity, issue: quantity): quantity {
return begin * (1 - issue) + finish * issue;
}
export operate clamp(min: quantity, max: quantity, worth: quantity): quantity {
return Math.max(min, Math.min(max, worth));
}These two features are important:
lerp(linear interpolation): easily transitions from one worth to a different. That is what makes our scroll really feel buttery {smooth} as an alternative of instantaneous.clamp: restricts a worth between a min and max. We’ll use this to stop scrolling past the gallery bounds.
For now, we should always have one thing like this :
Constructing the 2D Model
Now that we've our HTML and CSS in place, let’s deliver this gallery to life with customized horizontal scrolling. We’re going to construct every thing from scratch to grasp precisely what’s taking place beneath the hood.
Customized Easy Scrolling
Right here’s the factor about default browser scroll: it’s both too snappy or not {smooth} sufficient, and you may’t simply management its habits. For a refined gallery expertise, we want full management.
Let’s create our App class in important.ts:
// src/important.ts
import "./gallery/gallery.css";
import { clamp, lerp } from "./utils/math";
interface Scroll {
present: quantity;
goal: quantity;
ease: quantity;
restrict: quantity;
}
class App {
container: HTMLElement | null;
wrapper: HTMLElement | null;
scroll: Scroll;
constructor() {
this.container = doc.querySelector(".gallery__image__container");
this.wrapper = doc.querySelector(".gallery__wrapper");
this.scroll = {
present: 0,
goal: 0,
ease: 0.07,
restrict: 0,
};
this.setLimit();
this.addEventListeners();
this.render();
}
setLimit()
onWheel(e: WheelEvent) {
this.scroll.goal += e.deltaY;
}
onResize() {
this.setLimit();
}
addEventListeners() {
window.addEventListener("resize", this.onResize.bind(this), {
passive: true,
});
window.addEventListener("wheel", this.onWheel.bind(this), {
passive: true,
});
}
render() {
this.scroll.goal = clamp(0, this.scroll.restrict, this.scroll.goal);
this.scroll.present = lerp(
this.scroll.present,
this.scroll.goal,
this.scroll.ease,
);
if (this.container) {
this.container.type.remodel = `translateX(${-this.scroll.present}px)`;
}
requestAnimationFrame(this.render.bind(this));
}
}
new App();Breaking it down
The Scroll object:
scroll: {
present: 0, // The place we're proper now
goal: 0, // The place we need to be
ease: 0.07, // How briskly we interpolate (decrease = smoother however slower)
restrict: 0, // Most scroll distance
}That is the center of {smooth} scrolling. As an alternative of leaping on to the scroll place, we progressively transfer present towards goal utilizing lerp().
Setting the scroll restrict:
setLimit() {
this.scroll.restrict = this.container.scrollWidth - this.wrapper.clientWidth;
}This calculates how far we will scroll. scrollWidth is the entire width of all photographs plus gaps, and we subtract the viewport width to get the utmost scroll distance.
Capturing wheel occasions:
onWheel(e: WheelEvent) {
this.scroll.goal += e.deltaY;
}Once you scroll your mouse wheel, we add the delta to our goal place. Discover we’re utilizing deltaY (vertical scroll) however making use of it horizontally, this feels extra pure than forcing customers to scroll sideways.
The render loop:
render() {
// Clamp goal to legitimate vary
this.scroll.goal = clamp(0, this.scroll.restrict, this.scroll.goal);
// Easily interpolate present towards goal
this.scroll.present = lerp(
this.scroll.present,
this.scroll.goal,
this.scroll.ease,
);
// Apply remodel
if (this.container) {
this.container.type.remodel = `translateX(${-this.scroll.present}px)`;
}
requestAnimationFrame(this.render.bind(this));
}This runs 60 instances per second (or at your monitor’s refresh price). Every body:
- We clamp the goal to stop scrolling out of bounds
- We lerp
presenttowardsgoalby the benefit issue (7%) - We apply the remodel to maneuver the gallery
Why lerp makes it {smooth}: Let’s say goal is 1000 and present is 0. With ease = 0.07:
- Body 1:
present = 0 + (1000 - 0) * 0.07 = 70 - Body 2:
present = 70 + (1000 - 70) * 0.07 = 135.1 - Body 3:
present = 135.1 + (1000 - 135.1) * 0.07 = 195.6 - …and so forth
It begins quick and slows down because it approaches the goal that’s the graceful, eased movement you are feeling.
The end result
At this level, you will have a totally useful horizontal scroll gallery with buttery {smooth} interpolation. Attempt scrolling, discover the way it glides as an alternative of snapping? That’s the ability of lerp.
However we’re not completed but. Let’s add the parallax impact to make it really particular.
Including the Parallax Impact
Now comes the magic half. Parallax creates depth by making photographs transfer at completely different speeds relative to the scroll. However right here’s what most tutorials don’t clarify nicely: parallax requires each CSS and JavaScript working collectively, and understanding how they join is crucial.
The CSS Setup (Crucial!)
Right here’s the CSS that makes parallax really doable:
.gallery__media {
place: relative;
overflow: hidden; /* Clips the outsized picture */
top: 60vh;
aspect-ratio: 4 / 3;
flex-shrink: 0;
}
.gallery__media__image {
place: absolute;
prime: 0;
left: -12.5%; /* Begin offset to the left */
width: 125%; /* Make picture BIGGER than container */
top: 100%;
object-fit: cowl;
will-change: remodel;
}That is the muse of your complete impact. Let me clarify why every worth issues:
Making the picture bigger:
width: 125%;The picture is 25% wider than its container. This additional house is what permits the picture to maneuver. Consider it like this: if the picture was precisely 100% width, there’d be no room for it to shift left or proper with out exhibiting empty house.
By making it 125%, we’re making a “buffer zone”, 12.5% on either side that the picture can slide into.
Offsetting the beginning place:
left: -12.5%;We place the picture 12.5% to the left of its container’s left edge. This facilities the additional width we created. With out this, the picture would begin flush left, and we’d solely be capable to parallax in a single course.
With this offset:
- The picture has 12.5% hidden on the left
- The picture has 12.5% hidden on the proper
- The seen portion is centered
- We are able to now transfer the picture each instructions because it scrolls by way of the viewport
Why these particular values?
The maths is easy: in case your picture is 125% huge (25% additional), you break up that additional house in half: 25% / 2 = 12.5%. This creates equal motion vary in each instructions.
Desire a stronger parallax impact? Improve each values proportionally:
width: 150%andleft: -25%→ extra dramatic motionwidth: 115%andleft: -7.5%→ extra refined impact
Simply keep in mind: left ought to at all times be (width - 100%) / 2 to maintain it centered.
The clipping container:
overflow: hidden;With out this, you’d see the outsized picture bleeding out of its container, breaking your complete structure. The mother or father acts as a “window” that clips the picture to the supposed measurement, whereas the picture itself can shift round inside that window.
How CSS and JavaScript Work Collectively
Right here’s the important thing connection:
- CSS units up the playground → The picture is 125% huge with a -12.5% offset, giving it room to maneuver inside its clipped container
- JavaScript strikes the picture inside that house → As we scroll, we calculate every picture’s place and apply transforms
- The end result → The picture shifts horizontally inside its fixed-size container, creating the parallax phantasm
With out the CSS sizing and positioning, the JavaScript would have nowhere to maneuver the picture. With out the JavaScript, the CSS would simply present a static, offset picture.
The JavaScript Implementation
Now let’s add the parallax impact to our App class:
import './gallery.css';
export class Gallery {
container: HTMLElement | null;
wrapper: HTMLElement | null;
photographs: NodeListOf;
constructor() {
this.container = doc.querySelector('.gallery__image__container');
this.wrapper = doc.querySelector('.gallery__wrapper');
this.photographs = doc.querySelectorAll('.gallery__media__image');
}
non-public clamp(v: quantity, min: quantity, max: quantity) {
return Math.max(min, Math.min(max, v));
}
applyParallaxEffect() {
const vw = window.innerWidth;
const viewportCenter = vw * 0.5;
this.photographs.forEach((picture) => {
const mother or father = picture.parentElement as HTMLElement;
if (!mother or father) return;
const rect = mother or father.getBoundingClientRect();
const elementCenter = rect.left + rect.width * 0.5;
// -1 (far left) .. 0 (heart) .. 1 (far proper)
const t = this.clamp((elementCenter - viewportCenter) / viewportCenter, -1, 1);
// For 125% picture width, secure max translate ~= 10% of picture width
const MAX_SHIFT = 10;
const shift = -t * MAX_SHIFT; // unfavourable for counter-motion depth
picture.type.remodel = `translate3d(${shift}%, 0, 0)`;
});
}
render(container: HTMLElement, scroll: quantity) {
container.type.remodel = `translateX(${scroll < 0.01 ? 0 : -scroll}px)`;
this.applyParallaxEffect();
}
} Breaking Down the Parallax Calculation
Let’s dissect applyParallaxEffect() line by line and see the way it connects to our CSS:
applyParallaxEffect() {
const vw = window.innerWidth;
const viewportCenter = vw * 0.5;
// With CSS: picture width = 125% => additional = 25% => 12.5% either side.
// translateX(%) is relative to IMAGE width (125%), so secure max ≈ 12.5/125 = 10%.
const MAX_SHIFT = 10; // %
this.photographs.forEach((picture) => {
const mother or father = picture.parentElement as HTMLElement;
if (!mother or father) return;
const rect = mother or father.getBoundingClientRect();
const elementCenter = rect.left + rect.width * 0.5;
// -1..1 because the ingredient strikes throughout the viewport
const t = (elementCenter - viewportCenter) / viewportCenter;
const clamped = Math.max(-1, Math.min(1, t));
// Counter-motion: ingredient proper => picture shifts left, and many others.
const shift = -clamped * MAX_SHIFT;
picture.type.remodel = `translate3d(${shift}%, 0, 0)`;
});
}
Step 1: Get the container’s place in viewport
const rect = mother or father.getBoundingClientRect();getBoundingClientRect() tells us the place every picture container sits relative to the viewport, and we use it to compute the ingredient’s heart place.
- Coming into from proper:
rect.leftis giant (e.g. > viewport width) - Centered: the ingredient’s heart is close to the viewport heart
- Exiting left:
rect.leftturns into unfavourable
Step 2: Compute distance from the viewport heart
const elementCenter = rect.left + rect.width * 0.5;We use the viewport heart because the reference level, so the parallax is strongest close to the middle and naturally eases towards the perimeters—with out counting on an arbitrary 25% offset.
Step 3: Calculate and apply the parallax
picture.type.remodel = `translate3d(${shift}%, 0, 0)`;Right here’s the place the magic occurs:
- We compute a normalized place t within the vary [-1, 1] primarily based on the ingredient’s heart relative to the viewport heart
- The unfavourable is essential: because the ingredient strikes proper, the picture shifts left (counter-motion), creating depth
- We map t to a bounded proportion shift (e.g. ±10%) so the impact is constant throughout viewports
- The sure ensures the motion stays contained in the CSS buffer, so that you received’t reveal empty house
Connecting again to CSS:
Bear in mind, our picture is:
- 125% huge
- Positioned at -12.5% left
- Has 12.5% hidden on either side
The JavaScript remodel shifts the picture inside that additional 25% of width. Since translateX(%) is relative to the picture width (125%), translateX(-10%) strikes the picture by 10% of its personal width, which is 12.5% of the container width—precisely the hidden buffer on either side.
Adjusting the impact depth:
Need to modify the parallax power? Change MAX_SHIFT (the utmost translate in %):
MAX_SHIFT = 4→ refinedMAX_SHIFT = 8→ mediumMAX_SHIFT = 10→ max-safe for width: 125%
If MAX_SHIFT is simply too excessive on your CSS sizing, you’ll reveal the feel edges—so both decrease MAX_SHIFT or improve the CSS buffer (e.g. wider picture).
What’s Really Taking place
Let’s hint by way of an instance:
Think about a container at left = 800px (proper of heart):
- Compute normalized place:
t = (elementCenter - viewportCenter) / viewportCenter - Clamp to [-1, 1]
- Apply bounded shift:
shift = -t * MAX_SHIFT
Instance (1920px huge viewport):
If the ingredient’s heart is 320px proper of the viewport heart:
t = 320 / 960 = 0.333shift = -0.333 * 10% ≈ -3.33%- Rework:
translate3d(-3.33%, 0, 0)
As a result of the picture is 125% huge and positioned at -12.5%, this -3.33% remodel shifts it barely left inside its container, creating the phantasm that it’s on a distinct depth airplane.
Because the container strikes left (scroll will increase):
- Because the ingredient strikes throughout the viewport,
tstrikes towards 0 (heart) and modifications signal previous heart, soshifteasily strikes in the other way (counter-motion). - This counter-movement at a distinct price creates the parallax depth impact
The Full Image: CSS + JS
The parallax impact is unimaginable with out each layers:
- CSS creates the bodily house → 125% width + -12.5% offset = 25% room to maneuver
- CSS clips the end result →
overflow: hiddenhides the additional width - JavaScript calculates place → Makes use of viewport place to find out how a lot to shift
- JavaScript applies remodel → Strikes the picture inside the house CSS created
Take away the CSS sizing? No room to maneuver, no impact. Take away the JavaScript? Static picture, no parallax. Take away overflow: hidden? Format breaks fully.
They’re inseparable.
Efficiency Issues
You may marvel: “Isn’t calling getBoundingClientRect() and setting kinds in a loop each body costly?”
Sure and no. Right here’s why this method works nicely:
What makes it performant:
will-change: remodeltells the browser to optimize for remodel modifications, typically selling the ingredient to its personal compositor layer. This implies the browser prepares for frequent remodel updates.remodelis GPU accelerated and operates on the composite layer. In contrast to properties likeprime,left, ormargin, transforms don’t set off structure recalculations or repaints, solely compositing, which is extraordinarily quick.getBoundingClientRect()is comparatively low cost if you’re not inflicting structure thrashing. Since we’re studying all positions first, then writing transforms, we keep away from the read-write-read-write sample that forces synchronous structure.
Once you may have to optimize:
For 10-15 photographs (like in our gallery), this method runs buttery {smooth} at 60fps. Nonetheless, in the event you had been coping with 50+ photographs or concentrating on low-end cellular units, you’d need to optimize by:
- Solely calculating parallax for photographs at the moment in or close to the viewport
- Utilizing Intersection Observer to trace which photographs are seen
- Debouncing or throttling calculations on slower units
However for many sensible use circumstances, this simple method is completely performant. The bottom line is understanding what triggers structure/paint/composite and sticking to GPU-accelerated properties.
Et voilà ! You now have a totally useful 2D parallax gallery with {smooth} scrolling and optimized transforms. The mix of correctly sized CSS containers and body by body place calculations creates a refined, skilled impact.
However right here’s the factor: we’re nonetheless doing all of this on the CPU, manipulating the DOM each body, and calling getBoundingClientRect() for every picture. What if we may offload this to the GPU completely and make it even smoother? That’s the place WebGL is available in.
Elevating to WebGL
Alright, our 2D model works nice. However do not forget that silky {smooth} feeling from Camille Mormal’s website? That comes from rendering every thing on the GPU with WebGL. Let’s deliver Three.js into the image.
First, let’s set up Three.js:
npm set up threeNow, let’s begin including WebGL to our important.ts. We’ll want a renderer, a scene, a digicam…
import * as THREE from 'three';
class App {
container: HTMLElement | null;
wrapper: HTMLElement | null;
photographs: NodeListOf;
scroll: Scroll;
// WebGL stuff
renderer!: THREE.WebGLRenderer;
scene!: THREE.Scene;
digicam!: THREE.PerspectiveCamera;
// ... and we'll want meshes for every picture
// ... and supplies
// ... and textures
// ... and replace logic for every mesh
constructor() {
// ... all our current scroll code
// ... plus all of the WebGL initialization
// ... plus mesh creation for every picture
// ... plus synchronization logic
}
applyParallaxEffect() {
// Preserve this for 2D model
}
updateWebGLParallax() {
// New parallax for 3D model
}
render() {
// Deal with each 2D and 3D rendering
// That is getting messy...
}
} Wait… our important.ts is about to blow up. We’re mixing scroll logic, 2D DOM manipulation, WebGL scene setup, per-mesh updates, and rendering multi functional class. That is going to be unreadable.
Refactoring for Sanity
Let’s take a step again. We have to separate considerations earlier than this turns into unmaintainable. Right here’s what we really want:
important.ts → The orchestrator
- Handles scroll state (works for each 2D and 3D)
- Detects which model to load (DOM vs WebGL)
- Coordinates every thing
gallery/index.ts → The 2D implementation
- Takes a container and scroll worth
- Handles all DOM primarily based parallax logic
- Self contained, reusable
gallery/GL.ts → The WebGL scene supervisor
- Units up renderer, scene, digicam
- Creates all of the meshes
- Handles resize
gallery/GLMedia.ts → Particular person WebGL picture
- One occasion per picture
- Manages its personal mesh, materials, texture
- Handles its personal place and parallax updates
This separation means:
- Every file has one clear duty
- We are able to work on 2D or 3D independently
- The code is testable and maintainable
important.tsstays clear and readable
Right here’s the refactored important.ts:
// src/important.ts
import { Gallery } from "./gallery";
import { GL } from "./gallery/GL";
import { clamp, lerp } from "./utils/math";
class App {
container: HTMLElement | null;
wrapper: HTMLElement | null;
scroll: Scroll;
gallery!: Gallery;
gl!: HTMLElement | null;
canvas!: GL | null;
constructor() {
this.container =
doc.querySelector(".gallery__image__container") ||
doc.querySelector(".gallery__image__container__gl");
this.wrapper =
doc.querySelector(".gallery__wrapper") ||
doc.querySelector(".gallery__wrapper__gl");
this.gl = doc.getElementById("gl");
this.scroll = {
present: 0,
goal: 0,
ease: 0.07,
restrict: 0,
};
this.init();
this.setLimit();
this.onResize();
this.addEventListeners();
this.render();
});
}
init() {
this.gallery = new Gallery();
if (this.gl) {
this.canvas = new GL();
}
}
setLimit()
onWheel(e: WheelEvent) {
this.scroll.goal += e.deltaY;
}
onResize() {
this.setLimit();
this.canvas?.onResize({
width: window.innerWidth,
top: window.innerHeight,
});
}
addEventListeners() {
window.addEventListener("resize", this.onResize.bind(this));
window.addEventListener("wheel", this.onWheel.bind(this), {
passive: true,
});
}
render() {
this.scroll.goal = clamp(0, this.scroll.restrict, this.scroll.goal);
this.scroll.present = lerp(
this.scroll.present,
this.scroll.goal,
this.scroll.ease,
);
this.gallery?.render(this.container!, this.scroll.present);
this.canvas?.render(this.scroll.present);
requestAnimationFrame(this.render.bind(this));
}
}
new App();A lot cleaner! Now important.ts simply orchestrates. The 2D logic lives in gallery/index.ts (which we have already got), and the WebGL magic will reside in GL.ts and GLMedia.ts.
A fast notice: If I’d been smarter from the beginning, I might’ve structured it this fashion from commit one. However truthfully? It’s completely superb to construct a prototype, understand it’s getting messy, after which refactor. That’s actual growth. The necessary factor is recognizing when to refactor earlier than it turns into technical debt.
Now let’s dive into the WebGL implementation.
Constructing the WebGL Model
That is the place issues get attention-grabbing. We’re going to render our gallery completely on the GPU, which implies we have to suppose in another way about positioning, sizing, and parallax.
The Digital camera Setup
One of many trickiest components of blending DOM and WebGL is synchronization. We wish our WebGL meshes to match the dimensions and place of DOM parts precisely. To do that, we want a digicam setup the place 1 pixel = 1 Three.js unit.
Right here’s the trick in GL.ts:
// src/gallery/GL.ts
import * as THREE from "three";
import { GLMedia } from "./GLMedia";
export class GL {
renderer: THREE.WebGLRenderer;
scene: THREE.Scene;
digicam: THREE.PerspectiveCamera;
group: THREE.Group;
display screen = {
width: window.innerWidth,
top: window.innerHeight,
};
medias: HTMLElement[];
allMedias: GLMedia[];
constructor() {
this.renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
doc.physique.appendChild(this.renderer.domElement);
this.scene = new THREE.Scene();
// The magic formulation for 1px = 1 unit
const fov = 2 * Math.atan(this.display screen.top / 2 / 100) * (180 / Math.PI);
this.digicam = new THREE.PerspectiveCamera(
fov,
this.display screen.width / this.display screen.top,
0.01,
1000,
);
this.digicam.place.set(0, 0, 100);
this.group = new THREE.Group();
this.medias = Array.from(
doc.querySelectorAll(".gallery__media__image__gl"),
);
this.createGeometry();
this.createGallery();
}
createGeometry() {
this.geometry = new THREE.PlaneGeometry(1, 1, 32, 32);
}
createGallery() {
// We'll instantiate our GLMedia situations right here quickly
this.scene.add(this.group);
}
onResize(viewport = { width: window.innerWidth, top: window.innerHeight }) {
this.display screen = viewport;
this.digicam.facet = this.display screen.width / this.display screen.top;
this.digicam.fov = 2 * Math.atan(this.display screen.top / 2 / 100) * (180 / Math.PI);
this.digicam.updateProjectionMatrix();
this.renderer.setSize(this.display screen.width, this.display screen.top);
this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
}
render(scroll: quantity) {
this.renderer.render(this.scene, this.digicam);
}
}The FOV calculation defined:
const fov = 2 * Math.atan(this.display screen.top / 2 / 100) * (180 / Math.PI);This formulation calculates the sector of view in order that at z = 100 (the place our digicam sits), the seen top precisely matches window.innerHeight in pixels.
Right here’s why it really works:
Math.atan(this.display screen.top / 2 / 100)offers us the angle from the digicam to the highest fringe of the display screen- We multiply by 2 to get the complete vertical angle
- We convert from radians to levels with
* (180 / Math.PI)
The end result: once we place a mesh at z = 0 and set its scale to mesh.scale.set(width, top, 1), these width/top values correspond on to pixels.
That is important for syncing DOM and WebGL.
Now let’s construct the GLMedia class the place the true magic occurs.
Syncing DOM with WebGL: The GLMedia Class
Every picture in our gallery wants a WebGL illustration, a mesh with a texture. However right here’s the problem: we have to make every WebGL airplane match its corresponding DOM ingredient’s measurement and place precisely.
HTML Setup
First, a fast notice in regards to the HTML. For the WebGL model (index2.html), we use barely completely different class names:
Discover the id="gl" on the physique, that is how important.ts detects which model to load.
In our CSS, we disguise these DOM photographs as soon as WebGL is prepared:
physique.demo-2 .gallery__media__image__gl {
opacity: 0; /* Disguise DOM photographs, present solely WebGL */
}We preserve the DOM parts within the HTML as a result of:
- They allow us to use
getBoundingClientRect()to get positions - They keep the structure construction (flexbox, gaps, and many others.)
- They supply fallback if WebGL fails
- They’re our “supply of fact” for sizing and positioning
Constructing GLMedia: Step by Step
Let’s begin with the essential construction:
// src/gallery/GLMedia.ts
import * as THREE from "three";
interface Props {
scene: THREE.Group;
ingredient: HTMLElement;
viewport: { width: quantity; top: quantity };
digicam: THREE.PerspectiveCamera;
geometry: THREE.PlaneGeometry;
renderer: THREE.WebGLRenderer;
}
export class GLMedia {
digicam: THREE.PerspectiveCamera;
ingredient: HTMLElement;
scene: THREE.Group;
geometry: THREE.PlaneGeometry;
renderer: THREE.WebGLRenderer;
materials: THREE.ShaderMaterial;
texture: THREE.Texture;
viewport: { width: quantity; top: quantity };
bounds: DOMRect;
mesh: THREE.Mesh;
constructor({ scene, ingredient, viewport, digicam, geometry, renderer }: Props) {
this.scene = scene;
this.ingredient = ingredient;
this.viewport = viewport;
this.digicam = digicam;
this.geometry = geometry;
this.renderer = renderer;
this.bounds = this.ingredient.getBoundingClientRect();
this.createMesh();
this.createTexture();
}
}Nothing fancy but. We’re simply storing references and getting the DOM ingredient’s bounding field.
Step 1: Creating the Mesh
Let’s create a primary mesh with a shader materials:
createMesh() {
this.materials = new THREE.ShaderMaterial({
uniforms: {
uTexture: { worth: null },
uResolution: 1,
),
,
uImageResolution: { worth: new THREE.Vector2(1, 1) },
},
vertexShader: `
various vec2 vUv;
void important() {
vUv = uv;
gl_Position = projectionMatrix * modelViewMatrix * vec4(place, 1.0);
}
`,
fragmentShader: `
precision highp float;
various vec2 vUv;
uniform sampler2D uTexture;
void important() {
vec3 col = texture2D(uTexture, vUv).rgb;
gl_FragColor = vec4(col, 1.0);
}
`,
});
this.mesh = new THREE.Mesh(this.geometry, this.materials);
this.scene.add(this.mesh);
}What are these uniforms?
uTexture: The picture texture (we’ll load this subsequent)uResolution: The mesh’s width and top in pixels, this may match the DOM ingredientuImageResolution: The precise picture’s width and top, we want this forobject-fit: cowlhabits
For now, the shaders are primary: simply cross by way of UVs and render the feel.
Step 2: Loading the Texture
createTexture() {
this.texture = new THREE.TextureLoader().load(
this.ingredient.getAttribute("src") as string,
(textual content) => {
const materials = this.mesh?.materials as THREE.ShaderMaterial;
if (materials?.uniforms?.uImageResolution) {
materials.uniforms.uImageResolution.worth.set(
textual content.picture.width,
textual content.picture.top,
);
}
},
);
this.materials.uniforms.uTexture.worth = this.texture;
}Why do we want uImageResolution?
Right here’s the issue: our mesh may be 800×1000 pixels, however the picture may be 1920×1080. If we simply map the feel on to the mesh, it’ll stretch and warp.
In CSS, we use object-fit: cowl to deal with this, it crops and facilities the picture to fill the container with out distortion. In WebGL, we have to do that manually within the shader.
The uImageResolution uniform shops the unique picture dimensions. Later, we’ll write a shader operate that calculates the proper UV coordinates to realize object-fit: cowl habits.
The callback operate fires when the feel masses, letting us seize the precise picture dimensions from textual content.picture.width and textual content.picture.top.
Step 3: Sizing the Mesh
Now let’s make the mesh match the DOM ingredient’s measurement:
updateScale() {
this.bounds = this.ingredient.getBoundingClientRect();
this.mesh?.scale.set(this.bounds.width, this.bounds.top, 1);
this.materials?.uniforms.uResolution.worth.set(
this.bounds.width,
this.bounds.top,
);
}Bear in mind our digicam setup the place 1 pixel = 1 unit? That is the place it pays off.
We learn the DOM ingredient’s dimensions with getBoundingClientRect(), then immediately apply them to the mesh’s scale. Due to our digicam FOV calculation, a scale of (800, 1000, 1) makes the mesh precisely 800×1000 pixels on display screen.
We additionally replace the uResolution uniform so the shader is aware of the mesh’s dimensions, essential for the object-fit: cowl calculation.
Step 4: Positioning the Mesh
That is the place DOM/WebGL sync will get tough. Three.js makes use of a center-origin coordinate system, however getBoundingClientRect() offers us top-left positions. We have to convert between them.
However there’s one other problem: horizontal scrolling. Bear in mind our {smooth} scroll system in important.ts? The scroll.present worth that’s being lerped each body? We have to account for that in our WebGL positioning.
updatePosition(scroll: quantity) {
const x =
this.bounds.left -
scroll -
this.viewport.width / 2 +
this.bounds.width / 2;
const y =
-this.bounds.prime + this.viewport.top / 2 - this.bounds.top / 2;
this.mesh.place.set(x, y, 0);
}Breaking down the mathematics:
X place (horizontal):
const x = this.bounds.left - scroll - this.viewport.width / 2 + this.bounds.width / 2;Let’s go step-by-step:
this.bounds.left→ DOM ingredient’s left edge in pixels from viewport left (fromgetBoundingClientRect())- scroll→ That is essential. Thescrollparameter comes fromimportant.ts‘sscroll.presentworth, our easily lerped horizontal scroll place. Because the person scrolls, this worth will increase, and we have to shift all meshes left by that quantity to simulate horizontal motion. With out this, the meshes would keep fastened whereas the DOM scrolls.- this.viewport.width / 2→ Shift origin from left edge to heart. Three.js positions meshes from their heart level, however the viewport’s origin (0,0) is on the heart of the display screen, not the top-left just like the DOM.+ this.bounds.width / 2→ Offset by half the mesh width. SincegetBoundingClientRect()offers us the left fringe of the ingredient, however Three.js positions from the middle, we have to shift proper by half the mesh’s width.
Y place (vertical):
const y = -this.bounds.prime + this.viewport.top / 2 - this.bounds.top / 2;-this.bounds.prime→ Invert Y axis (DOM counts down, WebGL counts up)+ this.viewport.top / 2→ Shift origin from prime to heart- this.bounds.top / 2→ Offset by half the mesh top
This formulation ensures the WebGL mesh sits precisely the place the DOM ingredient can be.
Placing It Collectively
Let’s replace our GL.ts to instantiate these meshes:
createGallery() {
this.allMedias = this.medias.map((media) => {
return new GLMedia({
scene: this.group,
ingredient: media,
viewport: this.display screen,
digicam: this.digicam,
geometry: this.geometry,
renderer: this.renderer,
});
});
this.scene.add(this.group);
}And add the render technique to GLMedia:
render(scroll: quantity) {
this.updatePosition(scroll);
}
onResize(viewport: { width: quantity; top: quantity }) {
this.viewport = viewport;
this.updateScale();
}What You Ought to See
At this level, in the event you open index2.html, you need to see… stretched, distorted photographs positioned accurately however trying horrible.
Why? As a result of we’re mapping textures 1:1 to the mesh UVs with out accounting for facet ratio variations. A 1920×1080 picture stretched onto an 800×1000 mesh appears to be like terrible.
That is precisely why we want the object-fit: cowl equal in our shader.
Attaining object-fit: cowl in Shaders
Bear in mind these stretched, distorted photographs? That’s as a result of we’re mapping the feel on to the mesh with out accounting for facet ratio variations. In CSS, object-fit: cowl handles this mechanically. In WebGL, we have to do it ourselves.
The coverUv() Operate
Let’s add this operate to our fragment shader:
// src/shaders/mediaFragment.glsl
precision highp float;
various vec2 vUv;
uniform sampler2D uTexture;
uniform vec2 uResolution;
uniform vec2 uImageResolution;
vec2 coverUv(vec2 uv, vec2 decision, vec2 imageResolution) {
vec2 ratio = vec2(
min((decision.x / decision.y) / (imageResolution.x / imageResolution.y), 1.0),
min((decision.y / decision.x) / (imageResolution.y / imageResolution.x), 1.0)
);
return vec2(
uv.x * ratio.x + (1.0 - ratio.x) * 0.5,
uv.y * ratio.y + (1.0 - ratio.y) * 0.5
);
}
void important() {
vec2 uv = coverUv(vUv, uResolution, uImageResolution);
vec3 col = texture2D(uTexture, uv).rgb;
gl_FragColor = vec4(col, 1.);
}How coverUv() Works
This operate calculates the proper UV coordinates to crop and heart the picture, similar to object-fit: cowl.
Step 1: Calculate facet ratios
vec2 ratio = vec2(
min((decision.x / decision.y) / (imageResolution.x / imageResolution.y), 1.0),
min((decision.y / decision.x) / (imageResolution.y / imageResolution.x), 1.0)
);We’re evaluating two facet ratios:
decision→ the mesh dimensions (e.g., 800×1000)imageResolution→ the precise picture dimensions (e.g., 1920×1080)
For every axis, we calculate how a lot we have to scale to suit. The min(..., 1.0) ensures we solely scale down, by no means up.
Instance:
- Mesh: 800×1000 (facet ratio 0.8)
- Picture: 1920×1080 (facet ratio 1.78)
The picture is wider than the mesh. To cowl the mesh top smart, we have to crop the edges.
ratio.x = min((0.8) / (1.78), 1.0) = min(0.45, 1.0) = 0.45ratio.y = min((1.25) / (0.56), 1.0) = min(2.23, 1.0) = 1.0
Step 2: Apply the ratio and heart
return vec2(
uv.x * ratio.x + (1.0 - ratio.x) * 0.5,
uv.y * ratio.y + (1.0 - ratio.y) * 0.5
);
We scale the UVs by the ratio, then offset by half the remaining house to heart the crop.
Utilizing our instance:
- X:
uv.x * 0.45 + (1.0 - 0.45) * 0.5 = uv.x * 0.45 + 0.275 - Y:
uv.y * 1.0 + 0.0 = uv.y
This implies:
- Horizontally, we’re solely utilizing 45% of the picture width, centered
- Vertically, we’re utilizing the complete picture top
The end result: the picture covers your complete mesh with out distortion, cropping the edges as wanted.
Earlier than and After
With out coverUv(), your photographs look stretched and flawed. With it, they give the impression of being good, correctly cropped and centered similar to object-fit: cowl in CSS.
Now your WebGL gallery ought to look similar to the DOM model (minus the parallax, which we’re about so as to add).
Parallax in WebGL
That is the place WebGL actually shines. As an alternative of calculating positions for every picture in JavaScript and making use of CSS transforms, we will do the parallax impact completely within the shader on the GPU.
The Idea
Bear in mind how we did parallax in 2D? We:
- Made the picture 125% huge with a -12.5% offset (CSS)
- Calculated every picture’s place within the viewport (JS)
- Utilized a
translateXremodel (JS → CSS)
In WebGL, we do one thing comparable however in UV house:
- We scale the UVs to make the feel smaller (like zooming out), creating house round it
- We calculate the picture’s place within the viewport (JS)
- We shift the UVs horizontally primarily based on that place (shader)
Including the Parallax Uniform
First, add the uParallax uniform to our materials in GLMedia.ts
createMesh() {
this.materials = new THREE.ShaderMaterial({
uniforms: {
uTexture: { worth: null },
uResolution: 1,
),
,
uImageResolution: { worth: new THREE.Vector2(1, 1) },
uParallax: { worth: 0 }, // Add this
},
vertexShader: vertex,
fragmentShader: fragment,
});
this.mesh = new THREE.Mesh(this.geometry, this.materials);
this.scene.add(this.mesh);
}Calculating the Parallax Worth
Add this technique to GLMedia.ts:
updateParallax(scroll: quantity) {
if (!this.bounds) return;
const { innerWidth } = window;
const elementLeft = this.bounds.left - scroll;
const elementRight = elementLeft + this.bounds.width;
// Solely calculate parallax for seen parts
if (elementRight >= 0 && elementLeft <= innerWidth) {
// Calculate place relative to viewport heart
// Vary from -1 to 1 as ingredient strikes by way of viewport
const elementCenter = elementLeft + this.bounds.width / 2;
const viewportCenter = innerWidth / 2;
const distance = (elementCenter - viewportCenter) / innerWidth;
// Apply parallax impact
const parallaxValue = distance * 0.4;
this.materials.uniforms.uParallax.worth = parallaxValue;
}
}Breaking it down:
Step 1: Calculate ingredient place
const elementLeft = this.bounds.left - scroll;
const elementRight = elementLeft + this.bounds.width;We get the ingredient’s left and proper edges relative to the viewport, accounting for scroll.
Step 2: Test visibility
if (elementRight >= 0 && elementLeft <= innerWidth)Solely calculate parallax for photographs at the moment seen on display screen. Small optimization.
Step 3: Calculate distance from heart
const elementCenter = elementLeft + this.bounds.width / 2;
const viewportCenter = innerWidth / 2;
const distance = (elementCenter - viewportCenter) / innerWidth;We discover the ingredient’s heart level, examine it to the viewport heart, and normalize the end result by dividing by viewport width.
This provides us a worth that:
- Is unfavourable when the ingredient is left of heart
- Is 0 when the ingredient is centered
- Is optimistic when the ingredient is correct of heart
- Ranges roughly from -1 to 1
Step 4: Apply depth
const parallaxValue = distance * 0.4;We multiply by 0.4 to manage the depth. That is your “parallax power” knob:
0.2→ refined impact0.4→ what we’re utilizing0.6→ dramatic impact
Replace the Render Technique
Don’t neglect to name updateParallax each body:
render(scroll: quantity) {
this.updateParallax(scroll);
this.updatePosition(scroll);
}Making use of Parallax within the Shader
Now replace the fragment shader to make use of the parallax worth:
// src/shaders/mediaFragment.glsl
precision highp float;
various vec2 vUv;
uniform sampler2D uTexture;
uniform vec2 uResolution;
uniform vec2 uImageResolution;
uniform float uParallax;
vec2 coverUv(vec2 uv, vec2 decision, vec2 imageResolution) {
vec2 ratio = vec2(
min((decision.x / decision.y) / (imageResolution.x / imageResolution.y), 1.0),
min((decision.y / decision.x) / (imageResolution.y / imageResolution.x), 1.0)
);
return vec2(
uv.x * ratio.x + (1.0 - ratio.x) * 0.5,
uv.y * ratio.y + (1.0 - ratio.y) * 0.5
);
}
void important() {
vec2 uv = coverUv(vUv, uResolution, uImageResolution);
// Apply parallax impact by shifting UVs horizontally
uv.x += uParallax * 1.0;
// Scale UVs to create house for parallax motion
// That is like making the picture smaller inside its body
uv -= 0.5;
uv *= 0.85; // Scale all the way down to 85% (leaving 15% house for motion)
uv += 0.5;
vec3 col = texture2D(uTexture, uv).rgb;
gl_FragColor = vec4(col, 1.);
}What’s taking place right here:
Step 1: Shift UVs
uv.x += uParallax * 1.0;We offset the UVs horizontally by the parallax worth. Because the picture strikes by way of the viewport:
- Left of heart →
uParallaxis unfavourable → texture shifts left - Proper of heart →
uParallaxis optimistic → texture shifts proper
The * 1.0 multiplier controls how a lot the feel strikes. You may alter this for stronger/weaker results.
Step 2: Create motion house
uv -= 0.5;
uv *= 0.85;
uv += 0.5;That is the shader equal of our 2D CSS trick (125% width, -12.5% offset).
We:
- Heart the UVs round (0, 0) by subtracting 0.5
- Scale them all the way down to 85% (making the feel successfully smaller)
- Shift again to (0.5, 0.5) to re-center
The end result: the feel is now 85% of its regular measurement, with 15% of empty house round it. After we shift the UVs with uv.x += uParallax, we’re shifting inside that 15% buffer.
Why 0.85?
This worth controls how a lot “room” the feel has to maneuver:
0.9→ much less house, extra refined parallax (however danger of exhibiting edges)0.85→ good stability (what we’re utilizing)0.8→ more room, stronger parallax doable (however texture seems extra zoomed out)
You may alter this primarily based in your parallax depth. Simply ensure that the parallax shift doesn’t exceed the obtainable house, otherwise you’ll see the feel edges.
The Full Image
Now you will have:
- JavaScript calculating every picture’s place within the viewport
- JavaScript passing a normalized parallax worth to the shader
- Shader shifting the feel’s UVs primarily based on that worth
- Shader working inside a scaled-down UV house (the “buffer zone”)
All of this occurs on the GPU, each body, for each pixel. No DOM manipulation, no structure recalculations, simply pure, {smooth}, GPU-accelerated rendering.
Evaluating 2D vs WebGL Parallax
2D (DOM):
- CSS creates bodily house (125% width)
- JS calculates place through
getBoundingClientRect() - JS applies
remodel: translateX()to every picture - Browser composites on GPU (hopefully)
WebGL:
- Shader creates UV house (0.85 scale)
- JS calculates place through
getBoundingClientRect() - JS passes worth to uniform
- Shader shifts UVs and samples texture
- The whole lot rendered on GPU
The tip end result appears to be like comparable, however the WebGL model:
- Offloads extra work to the GPU
- Avoids touching the DOM each body
- Handles extra photographs with higher efficiency
- Opens the door to extra advanced shader results
Tweaking Values with lil-gui (Elective)
Need to experiment with the parallax impact and actually perceive how every worth impacts the end result? Let’s add lil-gui, a light-weight GUI controller.
npm set up lil-guiAdd this to your GL.ts:
import * as THREE from "three";
import { GLMedia } from "./GLMedia";
import GUI from "lil-gui";
export class GL {
// ... current properties
gui: GUI;
params = {
parallaxIntensity: 0.4,
uvScale: 0.85,
shaderMultiplier: 1.0,
};
constructor() {
// ... current setup
this.setupGUI();
}
setupGUI() {
this.gui = new GUI();
this.gui
.add(this.params, "parallaxIntensity", 0, 1, 0.01)
.title("Parallax Depth")
.onChange((worth: quantity) => {
this.allMedias.forEach((media) => {
media.parallaxIntensity = worth;
});
});
this.gui
.add(this.params, "uvScale", 0.7, 1.0, 0.01)
.title("UV Scale (Buffer)")
.onChange((worth: quantity) => {
this.allMedias.forEach((media) => {
media.materials.uniforms.uUvScale.worth = worth;
});
});
this.gui
.add(this.params, "shaderMultiplier", 0, 2, 0.1)
.title("Shader Multiplier")
.onChange((worth: quantity) => {
this.allMedias.forEach((media) => {
media.materials.uniforms.uShaderMultiplier.worth = worth;
});
});
}
}Replace GLMedia.ts to make use of these values:
export class GLMedia {
parallaxIntensity = 0.4;
createMesh() {
this.materials = new THREE.ShaderMaterial({
uniforms: {
uTexture: { worth: null },
uResolution: { worth: new THREE.Vector2(/* ... */) },
uImageResolution: { worth: new THREE.Vector2(1, 1) },
uParallax: { worth: 0 },
uUvScale: { worth: 0.85 },
uShaderMultiplier: { worth: 1.0 },
},
// ... shaders
});
}
updateParallax(scroll: quantity) {
// ... current code
const parallaxValue = distance * this.parallaxIntensity;
this.materials.uniforms.uParallax.worth = parallaxValue;
}
}And replace the fragment shader to make use of the uniforms:
uniform float uParallax;
uniform float uUvScale;
uniform float uShaderMultiplier;
void important() {
vec2 uv = coverUv(vUv, uResolution, uImageResolution);
uv.x += uParallax * uShaderMultiplier;
uv -= 0.5;
uv *= uUvScale;
uv += 0.5;
vec3 col = texture2D(uTexture, uv).rgb;
gl_FragColor = vec4(col, 1.);
}Now you may tweak values in real-time and see precisely how they have an effect on the parallax:
- Parallax Depth: Controls how a lot JS calculates (the gap multiplier)
- UV Scale: Controls the buffer house (decrease = more room for motion)
- Shader Multiplier: Controls how a lot the shader shifts UVs
Mess around! You’ll shortly perceive the connection between these values and the visible impact.
(Elective) Train: Including Contact Assist
Need to take this additional? Right here’s a problem: add contact/drag help so customers can scroll the gallery by swiping.
Hints:
- Pay attention for
touchstart,touchmove, andtouchendoccasions - Monitor the contact delta and add it to
scroll.goal - Don’t neglect to deal with
pointerdown,pointermove, andpointerupfor each mouse and contact - Add momentum/inertia for a extra pure really feel
This may make the gallery work fantastically on cellular units and add an additional layer of interactivity.
Conclusion
Once I began constructing this gallery, I wished to transcend the everyday “right here’s the way to do horizontal scroll with parallax” tutorial. There are already loads of these on the market, they usually largely concentrate on the DOM-based method.
What impressed me, and what I hope this tutorial conveys, is how efficiency and approach can essentially change the texture of an internet site. The distinction between a janky 30fps parallax and a buttery {smooth} 60fps GPU accelerated one isn’t simply technical, it’s visceral. Customers really feel it instantly, even when they'll’t articulate why.
Camille Mormal’s portfolio is an ideal instance of this. The fluidity isn’t unintended, it’s the results of rendering every thing in WebGL and letting the GPU do what it does greatest. That’s the method I wished to interrupt down right here: not simply “the way to make it work,” however “the way to make it really feel proper.”
We’ve coated:
- Customized {smooth} scrolling with lerp and easing
- 2D parallax with CSS sizing and JavaScript transforms
- The important connection between CSS buffer house and JavaScript motion
- WebGL fundamentals with DOM/3D synchronization
- Shader-based parallax that runs completely on the GPU
- Efficiency issues and when to optimize
The 2D model is nice for easy galleries. The WebGL model is for if you need to push additional if you need that additional fluidity, if you need to deal with dozens of photographs with out breaking a sweat, or if you need to add extra advanced shader results down the road.
I hope this deep dive into each approaches offers you not simply copy paste code, however an actual understanding of what’s taking place beneath the hood. That’s what issues. That’s what enables you to adapt these methods to your personal tasks and push them even additional.
Now go construct one thing stunning.
