DEV Community: itihon

Using the same validation logic on the client and server side with Isomorphic-validation.

itihon — Wed, 07 May 2025 11:04:12 +0000

In this post I want to briefly describe the usage of Isomorphic-validation, a javascript validation library that was intended to be used on the client and server side and make the process of validating user input seamless across your application.

In the two previous posts I covered some aspects of using this library on the client side by creating a sign-in and sign-up form:

Here I will show why this library is actually isomorphic. I'm going to incorporate that sign-in and sign-up examples into a simple Node.js application.

If you want to run this project locally it is there:

View on Github

0. Setting up the project

First, I created the following folder structure:

.
⊟── public
│   ⊞─── bundles
│   ├── signin.html
│   ├── signup.html
│   └── style.css
├── repository.js
⊟─── validation
    ⊞── profiles
    ⊞── ui
    ⊞── validations
    ⊞── validators

repository.js

// repository.js

/**
 * Mock repository
 */

const existingEmails = new Map([
  ['ww@ww.ww', 1],
  ['xx@xx.xx', 2],
  ['yy@yy.yy', 3],
  ['zz@zz.zz', 4],
]);

export default {
  async getUserIdBy({ email = '' }) {
    return existingEmails.get(email);
  },
};

public/signin.html

<!-- public/signin.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Sign in</title>
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <form action="signin" method="post" name="signinForm" autocomplete="off">
      <h2>Sign in</h2>

      <label class="form-field" for="email">
        <input type="text" name="email" id="email" required />
        <span class="field-title">E-mail</span>
      </label>

      <label class="form-field" for="password">
        <input type="password" name="password" id="password" required />
        <span class="field-title">Password</span>
      </label>

      <input type="submit" name="submitBtn" disabled />
    </form>
    <script type="module" src="bundles/signin.js"></script>
  </body>
</html>

public/signup.html

<!-- public/signup.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Sign up</title>
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <form action="signup" method="post" name="signupForm" autocomplete="off">
      <h2>Sign up</h2>

      <label class="form-field" for="email">
        <input type="text" name="email" id="email" required />
        <span class="field-title">E-mail</span>
      </label>

      <label class="form-field" for="password">
        <input type="password" name="password" id="password" required />
        <span class="field-title">Password</span>
      </label>

      <label class="form-field" for="pwdConfirm">
        <input type="password" name="pwdConfirm" id="pwdConfirm" required />
        <span class="field-title">Password confirmation</span>
      </label>

      <input type="submit" name="submitBtn" disabled />
    </form>
    <script type="module" src="bundles/signup.js"></script>
  </body>
</html>

public/style.css

// public/style.css

* {
  padding: 0;
  margin: 0;
  box-sizing: border-box;
  font-family: Helvetica;
}

body {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
  background-color: lightslategray;
}

h2 {
  text-align: center;
  width: 100%;
}

form {
  display: flex;
  flex-wrap: wrap;
  gap: 48px;
  justify-content: flex-start;
  align-items: center;
  width: min-content;
  padding-inline: 24px;
  padding-block: 32px;
  border: 1px solid slategray;
  border-radius: 2px;

  background: rgb(255,255,255);
  background: linear-gradient(123deg, rgba(255,255,255,1) 24%, rgba(244,250,255,1) 51%, rgba(255,255,255,1) 77%);
}

label {
  padding: 4px;
  background-color: white;
}

input { 
  height: 32px;
  width: 100%;
  border: none;
  background: none;
  outline: none;
  font-size: 16px;
}

input[type="submit"] {
  height: 42px;
  border: 1px solid lightslategray;
  background-color: slategray;
  color: white;
  transition: opacity .1s;
}

input[type="submit"]:disabled {
  opacity: .5;
  cursor: not-allowed;
}

input[type="submit"]:not(:disabled):hover {
  filter: brightness(1.1);
}

.form-field {
  width: 220px;
  position: relative;
  border: 1px solid slategray;
  border-radius: 2px;
  cursor: text;
}

.field-title {
  position: absolute;
  top: 0;
  padding-block: 4px;
  display: grid;
  align-items: center;
  height: 100%;
  color: slategray;
  transition: font-size .1s, height .1s ease-out;
}

.form-field > input:valid + .field-title {
  font-size: 12px;
  height: 20px;
}

.form-field > input:valid {
  padding-top: 14px; 
}

I didn't want to set up the whole database for this simple demonstration, so I just created a mock repository file with registerd e-mail addresses in order to implement the checking an e-mail for existance functionality on the sign-up form.

1. Preparing validators

.
⊞─── public
├── repository.js
⊟─── validation
    ⊞── profiles
    ⊞── ui
    ⊞── validations
    ⊟── validators
        ├── is-email.js
        ├── is-email-not-registered.js
        ├── is-email-not-registered-s.js
        ├── is-max-length.js
        ├── is-min-length.js
        ├── is-password-confirmed.js
        └── is-strong-password.js

validation/validators/is-email.js

// validation/validators/is-email.js

import { Predicate } from 'isomorphic-validation';
import isEmail from 'validator/es/lib/isEmail';

export default Predicate(isEmail, {
  err: 'Must be in the E-mail format.',
});

validation/validators/is-email-not-registered.js

// validation/validators/is-email-not-registered.js

import { Predicate } from 'isomorphic-validation';

const isEmailNotRegistered = value =>
  fetch('/checkemail', { method: 'post', body: new URLSearchParams({ email: value }) }).then(res => res.json());

export default Predicate(isEmailNotRegistered, {
  err: 'The E-mail must not be already registered.',
  waitMsg: 'Wait a moment, we are checking your E-mail.',
});

validation/validators/is-email-not-registered-s.js

// validation/validators/is-email-not-registered-s.js

import repository from '../../repository.js';

const isEmailNotRegisteredS = async value => !(await repository.getUserIdBy({ email: value }));

export default isEmailNotRegisteredS;

validation/validators/is-max-length.js

// validation/validators/is-max-length.js

import { Predicate } from 'isomorphic-validation';
import isLength from 'validator/es/lib/isLength';

const isMaxLength = max =>
  Predicate(value => isLength(value, { max }), {
    err: `Should not be longer than ${max} characters.`,
  });

export default isMaxLength;

validation/validators/is-min-length.js

// validation/validators/is-min-length.js

import { Predicate } from 'isomorphic-validation';
import isLength from 'validator/es/lib/isLength';

const isMinLength = min =>
  Predicate(value => isLength(value, { min }), {
    err: `Must be at least ${min} characters long.`,
  });

export default isMinLength;

validation/validators/is-password-confirmed.js

// validation/validators/is-password-confirmed.js

import { Predicate } from 'isomorphic-validation';
import equals from 'validator/es/lib/equals';

export default Predicate(equals, {
  err: 'Password and password confirmation must be the same',
});

validation/validators/is-strong-password.js

// validation/validators/is-strong-password.js

import { Predicate } from 'isomorphic-validation';
import isStrongPassword from 'validator/es/lib/isStrongPassword';

export default Predicate(isStrongPassword, {
  err: 'Min. 8 symbols, 1 capital letter, 1 number, 1 special character',
});

Here I'm using validators from the library validator.js. You can use validators provided by other libraries or write your own. They only have to return a Boolean value or a Promise that fullfils with a Boolean value. I wrap them in Predicate in order to pass error messages along with them. If your project requires internationalization you can pass translation keys instead. See an example of usage with i18next library.

There are two validators that will be checking an e-mail registration, one is-email-not-registered.js which will be executed on the client side and make a request to the server, and is-email-not-registered-s.js which will be making a request to the database on the server, that is in our case to the mock repository.

2. Preparing validations

.
⊞─── public
├── repository.js
⊟─── validation
    ⊞── profiles
    ⊞── ui
    ⊟── validations
    │   ├── email.js
    │   └── password.js
    ⊞─── validators

validation/validations/email.js

// validation/validations/email.js

import { Validation } from 'isomorphic-validation';
import isEmail from '../validators/is-email.js';
import isMinLength from '../validators/is-min-length.js';
import isMaxLength from '../validators/is-max-length.js';

const emailV = Validation()
  .constraint(isMinLength(8), { next: false })
  .constraint(isMaxLength(48), { next: false })
  .constraint(isEmail, { next: false });

export default emailV;

validation/validations/password.js

// validation/validations/password.js

import { Validation } from 'isomorphic-validation';
import isStrongPassword from '../validators/is-strong-password.js';

const passwordV = Validation().constraint(isStrongPassword);

export default passwordV;

Here I'm creating two Validation objects for e-mail and password fields with validators that will be shared by both forms. We do not duplicate the validation logic even though the sign-up form differs from the sign-in form in the way that it requires additional validators for checking an e-mail registration and checking password and password confirmation equality. We will add them in the following steps.

At this point our dependency graph looks like this:

3. Creating UI effects

.
⊞─── public
├── repository.js
⊟─── validation
    ⊞── profiles
    ⊟── ui
    │   └── apply-effects.js
    ⊞── validations
    ⊞── validators

validation/ui/apply-effects.js

// validation/ui/apply-effects.js

import { Validation } from 'isomorphic-validation';
import { applyAccess, applyOutline, applyBox, renderFirstError, renderProperty } from 'isomorphic-validation/ui';

const delayedOutline = {
  false: { delay: 2000, value: '2px solid lightpink' },
  true: { delay: 500, value: '' },
};

const delayedAccess = {
  true: { delay: 600 },
};

const disabledAccess = {
  false: { value: true },
  true: { value: true },
};

const remainedOutline = {
  false: { delay: 20000, value: '' },
  true: { delay: 20000, value: '' },
};

const changedOutline = {
  false: { delay: 500, value: '2px solid lightpink' },
  true: { delay: 500, value: '' },
};

const editIcon = {
  false: { value: '🖊' },
  true: { value: '🖊' },
  position: 'LEVEL_RIGHT',
};

const loadImg = `
<img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgdmlld0JveD0iMCAwIDUwIDUwIj4KICA8Y2lyY2xlIGN4PSIyNSIgY3k9IjI1IiByPSIyMCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjNjBBNUZBIiBzdHJva2Utd2lkdGg9IjMiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWRhc2hhcnJheT0iNjAgMTIwIj4KICAgIDxhbmltYXRlVHJhbnNmb3JtIGF0dHJpYnV0ZU5hbWU9InRyYW5zZm9ybSIgdHlwZT0icm90YXRlIiBmcm9tPSIwIDI1IDI1IiB0bz0iMzYwIDI1IDI1IiBkdXI9IjFzIiByZXBlYXRDb3VudD0iaW5kZWZpbml0ZSI+PC9hbmltYXRlVHJhbnNmb3JtPgogIDwvY2lyY2xlPgo8L3N2Zz4=" alt="SVG Image" />
`;

const loadIcon = {
  false: { delay: 1000, value: loadImg },
  true: { delay: 1000, value: loadImg },
  position: 'LEVEL_RIGHT',
};

const validIcon = {
  false: { delay: 1000, value: '' },
  true: { delay: 500, value: '✔' },
  position: 'LEVEL_RIGHT_BESIDE',
  style: { color: 'green', left: '-8px' },
};

const errMsg = {
  false: { delay: 2000, value: renderFirstError('err') },
  position: 'BELOW_CENTER',
  mode: 'MAX_SIDE',
  style: { color: 'firebrick', fontSize: '12px', padding: '4px' },
};

const changedMsg = {
  false: { delay: 500, value: renderFirstError('err') },
  position: 'BELOW_CENTER',
  mode: 'MAX_SIDE',
  style: { color: 'firebrick', fontSize: '12px', padding: '4px' },
};

const waitMsg = {
  false: { delay: 1000, value: renderProperty('waitMsg') },
  true: { delay: 1000, value: renderProperty('waitMsg') },
  position: 'BELOW_CENTER',
  mode: 'MAX_SIDE',
  style: { color: 'steelblue', fontSize: '12px', padding: '4px' },
};

const applyEffects = validationProfile => {
  const [form, groupingValidation] = validationProfile;

  form.addEventListener(
    'input',
    Validation.group(
      groupingValidation.validations.map((validation, idx) => {
        const iconEID = form[idx].name + 'icon';
        const errMsgEID = form[idx].name + 'error';
        const outlineEID = form[idx].name + 'outline';
        const formField = form[idx].parentNode;

        return validation
          .started(applyOutline(formField, remainedOutline, outlineEID))
          .validated(applyOutline(formField, delayedOutline, outlineEID))
          .changed(applyOutline(formField, changedOutline, outlineEID))
          .started(applyBox(formField, editIcon, iconEID))
          .started(applyBox(formField, loadIcon, iconEID))
          .validated(applyBox(formField, validIcon, iconEID))
          .changed(applyBox(formField, validIcon, iconEID))
          .started(applyBox(formField, waitMsg, errMsgEID))
          .validated(applyBox(formField, errMsg, errMsgEID))
          .changed(applyBox(formField, changedMsg, errMsgEID));
      }),
    )
      .started(applyAccess(form.submitBtn, disabledAccess))
      .validated(applyAccess(form.submitBtn, delayedAccess)),
  );
};

export default applyEffects;

Here I simply wrap the effects I demonstrated in the previous post's example in a function in order to apply them to both forms. Insted of using the library's UI effect functions, you can also create your own effects, make them a part of your components and use Validation or Predicate objects inside your components to connect validity states to your components' states.

4. Creating validation profiles

.
⊟── public
├── repository.js
⊟── validation
    ⊟── profiles
    │   ├── signin.js
    │   └── signup.js
    ⊞─── ui
    ⊞─── validations
    ⊞─── validators

validation/profiles/signin.js

// validation/profiles/signin.js

import { Validation } from 'isomorphic-validation';
import emailV from '../validations/email.js';
import passwordV from '../validations/password.js';
import applyEffects from '../ui/apply-effects.js';

/** Creating profiles */

const [signinForm, signinV] = Validation.profile('[name="signinForm"]', ['email', 'password'], [emailV, passwordV]);

/** UI effects */

applyEffects([signinForm, signinV]);

export { signinForm, signinV };

validation/profiles/signup.js

// validation/profiles/signup.js

import { Validation } from 'isomorphic-validation';
import emailV from '../validations/email.js';
import passwordV from '../validations/password.js';
import isPasswordConfirmed from '../validators/is-password-confirmed.js';
import isEmailNotRegistered from '../validators/is-email-not-registered.js';
import applyEffects from '../ui/apply-effects.js';

const pwdConfirm = Validation();

/** Creating profiles */

const [signupForm, signupV] = Validation.profile(
  '[name="signupForm"]',
  ['email', 'password', 'pwdConfirm'],
  [emailV, passwordV, pwdConfirm],
);

signupV.email.client.constraint(isEmailNotRegistered, { debounce: 5000 });

Validation.glue(signupV.password, signupV.pwdConfirm).constraint(isPasswordConfirmed);

/** UI effects */

applyEffects([signupForm, signupV]);

export { signupForm, signupV };

Here signin.js and signup.js will be entry points for a module bundler. This is the place where we apply UI effects. Also, signup.js is the place to add sign-up form specific validators:

// this validator will be added on the client side only
signupV.email.client.constraint(isEmailNotRegistered, { debounce: 5000 });

Validation.glue(signupV.password, signupV.pwdConfirm)
  .constraint(isPasswordConfirmed);

Now our dependency graph has the following structure:

We are using the same validations on both forms without duplicating.

5. Creating the server

.
├── index.js
⊞─── public
├── repository.js
⊟── validation
    ⊞─── profiles
    ⊞─── ui
    ⊞─── validations
    ⊞─── validators

index.js

// index.js

import express from 'express';
import bodyParser from 'body-parser';
import { signinV } from './validation/profiles/signin.js';
import { signupV } from './validation/profiles/signup.js';
import isEmailNotRegisteredS from './validation/validators/is-email-not-registered-s.js';

const app = express();
const urlencodeParser = bodyParser.urlencoded({ extended: false });

app.use(express.static('public'));

function signinHandler(req, res) {
  const { validationResult } = req;

  if (validationResult.isValid) {
    // check credentials and authorize the user
    // ...
    res.send('VALID');
  } else {
    // respond with the validation error
    // ...
    res.json(validationResult);
  }
}

function signupHandler(req, res) {
  const { validationResult } = req;

  if (validationResult.isValid) {
    // create an account
    // ...
    res.send('VALID');
  } else {
    // respond with the validation error
    // ...
    res.json(validationResult);
  }
}

function checkemailHandler(req, res) {
  res.json(req.validationResult.isValid);
}

const emailV = signupV.email.server.constraint(isEmailNotRegisteredS);

// validations are added as middlewares
app.post('/signin', urlencodeParser, signinV, signinHandler);
app.post('/signup', urlencodeParser, signupV, signupHandler);
app.post('/checkemail', urlencodeParser, emailV, checkemailHandler);

app.listen(8080, () => {
  console.log('Listening port 8080 ...');
});

On the server side, we use validations as Express middleware functions:

// here the .server property actually can be ommited
const emailV = signupV.email.server.constraint(isEmailNotRegisteredS);

// validations are added as middleware functions
app.post('/signin', urlencodeParser, signinV, signinHandler);
app.post('/signup', urlencodeParser, signupV, signupHandler);
app.post('/checkemail', urlencodeParser, emailV, checkemailHandler);

Final result

This is the final project's file system structure:

.
├── index.js
⊟── public
│   ⊞─── bundles
│   ├── signin.html
│   ├── signup.html
│   └── style.css
├── repository.js
⊟── validation
    ⊟── profiles
    │   ├── signin.js
    │   └── signup.js
    ⊟── ui
    │   └── apply-effects.js
    ⊟── validations
    │   ├── email.js
    │   └── password.js
    ⊟── validators
        ├── is-email.js
        ├── is-email-not-registered.js
        ├── is-email-not-registered-s.js
        ├── is-max-length.js
        ├── is-min-length.js
        ├── is-password-confirmed.js
        └── is-strong-password.js

The final dependency graph looks as the following:

Conclusion

What we achived so far:

No duplicates of validation logic across different forms with the same kind of fields.
No duplicates of validation logic between client and server.
All validation logic resides in one place which provides one source of truth.

If you read up to this point I'd like to know your opinion. What do you think about this approach? Does this library have the right to exist?

Handling asynchronous validators and mutually dependent fields using Isomorphic-validation library.

itihon — Sun, 04 May 2025 08:43:24 +0000

In the previous video Quick introduction to isomorphic-validation javascript library I demonstrated how quickly a user-friendly form can be created with UI effects connected to fields' validity states.

This is the second part in which I wanted to touch:

working with asynchronous validators;
conditional execution of validators;
handling password and password confirmation fields.

See the playground with the code from the video.

In this video I showed how a typical sign-up logic can be implemented such as checking an e-mail for being already occupied before submitting a form to create a new account.

Asynchronous validators are handled in the same way as synchronous, you only need to keep in mind that their execution takes time. We are simply playing with timings to create UI effects such as showing loaders/spinners while a request is being processed.

It is recommended to execute asynchronous validators conditionally when they are mixed with synchronous. For that, this library provides a feature that implements a simple logic: following validators can not be "valid" without the preceding being "valid", therefore it is not necessary to execute them. For example, it doesn't make sense to make a request to the server to check if an e-mail already registered if it doesn't conform to the E-mail format. Also, you don't have to worry about an async validator retrieving an irrelevant result if the user keeps typing while the request is being processed. The library handles such edge cases for you.

Handling fields with validity states depending on each other, such as password and password confirmation, is as easy as handling one field. Also, if you need to implement the logic of one field depending on another it is possible using an auxiliary Validation object.

Quick introduction to isomorphic-validation javascript library.

itihon — Sun, 27 Apr 2025 16:54:43 +0000

Isomorphic-validation is a Javascript library that allows writing the same validation logic once for client and server side, reuse it across different forms in your app, and offers a straightforward way of creating UI effects for indicating fields validity state.

In this video I wanted to show how easily client side form validation can be made with this library.

See the playground with the code from the video.

The concept is simple.

When running on the client side, a Validation object was designed to be used as an event handler. Validation objects can be grouped into another object so that a single Validation is in the "valid" state when all predicates return true (or a Promise with true in case they are asynchronous) and a grouping Validation is in the "valid" state when its all grouped Validation objects are in the "valid" state as well.

Validation and Predicate objects can be in one of the following states: started -> valid|invalid -> [changed] -> validated. You can think of it as a finite-state machine. A validation result at each state (except for valid and invalid) can be either true or false.

We simply need to declare effect values with desired delays for validation result states and associate UI effects with desired Validation and Predicate states. This approach makes for seemingly linear code, all asynchronicity and conditionals are abstracted away.

Detecting size and position change of a DOM element as a result of scroll, resize or zoom with IntersectionObserver.

itihon — Mon, 07 Apr 2025 12:52:22 +0000

I recently needed a solution to observe DOM element's position change in order to adjust another element accordingly, which might be placed beside as well as above or below the observed element. I didn't manage to find a solution that would satisfy my needs, under any circumstances reliably detect any kind of position change caused by scroll, resize, layout change or zoom and at the same time wouldn't hang in the background constantly polling the element. Luckily, I came across the article: Observing position-change of HTML elements using Intersection Observer. It describes a reliable method and gave me a good foundation to build up on.

As a result I implemented a hybrid approach that uses four IntersectionObserver instances to detect the beginning of element's bounding rectangle change in any direction, then runs a requestAnimationFrame loop as the element keeps moving. When element's bounds stop changing, it stops the loop and recreates the affected observers.

See Position observer demo.

In this article I want to describe some pitfalls discovered while experimenting with IntersectionObserver, when you shouldn't rely on intersectionRect and visualViewport size, and consider an alternative way when you can do without observing element's position change.

What for?

A typical use case, as I mentioned above, is when you have two DOM elements placed inside different parent containers (or maybe they come from different component libraries, or you are not allowed to modify any of them), and you need to to stick them together so that if one of them (the observed one) changes the coordinates of its bounding rectangle, the other one moves along.

Possible approaches

One of possible approaches is to crop the root bounding box to the size of the observed element by setting negative values to rootMargin. This approach has several drawbacks.

When an observed element is partly overlapped by its scrollable parent container, it creates a situation in which intersectionRatio doesn't change when the element moves until it is fully visible, therefore position change can not be detected.

The solution may be to calculate rootMargin so that rootBounds rectangle is captured inside the overlapping container and never leaves its boundaries. When the observed element is fully scrolled out of view, we just "switch" the observer to full vewport size to detect when the element gets visible again, so when it happens, we "switch" back to the cropped size.

Another problem occurs when resizing browser window, since rootMargin set in pixels it is static, rootBounds rectangle shrinks and expands with the window, creating "blind areas" with intersectionRatio = 1.0.

The solution to this may be calculating rootMargin in percents relation of the element's left and top coordinates to viewport's width and hight respectively. Now rootMargin is dynamic, rootBounds rectangle has a fixed size, but this way it runs away from the element on window resize. Although it doesn't prevent position change from being detected, when both element and detector are able to move, it makes the whole solution slightly less predicatble and adds more edge cases to check.

An observed element itself can also change its size. This entails the same consequences as described above. This can be possibly solved by using two IntersectionObservers with the cropped rootBounds rectangle per element, inner and outer. One detects size decrease, the other one detects size increase. They both would be needed to be recreated after every resize or position change. Another solution to this problem may be to use ResizeObserver in combination with IntersectionObserver.

This already gets us closer to the 4-observers concept.

4 observers

Keeping in mind all edge cases of the approach with rootBounds rectangle cropped to the target element size, I realized it would be much easier to observe each side of the element's bounding box instead of an element as a whole. No matter in which direction an element moves, its position or size change will be relibly detected by at least one observer. For that an element must be at least partly visible.

The algorithm is simple: we create 4 observers whose rootBounds rectangles initially intersect each side of the observed element by 2 pixels. If an intersection deviates from the range between 1 and 2 pixels in any direction, position or size change is detected. Since the same change can be detected by more than one observer, we invoke the .takeRecords() method of the rest observers in order to gather pending records and prevent repetetive callback function calls. Then we mark those observers for recreation whose records we collected. In the worst case (diagonal movement) it would be all 4. Then we "unobserve" all 4 observers, start a requestAnimationFrame loop and keep it running until the element's bounding rectangle stops changing. Once it happens, we stop the loop, and recreate the marked observers.

This looks more straithforward and implies much less edge cases to handle. If position change happens in between observer creation and its first callback invokation, we just repeat the cycle as if it was actual position change detection but only if the target element is inside document's viewport boundaries. This is a protection against an infinite loop. Whereas in the "cropped observer" approach, due to its variaty of edge cases, I had to implement the mechanics to distinguish between the first call of a callback after the new IntersectionObserver().observe() method invokation and an actual intersection change notification.

Why not to consider resize and scroll event handlers?

Having to handle events in combination with IntersectionObserver, that is code with different kinds of asynchronous nature, that executes in different phases and with different frequencies makes it hard to debug and brittle.

Moreover, in event handlers observing position change implies getBoundingClientRect() invokations. Not only it may be expensive, data aquired in one phase of asynchronous execution may turn out already stale in other phase where it is consumed.

When you shouldn't rely on `intersectionRect` and `intersectionRatio`?

As I already mentioned this case above, when a target element can possibly be partly overlapped by its parent scrollable container. If this is the case, it is better to calculate intersection using coordinates of rootBounds and boundingClientRect rectangles, because intersectionRect and intersectionRatio reflect intersection of a target's visible part rather than the whole target.

When you shouldn't use `visualViewport` with `IntersectionObserver`?

It may seem logical at first glance to use visualViewport.height or window.innerHeight in order to calculate the bottom margin of rootMargin. This will not be consistent among mobile and desktop screens if minimum-scale=1.0 is not specified in the meta tag.

<meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0, minimum-scale=1.0" />

Open developer tools, set the desktop view mode and put the spippet down below in the console. Then switch to the mobile view mode, refresh the page and paste the snippet again. See the difference.

var obs = new IntersectionObserver(
  entries => {
    console.log(
      'rootBounds.height:',
      entries[0].rootBounds.height,
      'visualViewport.height:',
      window.visualViewport.height,
      'window.innerHeight:',
      window.innerHeight,
    );
  },
  { root: document },
);

const longDiv = document.createElement('div');
longDiv.style.width = `${20000}px`;
longDiv.style.height = `${10}px`;
longDiv.style.position = 'absolute';
document.body.appendChild(longDiv);

obs.observe(document.documentElement);

It seems the most reliable way is to use viewport dimensions of an already created instance of IntersectionObserver (since it already calculated them for itself) to calculate rootMargin for another instance. This way we are dealing with the same source of truth and the same units regardles of scaling.

// initial viewport rect
const viewportRect = await new Promise(res => {
  const observer = new IntersectionObserver(
    entries => {
      res(entries[0].rootBounds);
      observer.unobserve(document.documentElement);
    },
    { root: document },
  );
  observer.observe(document.documentElement);
});

const { width: viewportWidth, height: viewportHeight } = viewportRect;

Alternative approach (When you can do without an observer at all?)

I couldn't finish without mentioning this hacky approach. If you need to stick one element to another one (target element) without employing any kind of position change observation, you can wrap the element into an auxiliary container with width and height equal to 0, so that it doesn't interfere with the natural document flow. Put this zero-sized container into the target's parent container right next to the target element using:

target.insertAdjacentElement('afterend', zeroSizedContainer);

Set the necessary offset for the element inside the zero-sized container and let the browser do the job.

Limitations for this approach:

When the target's parent container has flexbox layout with set gap or justify-content: space-between; it will create gaps and spaces for that zero-sized container.
And it will definetely break the target's parent container grid layout.

These limitations actually were the reason I started this little project.