Back to Blog Page
Frontend Development

How to Use The JavaScript Intersection Observer API

How to Use The JavaScript Intersection Observer API

Written by Kolade Chris | Sep 21, 2024 | #JavaScript #WebDev | 5 minutes Read

In simple terms, the JavaScript intersection observer API is a tool that lets you know when an element on a webpage is visible on the screen.

The API makes it easy to detect when elements enter or leave the viewport, removing the need for complex scroll event handling. This allows developers to execute actions based on the visibility of elements within the viewport.

The said actions include lazy-loading images, implementing infinite scrolling, or triggering animations when elements become visible.

Keep reading as I walk you through the syntax of the Intersection Observer API and share three examples to help you start using it in your projects.

Basic Syntax of the Intersection Observer API

Below is the basic syntax of the intersection observer API:

1
const observerVariable = new IntersectionObserver(
2
callbackFunc,
3
observerOptions
4
);
5
6
observerVariable.observe(targetElement);

Let’s look at each of the items in the syntax:

  • InterSectionObserver() is the API itself. It’s a constructor, so you need to initialize it with the new keyword. It takes two parameters – a callback function and an optional options object.
  • callbackFunc is the callback function is the function that will be called whenever the observed element enters or exits the viewport
  • observerOptions is an object that allows you to specify the root element for observing, margins around the root, and visibility thresholds to trigger the callback.
  • observerVariable is the constant you have to assign the instance of the IntersectionObserver constructor to. It’s an identifier (a name), so you can call it whatever you want.
  • observerVariable.observe(targetElement) is the line that will finally do the slam dunk with the observe() method. The targetElement is the element you want to do something with.

Let’s look at 3 examples of the ways you can use the intersection observer API:

  • the first example will focus on observing a single element and using the basic syntax as is
  • the second will observe one element too but make the syntax clearer
  • the third will show you how to observe multiple elements without defining separate observers for them

Example 1: Using the Intersection Observer API to Observe a Single Element

Let’s observe the h1 element in the HTML code below:

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
<meta charset="UTF-8" />
5
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
<title>JS Intersection Observer API</title>
7
<link rel="stylesheet" href="styles.css" />
8
</head>
9
<body>
10
<h1 class="heading">JavaScript Intersection Observer API</h1>
11
150 collapsed lines
12
<p>
13
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
14
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
15
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
16
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
17
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
18
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
19
error est, consectetur exercitationem nihil optio voluptate pariatur.
20
Voluptatem provident autem, officiis qui quod porro facilis libero
21
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
22
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
23
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
24
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
25
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
26
perferendis tempora minima, commodi asperiores quae recusandae aliquam
27
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
28
unde ratione.
29
</p>
30
<p>
31
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
32
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
33
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
34
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
35
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
36
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
37
error est, consectetur exercitationem nihil optio voluptate pariatur.
38
Voluptatem provident autem, officiis qui quod porro facilis libero
39
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
40
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
41
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
42
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
43
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
44
perferendis tempora minima, commodi asperiores quae recusandae aliquam
45
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
46
unde ratione.
47
</p>
48
<p>
49
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
50
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
51
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
52
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
53
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
54
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
55
error est, consectetur exercitationem nihil optio voluptate pariatur.
56
Voluptatem provident autem, officiis qui quod porro facilis libero
57
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
58
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
59
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
60
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
61
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
62
perferendis tempora minima, commodi asperiores quae recusandae aliquam
63
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
64
unde ratione.
65
</p>
66
<p>
67
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
68
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
69
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
70
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
71
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
72
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
73
error est, consectetur exercitationem nihil optio voluptate pariatur.
74
Voluptatem provident autem, officiis qui quod porro facilis libero
75
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
76
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
77
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
78
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
79
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
80
perferendis tempora minima, commodi asperiores quae recusandae aliquam
81
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
82
unde ratione.
83
</p>
84
<p>
85
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
86
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
87
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
88
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
89
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
90
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
91
error est, consectetur exercitationem nihil optio voluptate pariatur.
92
Voluptatem provident autem, officiis qui quod porro facilis libero
93
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
94
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
95
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
96
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
97
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
98
perferendis tempora minima, commodi asperiores quae recusandae aliquam
99
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
100
unde ratione.
101
</p>
102
103
<div class="box"></div>
104
105
<p>
106
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
107
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
108
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
109
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
110
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
111
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
112
error est, consectetur exercitationem nihil optio voluptate pariatur.
113
Voluptatem provident autem, officiis qui quod porro facilis libero
114
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
115
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
116
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
117
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
118
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
119
perferendis tempora minima, commodi asperiores quae recusandae aliquam
120
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
121
unde ratione.
122
</p>
123
124
<p>
125
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
126
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
127
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
128
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
129
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
130
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
131
error est, consectetur exercitationem nihil optio voluptate pariatur.
132
Voluptatem provident autem, officiis qui quod porro facilis libero
133
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
134
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
135
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
136
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
137
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
138
perferendis tempora minima, commodi asperiores quae recusandae aliquam
139
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
140
unde ratione.
141
</p>
142
143
<p>
144
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
145
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
146
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
147
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
148
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
149
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
150
error est, consectetur exercitationem nihil optio voluptate pariatur.
151
Voluptatem provident autem, officiis qui quod porro facilis libero
152
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
153
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
154
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
155
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
156
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
157
perferendis tempora minima, commodi asperiores quae recusandae aliquam
158
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
159
unde ratione.
160
</p>
161
162
<p>
163
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Dolore nihil
164
veniam ipsa numquam totam eligendi eaque error eum, voluptates enim
165
laudantium sapiente, hic unde inventore a dolorem adipisci consequuntur
166
assumenda tempora nobis iste voluptate officiis nesciunt. Neque numquam
167
iusto ipsum quos tempora delectus expedita autem eaque facere voluptate
168
rerum ab possimus, explicabo quasi! Culpa asperiores temporibus dicta
169
error est, consectetur exercitationem nihil optio voluptate pariatur.
170
Voluptatem provident autem, officiis qui quod porro facilis libero
171
molestias error dolorum, ad nihil suscipit recusandae, aliquid animi. A,
172
temporibus? Optio fugit sed natus recusandae fugiat veniam illo hic
173
aperiam officia inventore ea molestiae itaque qui, deleniti officiis?
174
Aliquid fuga nisi veritatis commodi doloribus sit rerum alias adipisci
175
natus. Incidunt totam reprehenderit atque deserunt veritatis iste
176
perferendis tempora minima, commodi asperiores quae recusandae aliquam
177
error quisquam ab eveniet quam provident, possimus natus, necessitatibus
178
unde ratione.
179
</p>
180
181
<div class="circle"></div>
182
183
<script src="script.js"></script>
184
</body>
185
</html>

Here’s the CSS for the HTML:

1
* {
2
margin: 0;
3
padding: 0;
4
box-sizing: border-box;
5
}
6
7
body {
8
max-width: 1000px;
9
margin: 0 auto;
10
transition: 2s ease-in-out;
11
}
12
13
h1 {
14
margin: 1rem 0;
15
}
26 collapsed lines
16
17
p {
18
margin: 4rem 0;
19
line-height: 1.5;
20
}
21
22
@keyframes rotate {
23
from {
24
transform: rotate(0deg);
25
}
26
to {
27
transform: rotate(360deg);
28
}
29
}
30
31
.animate {
32
animation: rotate 2s linear infinite;
33
}
34
35
.box {
36
height: 400px;
37
width: 400px;
38
background-color: #2ecc71;
39
transition: background-color 0.3s;
40
}
41
42
.circle {
43
height: 400px;
44
width: 400px;
45
background-color: #2ecc71;
46
border-radius: 49%;
47
}

To start observing the h1 element, you need to reference it with querySelector [or your favourite method of doing so].

I’ll do that by targeting the .heading class of the h1:

1
const h1 = document.querySelector('.heading');

The next thing to do is to create a new instance of the intersection observer API and pass in the callback and the options.

I’ll start by defining an observerh1 variable set to a new instance of IntersectionObserver(). I will also start observing the h1 element straight away:

1
const observeh1 = new IntersectionObserver();
2
3
observeh1.observe(h1);

For the callback, I’m going to start with an entries parameter for an arrow function, I’ll also log the entries parameter to the console:

1
const observeh1 = new IntersectionObserver((entries) => {
2
console.log(entries);
3
});

h1 observed in the console

You can see that the target is indeed the h1 element with the class heading.

There’s also an isIntersecting property you can use to check if the target element is in the viewport.

Let’s loop through the entries (only h1 for now, actually) and do something using the isIntersecting property based on whether the h1 is in the viewport or not:

1
const observeh1 = new IntersectionObserver((entries) => {
2
entries.forEach((entry) => {
3
if (entry.isIntersecting) {
4
console.log('h1 is in the viewport!');
5
} else {
6
console.log('h1 is out of the viewport!');
7
}
8
});
9
});
10
11
observeh1.observe(h1);

Here’s the result:

h1 observed without styling

Isn’t that what we all call “cool”?

You can take things further and assign some style to the target element once it’s in the viewport:

1
const observeh1 = new IntersectionObserver((entries) => {
2
entries.forEach((entry) => {
3
if (entry.isIntersecting) {
4
console.log('h1 is in the viewport!');
5
entry.target.style.backgroundColor = '#3498db';
6
entry.target.style.fontSize = '4rem';
7
} else {
8
console.log('h1 is out of the viewport!');
9
entry.target.style.backgroundColor = 'unset';
10
entry.target.style.fontSize = 'unset';
11
}
12
});
13
});

For the optional options object, I’ll pass in the following:

1
const observeh1 = new IntersectionObserver(
2
(entries) => {
3
entries.forEach((entry) => {
4
if (entry.isIntersecting) {
5
console.log('h1 is in the viewport!');
6
entry.target.style.backgroundColor = '#3498db';
7
entry.target.style.fontSize = '4rem';
8
} else {
9
console.log('h1 is out of the viewport!');
10
entry.target.style.backgroundColor = '#2ecc71';
11
entry.target.style.fontSize = 'unset';
12
}
13
});
14
},
15
{
16
root: null,
17
rootMargin: '200px',
18
threshold: 0.5,
19
}
20
);
21
22
observeh1.observe(h1);

Don’t be confused. Here’s what those mean:

  • a root of null means the observer will use the entire browser viewport as the area to watch for visibility changes
  • a rootMargin of 200px means the observer will add an extra 200px around the root area (the entire browser viewport for this example) , so elements will be considered visible even when they are still 200 pixels outside the root
  • a threshold of 0.5 means 50% of the element needs to be visible before the observer callback will be triggered

This is what things look like now:

h1 observed with styling

In case you’re doubting it, things really do change if you inspect the h1 element:

Confirm h1 intersection

Example 2: Defining the Callback and Options Outside of the IntersectionObserver Constructor

You don’t have to fill up the IntersectionObserver constructor with the callback function and options parameters. You can define both outside and reference them inside the constructor.

To show you how to do this, let’s observe the box inside the HTML code. Here’s the fully commented code that shows you what’s going on:

1
const box = document.querySelector('.box');
2
3
// Define the callback function outside the constructor
4
const observerCallback = (entries) => {
5
entries.forEach((entry) => {
6
if (entry.isIntersecting) {
7
// Once the box is within the viewport:
8
9
// 1. Log "Box is in the viewport!" to the console
10
console.log('Box is in the viewport!');
11
// 2. Change the background color to blue
12
entry.target.style.backgroundColor = '#3498db';
13
// 3. Add a class that animates the box
14
entry.target.classList.add('animate');
15
} else {
16
// Once the box is outside the viewport:
17
18
// 1. Log "Box is out of the viewport!" to the console
19
console.log('Box is out of the viewport!');
20
// 2. Change the background color to green
21
entry.target.style.backgroundColor = '#2ecc71';
22
// 3. Remove the class that animates the box
23
entry.target.classList.remove('animate');
24
}
25
});
26
};
27
28
// Define the options
29
const observerOptions = {
30
root: null,
31
rootMargin: '0px',
32
threshold: 0.5,
33
};
34
35
// Define the constructor and reference the callback function and the options
36
const observer = new IntersectionObserver(observerCallback, observerOptions);
37
38
// Observe the box
39
observer.observe(box);

Here’s what’s happening to the box now:

Box intersecting

Pardon the interruption

Subscribe to my newsletter for coding tips, videos from reputable sources, articles from OG tech authors, and a ton of other goodies.

No BS. No fluff. Just pure software development goodies on a Sunday every week.

Back to the intersection observer API

Example 3: How to Observe Multiple Elements with the IntersectionObserver API

Observing multiple element with the IntersectionObserver API works a bit differently.

To do that, you need to do these:

  • select your elements from the HTML with querySelectorAll() or other relevant methods
  • define your callback and options as usual
  • supply the callback and the options parameters into the IntersectionObserver API constructor
  • loop through the target elements with forEach and observe them inside it

Here’s how I was able to observe the circle and box on the page:

1
// select the target box and the circle with querySelectorAll()
2
const targets = document.querySelectorAll('.box, .circle');
3
4
//define the callback function
5
const observerCallback = (entries) => {
6
entries.forEach((entry) => {
7
// Once the targets are within the viewport:
8
if (entry.isIntersecting) {
9
// 1. Log "[target] is in the viewport" to the console
10
console.log(`${entry.target.className} is in the viewport!`);
11
// 2. Add a blue background color to the targets
12
entry.target.style.backgroundColor = '#3498db';
13
// 3. Animate the target
14
entry.target.classList.add('animate');
15
} else {
16
// Once the targets are out of the viewport:
17
18
// 1. Log "[target] is out of the viewport" to the console
19
console.log(`${entry.target.className} is out of the viewport!`);
20
// 2. Add a green background color to the targets
21
entry.target.style.backgroundColor = '#2ecc71';
22
// 3. Remove the animation from the target
23
entry.target.classList.remove('animate');
24
}
25
});
26
};
27
28
// define the options
29
const observerOptions = {
30
root: null,
31
rootMargin: '0px',
32
threshold: 0.5,
33
};
34
35
// pass the callback and options into the constructor
36
const observer = new IntersectionObserver(observerCallback, observerOptions);
37
38
// loop through the selected targets and observe them
39
targets.forEach((target) => observer.observe(target));

Here are the box and the circle intersecting:

Box and circle intersecting

You can see that in the second and third examples, the animation is only triggered once the user scrolls to them. This can be useful when you’re dealing with expensive animations or other processes.

The Intersection Observer API improves user experience by ensuring elements load and animate only when needed, reducing unnecessary processing and enhancing performance. It’s an excellent tool for creating responsive, efficient, and engaging web interactions.

Start using the IntersectionObserver API in your projects now!