DEV Community: Stefan Nieuwenhuis

Gaussian Naive Bayes: Part 2 — Mathematical Deep Dive and Optimization

Stefan Nieuwenhuis — Mon, 19 May 2025 00:00:00 +0000

Series: Gaussian Naive Bayes Classifier

Gaussian Naive Bayes: Part 1 — Introduction and Bayes Theorem Refresher
Gaussian Naive Bayes: Part 2 — Mathematical Deep Dive and Optimization

In the second part of the series, we dive into the mathematics behind Gaussian Naive Bayes. We’ll derive the class-conditional probability density functions, explore why log-probabilities are used, and show how the entire prediction process can be transformed into a fast, vectorized dot-product computation. Along the way, we’ll clarify common assumptions—such as constant variance across classes—and examine their practical consequences.

From Bayes to Naive Bayes

Bayes’ Theorem offers a formal way of updating our beliefs given new evidence. However, applying it directly in real-world classification tasks often becomes computationally intractable, especially dealing with high-dimensional data where we want to estimate the joint probability distribution (P(x_1, x_2, \dots,x_n\vert y)). It’s the combinatorial explosion problem, where the number of possible combinations of feature values grows exponentially with the number of features.

A Quick Primer: Independent vs. Conditionally Independent Events

Let’s break down the concepts of independence and conditional independence , as they’re crucial for understanding the “naivety” in Naive Bayes.

Independent events

Two events, (A) and (B), are independent if the occurrence of one has no effect on the probability of the other:

[P(A\cap B)=P(A)\cdot P(B)]

Or, equivalently:

[P(A\vert B) = P(A)]

, and

[P(B\vert A) = P(B)]

Example: Tossing two fair coins; The result of the first toss doesn’t affect the second.

Image by Great American Coin Co.

When

(A={x\vert x = \text{first coin is heads}}), and
(B={x\vert x = \text{second coin is heads}}),

Then

[P(A\cap B)=P(A)\cdot P(B) = \frac{1}{2} \cdot \frac{1}{2} = \frac{1}{4}]

Conditional independent events

Two events (A) and (B) are conditionally independent given a third event (C) if, once we know (C) has occurred, learning about (A) gives us no additional information about (B), and vice-versa. In other words, once we know the “cause”, the symptoms are treated as independent.

Formally:

[P(A\cap B\vert C)=P(A\vert C)\cdot P(B\vert C)]

Or, equivalently:

[P(A\vert B, C)=P(A\vert C)]

and

[P(B\vert A, C)=P(B\vert C)]

Example: Spam Email classifier

Let’s say we’re building a spam email classifier, where:

(C): Email is spam or not spam
(A): Email contains the word “Viagra”
(B): Email contains the words “Money-back guarantee”

In general, the presence of the words “Viagra”, and “Money-back guarantee” might be correlated, since spammy phrases often appear together. Knowing the presence of (A) might increase the likelihood of (B). This means that both events are dependent in isolation.

But here’s the key. Once we conditioned on (C) (email is spam), the presence of (A) no longer gives us new infromation on the likelihood of (B). Why? Both events are already explained by the fact the email is spam. The common cause (C) makes the co-occurrence of the symptoms more likely.

In other words,

Once we know that an email is spam, it does not matter wheter (A) and (B) often appear together in general. The only relevant question is how likely each word appears in spam emails?

So (A) and (B) become conditionally independent given (C). This is the Naive Bayes assumption in action. It’s what allows the model to break down complex joint probabilities into simpler, individual conditional probabilities (one per feature).

The “Naive” assumption

Now that we understand how Bayes’ Theorem updates our beliefs given evidence, we face a practical question:

How do we estimate (P(e\vert H)) when (e) is a high-dimensional feature vector?

Given the hypothesis (H), and dependent feature (or evidence) vector (\vec{e} = \begin{bmatrix}e_1 & \dots & e_n\end{bmatrix}), Bayes’ Theorem states:

[P(H\vert e_1 \cap e_2 \cap \dots\cap e_n) = \frac{(e_1 \cap e_2 \cap \dots\cap e_n \vert H)\cdot P(H)}{P(e_1 \cap e_2 \cap \dots\cap e_n)}]

In high-dimensional spaces, modelling this full joint probability distribution (P(e_1 \cap e_2 \cap \dots\cap e_n\vert H)) becomes often computationally intractable, especially with limited training data.

Why is it hard?

The number of parameters required to model a joint distribution grows exponentially with the number of features in a dataset. For example, suppose we wanted to model dependencies between just 100 binary features conditioned on a class label. This would require estimating probabilities for (2^{100}) possible feature combinations per class - an astronomically large number ((1,2676506002×10^{30})). Even for continuous features, estimating a full, multivariate distribution requires computing high-dimensional covariance matrices, and ensuring they are invertible and well-conditioned. These tasks are computationally expensive and statistically fragile unless we have massive datasets.

This is known as the curse of dimensionality: as the number of dimensions (features) increases, the amount of data required to reliably estimate densities increases exponentially. In practice, we rarely have enough data to estimate these complex joint distributions without overfitting or introducting heavy regularization.

The “naive” simplification

The “naive” assumption circumvents this by treating each feature as conditionally independent given the class label:

[P(e_i\vert H\cap e_1\cap\dots\cap e_{i-1}\cap e_{i+1}\cap\dots\cap e_n) = P(e_i\vert H)]

, and for all (i) this relation is simplified to:

[P(H\vert e_1\cap\dots\cap e_n) = \frac{P(H)\cdot\prod\limits_{i=1}^n P(e_i | H)}{P(e_1\cap\dots\cap e_n)}]

The denominator normalizes the nominator, and integrates over all possible class labels , since it does not depend on (H) to be computed - i.e. it doesn’t affect which class has the highest probability. So we can rewrite the classification rule using just the numerator:

[P(H\vert e_1\cap\dots\cap e_n) \varpropto P(H)\cdot\prod\limits_{i=1}^n P(e_i | H)]

, and we can use (\arg \max) to find the class that gives the highest posterior probability for feature vector (\vec{x}):

[\hat{y}=\arg \max_{y} P(y)\cdot\prod\limits_{i=1}^n P(x_i | y)]

Estimating the posterior probabilities from training data is done via Maximum A Posteriori (MAP) estimation. (P(y)) is estimated as the relative frequency of class (y) in the training set, and each (P(x_i\vert y)) is estimated based on feature distributions in each class.

Under the hood, it computes (P(y)\cdot\prod\limits_{i=1}^n P(x_i \vert y)) for every class (y), and normalizes the results so they sum to (1).

Why does it work?

Naive Bayes often performs surprisingly well in practice, despite its unrealistic independence assumptions. This is because accurate probability estimates are not always required for good classification. What matters is that the decision boundary induced by comparing class scores remains useful. Even when the probabilities themselves are not well calibrated. As long as the incorrect independence assumption does not lead to systematically biased scores, the final predictions can still be highly effective.

This is why Naive Bayes is often described as

“wrong, but useful” - A pragmatic trade-off between statistical realism and computational simplicity.

We have to be cautious with correlations between features though, since it breaks down our feature independence assumption, and the model exaggerates or underrepresents the true likelihood, and performance degrades.

The naive assumption oversimplifies reality. In most real-world datasets, features are not truly independent. However, the simplification offers practical benefits:

Tractability : We only have to estimate one univariate distribution per feature per class.
Sample efficiency : We need far fewer samples to get reliable estimates of the probability distributions for each class.
Speed : The classifier becomes fast to train and evaluate.

From assumptions to implementations: Handling continuous features

At the heart of Naive Bayes thus lies a simplifying assumption: All features are conditionally independent given the class label, but in order to compute the individual terms (P(x_i \vert y)), we have to make assumptions about each features’ distribution. This is where we can use different Naive Bayes variants. The assumptions remain the same, but the difference is the way the individual probabilities for each (x_i) is computed.

if (x_i) is categorical , we use frequency counts (Multinominal or Bernoulli NB).
if (x_i) is continuous , we cannot count how often each exact value occurs, since real-valued features are rarely repeated exactly, and this problem grows when the precision (e.g. measurement) increases.

The latter leads us to a natural solution: Assume a probability distribution over the feature values. Enter the Gaussian Naive Bayes classifier.

Gaussian Naive Bayes Classifier

Image by RMIT University

The Gaussian distribution is a natural choice, since:

The Central Limit Theorem since many features tend to be approximately normal.
Simplicity: A normal distribution is described with only the mean and variance.
Mathematical convenience (e.g. closed-form likelihood, stability under transformations, computationally cheap)

It is defined for a continuous variable (x) with:

Mean (\mu): The center of the distribution
Variance (\sigma^2): The spread of the data - i.e. distance from the mean

Probability density function (PDF)

We can use the probability density function (PDF) to compute the probability of (x) comes from a Gaussian distribution with a given (\mu), and (\sigma^2):

[P(x_i\vert y) = \frac{1}{\sqrt{2\pi\sigma_{ic}^2}}\cdot\exp(-\frac{(x_i - \mu_{ic})^2}{2\sigma_{ic}^2})]

First term: the normalization constant

[\frac{1}{\sqrt{2\pi\sigma_{ic}^2}}]

In probability theory, a PDF describes how likely a continuous random variable is to take on a value in a given range, but, unlike discrete probabilities, where probabilities like (P(x=3)) are directly meaningful, continuous variables don’t work that way.

Instead, the probability that a continuous variable fall within a range ([a,b]) is given by the area under the curve of the PDF between (a) and (b).

[P(a \leq x \leq b) = \int_{b}^{a}f(x)dx]

To be a valid PDF, it must satisfy one crucial condition:

The total area under the curve across the entire real number line must equal 1.

That is

[\int_{\infty}^{-\infty}f(x)dx=1]

This renders the distribution properly normalized over all real numbers.

Second term: exponential decay

[\exp(-\frac{(x_i - \mu_{ic})^2}{2\sigma_{ic}^2})]

The exponential term controls the shape of the bell curve - i.e. the kurtosis (how “tall” or “flat” is the distribution around (\mu)?). It is called exponential decay , since, as (x) moves away from (\mu), this term rapidly decreases toward zero.

Decoding the terms

((x - \mu)): Measures the distance of (x) from (\mu)
((x - \mu)^2): (squared distance): Ensures this value is always positive, and the larger the distance, the larger the value becomes.
((2\sigma^2)): Scales the squared distance. The larger (\sigma), the more “forgiving” the distribution is of being far from the mean.
(-\frac{(x_i - \mu_{ic})^2}{2\sigma_{ic}^2}) (negative sign): This makes the exponent negative, so as the distance increases, the exponent decays.
(\exp): Converts the scaled squared distance into a value between 0 and 1 - i.e. a probability estimate.

The expontential decay models the likelihood (x) appears in a Gaussian-distributed class (y).

When (x) is close to the class mean , the exponent is near 0 - i.e. high probability
When (x) is far from the class mean , the exponent becomes strongly negative - i.e. probability shrinks toward 0.

This makes the model sensitive to deviations from the class-specific mean , which is what allows Gaussian Naive Bayes to perform classification based on how well a value fits into the distribution learned for each class.

Mathematical Optimizations in Gaussian Naive Bayes

When implementing Gaussian Naive Bayes, several mathematical optimizations are employed to improve both numerical stability and computational efficiency. The underlying probability theory remains unchanged but the optimizations make the model more robust and scalable (with high-dimensional or sparse data in particular).

Use log probabilities instead of raw probabilities

In the prediction phase, we compute the product of conditional likelihoods

[P(y=c\vert x)\varpropto P(y=c)\prod\limits_{i=1}^n P(x_i | y=c)]

However, multiplying many small probabilities can quickly lead to numerical underflow, where the product becomes so small that it rounds to zero in floating-point representation. It becomes a number of more precise absolute value than the computer can actually represent in memory on its central processing unit (CPU).

Optimization

Apply the natural logarithm to the entire expression. Since the logarithm is a monotonically increasing function, maximizing the log of the probabilities yields the same result as maximizing the original product:

[\hat{y}=\arg \max_{c} \biggl( \log P(y=c)+\sum\limits_{i=1}^n \log P(x_i | y=c)\biggl)]

This transformation avoids numerical underflow and ensures robust computation.

But log-space transformations are not just about numerical safety, they also improve computational efficiency , particularly in the context of large-scale or high-dimensional data.

The primary benefit comes from the mathematical identity

[log(a\cdot b) = log(a) + log(b)]

Multiplying many identities - i.e. one for each feature variable - can be computationally expensive and slow. By converting the product into a sum of logarithms:

We reduce the number of operations from (O(n)) multiplications to (O(n)) additions. Although modern CPU architectures mitigate the effects, addition is still faster, and less complex than multiplication ((O(n)) vs. (O(n \log n)) time complexity).
Additions are faster and more stable than floating-point multiplications, especially on hardware like GPUs or vectorized CPUs where addition is heavily optimized. It also limits parallelism, since each multiplication depends on the previous result.

Use vectorization via dot-product form

Terms can be re-arranged to fit the structure of a dot-product by transforming the log-likelihood of a Gaussion PDF into an algebraic form. This allows for efficient batch computation, since modern hardware architectures are highly optimized for such calculations.

Recall the log of a Gaussian PDF

[log P(x_i \vert y=c) = -\frac{1}{2}log(2\pi\sigma_{ic}^2)-\frac{(x_i - \mu_{ic})^2}{2\sigma_{ic}^2}]

The total log-probability can be broken down into a sum of constants , quadratic terms , and a linear dot-product between input and model parameters. The class score is represented as

[log P(y=c \vert x) = log P(y=c)+x+w_c+\text{const}_c]

Where

(w_c=\biggl(\frac{\mu_{ic}}{\sigma_{ic}^2}\biggl)),
The offset (\text{const}_c=-\sum\limits_i\biggl(\frac{\mu_{ic}^2}{2\sigma_{ic}^2}+\frac{1}{2}log(2\pi\sigma_{ic}^2)\biggl))

This transforms inference into a single dot-product plus offset per class , which allows for fast batch prediction with matrix multiplication ((X\cdot\mathbf{\theta}^\top+b)), and allows the constants to be cached.

If speed is what you’re after, we can assume equal variance (\sigma_{ic}^2 = \sigma_{c}^2) or (\sigma_{ic}^2 = \sigma^2) so that the quadratic term cancels out in the equation, and the remaining term becomes linear. This is a trade-off between speed and accuracy, and A/B testing is required to objecticvely compare solutions, and pick the best fitting model for a use-case.

Use Epsilon Variance Smoothing

The Gaussian PDF breaks down if the estimated variance (\sigma_{ic}^2=0), which can happen when:

A feature has zero variance in a class (e.g. same value across all training samples of a class).
A feature has very low variance making the denominator in the exponent extremely small, leading to numerical instability or exploding gradients in probabilistic computations.

To guard against these issues, a small constant (\epsilon) is added to the variance during computation

[\tilde{\sigma}_{ic}^2=\sigma_{ic}^2+\epsilon]

This technique is called variance smoothing , and (\epsilon) is typically on the order of (10^{-9}) to (10^{-5}), depending on the scale of the data. By preventing division by zero and avoiding extremely large exponentials, it guarantees well-behaved computation even for pathological features or small training sets.

Conclusion

Gaussian Naive Bayes might seem simple at first glance, but beneath its straight-forward assumptions lies a wealth of mathematical elegance and engineering nuance. By diving deep into the underlying mathematics, we’ve seen how classical probability theory, numerical stability optimizations, and linear algebra come together to create an inference engine that’s both fast and effective.

Transforming probability products into log-space not only prevents numerical underflow but unlocks powerful computational optimizations: it turns costly multiplications into efficient additions and enables vectorized inference via dot-product formulations. Smoothing tiny variances with epsilon avoids pathological cases where the model becomes overly confident or completely unstable. And through visualizing decision boundaries, we get a tangible sense of how these mathematical choices shape model behavior.

Ultimately, these optimizations aren’t just about speed or safety — they reflect a mature understanding of how theoretical models meet the real-world imperfections of data and hardware. Whether you’re building a scalable classifier or exploring probabilistic reasoning, mastering these principles ensures your models are not only correct, but robust, interpretable, and production-ready.

In the next and final part, we’ll implement these ideas in Python, visualize decision boundaries, and compare theoretical insights with empirical results.

Gaussian Naive Bayes: Part 1 — Introduction and Bayes Theorem Refresher

Stefan Nieuwenhuis — Thu, 15 May 2025 00:00:00 +0000

Series: Gaussian Naive Bayes Classifier

Gaussian Naive Bayes: Part 1 — Introduction and Bayes Theorem Refresher
Gaussian Naive Bayes: Part 2 — Mathematical Deep Dive and Optimization

This is the first part of a multi-part series on Gaussian Naive Bayes, a simple yet surprisingly effective probabilistic classifier. In this post, we’ll explore the foundational concepts behind Bayes’ Theorem and how they apply to machine learning. We’ll also introduce the Naive Bayes assumption, setting the stage for a deeper mathematical dive in the next post.

In the ever-growing landscape of machine learning algorithms, Naive Bayes stands out due to its elegant probabilistic foundation and surprising effectiveness in various practical applications, especially in text classification and medical diagnosis. Gaussian Naive Bayes, in particular, is a variant tailored for continuous data, assuming a Gaussian distribution for each feature conditioned on the class.

As part of revisiting foundational concepts in probability and statistics—especially Bayes’ Theorem—I built a machine learning project that implements classifiers from scratch to classify Iris flower species. The first model I implemented was a Gaussian Naive Bayes classifier, which served as both a mathematical refresher and a practical coding exercise.

This blog post is a deep mathematical dive into the Gaussian Naive Bayes classifier. We will go beyond the intuition and dissect the mathematical components that underpin it. This post focuses solely on the mathematics behind Gaussian Naive Bayes—not on implementation or model building. That will be covered in a dedicated follow-up post.

Whether you’re an aspiring data scientist, machine learning engineer, or a curious student, this guide aims to offer clarity and precision in understanding the mathematical machinery that drives Gaussian Naive Bayes.

The Iris Flower Species dataset

The Iris flower data set or Fisher’s Iris data set is a multivariate data set used and made famous by the British statistician and biologist Ronald Fisher in his 1936 paper The use of multiple measurements in taxonomic problems as an example of linear discriminant analysis.

The data set consists of 50 samples from each of three species of Iris (Iris setosa, Iris virginica and Iris versicolor). Four features were measured from each sample: the length and the width of the sepals and petals, in centimeters.

– Source: Wikipedia: Iris Flower Data Set

Bayes’ Theorem Refresher

Bayes’ Theorem provides a formal method - i.e. mathematical rule for updating probabilities based on new evidence. In other words, with Bayes’ Theorem we can compute how much to revise our probabilities (change our minds) when we learn a new fact or observe new evidence.

In classification terms:

(P(H\vert E)): Posterior - probability of (H) (hypothesis) given (e) (the evidence) is true
(P(H)): Prior - initial belief about (H) before seeing (e)
(P(e\vert H)): Likelihood - probability of observing (e) given that (H) is true
(P(e)): Marginal probability (or evidence) - overall probability of observing (e)

When, for example, a certain Iris Flower species is known to have larger petals, Bayes’ theorem allows a sample to be assessed more accurately by conditioning it relative to its petal size, rather than assuming the sample is typical of the population as a whole. In other words, we reduce the total number of possibilities to make the propability estimates more likely.

It is all about information

Bayes’ Theorem is, at its core, a tool for updating beliefs in light of new information. It provides a formal definition how evidence should impact our confidence in different hypothesis. The prior, (P(H)), is our belief before seeing any data. The likelihood, (P(e\vert H)), captures how likely the observed data is under each hypothesis, and combining both terms results in the posterior, (P(H\vert e)), our updated belief after seeing the evidence.

Bayes’ Theorem is thus about information flow : How new data reshapes our expectations and refines our understanding of the world in a formal, structured way.

Example: Monty Hall Problem

Image by Cepheus - Own work, Public Domain

The Monty Hall problem is a brain teaser, in the form of a probability puzzle, based nominally on the American television game show Let’s Make a Deal and named after its original host, Monty Hall. The problem was originally posed (and solved) in a letter by Steve Selvin to the American Statistician in 1975 It became famous as a question from reader Craig F. Whitaker’s letter quoted in Marilyn vos Savant’s “Ask Marilyn” column in Parade magazine in 1990:

Suppose you’re on a game show, and you’re given the choice of three doors: Behind one door is a car; behind the others, goats. You pick a door, say No. 1, and the host, who knows what’s behind the doors, opens another door, say No. 3, which has a goat. He then says to you, “Do you want to pick door No. 2?” Is it to your advantage to switch your choice?

Savant’s response was that the contestant should switch to the other door. By the standard assumptions, the switching strategy has a ⁠ (\frac{2}{3}) probability of winning the car, while the strategy of keeping the initial choice has only a ⁠(\frac{1}{3}) probability.

– Source: Wikipedia: Monty Hall Problem

To switch or not to switch? Bayes to the rescue!

Bayes’ Theorem helps clarify why switching increases your odds.

Step 1: Define the hypotheses

Since each door is equally likely to contain the car before Monty opens any , LaPlace definition of probabilty applies.

[H_1=H_2=H_3=\frac{n_{favorable}}{n_{total}}=\frac{1}{3}]

We can also define our priors:

(H_1): The car is behind door No. 1 (our original choice)
(H_2): The car is behind door No. 2 (we’d win if we switch)
(H_3): The car is behind door No. 3 (ruled out since Monty just revealed a goat behind this door)

Step 2: Use the evidence

Let’s denote the evidence, (e), as: “Monty opens door No. 3, revealing a goat”.

Next, we want to compute the posterior probabilities (P(H_1\vert e)), and (P(H_2\vert e)) - i.e. what is the probability the car is behind door No. 1 or No. 2 given that Monty revealed a goat behind door No. 3?

Applying Bayes’ Theorem:

(P(H_k\;\vert\;e) = \frac{P(e\;\vert\;H_k)\cdot P(H_k)}{P(e)}), where (k \in {1,2,3}).

And compute the likelihoods:

If the car is behind door No. 1, (H_1), Monty could randomly choose door No. 2 or 3. (\Rightarrow P(e\vert H_1)=\frac{1}{2}).
If the car is behind door No. 2, (H_2), Monty could only pick door No. 3, since we picked the first already (\Rightarrow P(e\vert H_2)=1).
If the car is behind door No. 3, (H_3), Monty could not open the door, since it reveals the car (\Rightarrow P(e\vert H_3)=0)

With the likelihoods computed, we now move forward to calculate the marginal probability, (P(E)), or normalization constant.

[P(E) = P(e\vert H_1)P(H_1)+P(e\vert H_2)P(H_2)+P(e\vert H_3)P(H_3)] [\Rightarrow (\frac{1}{2}\cdot\frac{1}{3})+(1\cdot\frac{1}{3})+(0\cdot\frac{1}{3})] [=\frac{1}{6}+\frac{1}{3}=\frac{3}{6}=\frac{1}{2}]

Finally, we compute posteriors for hypothesis 1

[P(H_1\vert e) =\frac{P(e\vert H_1)P(H_1)}{P(e)}] [\Rightarrow \frac{\frac{1}{2}\cdot\frac{1}{3}}{\frac{1}{2}}=\frac{\frac{1}{6}}{\frac{1}{2}}=\frac{1}{3}]

And hypothesis 2

[P(H_2\vert e) =\frac{P(e\vert H_2)P(H_2)}{P(e)}] [\Rightarrow \frac{1\cdot\frac{1}{3}}{\frac{1}{2}}=\frac{\frac{1}{3}}{\frac{1}{2}}=\frac{2}{3}]

Switching gives you a (\frac{2}{3}) chance of winning the car, while staying with your initial pick gives you only a (\frac{1}{3}) chance, so we switch.

The Monty Hall Problem demonstrates how Bayesian updating works:

Start with prior beliefs
Incorporate new evidence
Normalize and update beliefs accordingly

It also challenges our intuition and why probabilistic reasoning is essential in making better decisions.

Conclusion

We’ve seen how Bayes’ Theorem provides a probabilistic framework for classification and how the “naive”” assumption simplifies modeling joint distributions. In Part 2, we’ll dive deeper into the mathematical formulation of Gaussian Naive Bayes, including how log-probabilities, vectorization, and variance assumptions impact efficiency and accuracy.

What is a Logarithm? A Complete Beginner’s Guide

Stefan Nieuwenhuis — Wed, 14 May 2025 00:00:00 +0000

If you’ve ever asked yourself, “What is a logarithm, and why should I care?” —you’re in the right place. Whether you’re a student, aspiring data scientist, or just curious about the math behind modern technology, this blog post will give you a solid understanding of logarithms.

I’ve recently been revisiting my knowledge of statistics and probability, including foundational concepts like Bayes’ Theorem. In the process, I built a machine learning project where I implement different classifiers from scratch to classify Iris Flower Species. The first one was a Gaussian Naive Bayes classifier. While implementing it, I ran into several mathematical optimizations that piqued my curiosity, especially the use of log transforms for numerical stability and computational efficiency. That journey is what led me to write this post.

This isn’t just a basic introduction—we’ll break everything down from first principles, explaining not just what logarithms are, but why they work, how they’re used, and how they tie into real-world applications like machine learning and data science.

Let’s start at the very beginning.

What is a logarithm?

A logarithm is a mathematical tool to answer this question:

“To what power must I raise a number to get another number?”

In other words, how many times do I have to multiply a number by itself to get another number?

Like subtraction is the opposite of summation, a logarithm is the inverse of exponentiation. If exponentiation is

10^2 = 100

Then the logarithmic version is

log_{10}(100) = 2

Intuition : “I have to multiply 10 twice to get 100.”

Breaking it down

Here, $log⁡\log$ stands for logarithm. The right side part of the arrow is read to be “Logarithm of $x$ to the base $b$ is equal to $a$ “.

Base(b): The number we are multiplying by itself.
Exponent(a): How many times we multiply the base.
Argument(x): The number that we are taking the logarithm of.

Restrictions

$ba=x\log_{b}(x) = a \;\text{if and only if}\; b^a = x$ . This is the basic definition of a logarithm.
The base $b$ of a logarithm is always a positive real number ( $\in \mathbb{R} \;\vert\; x > 0$ )
The argument $x$ is always a positive real number ( $\in \mathbb{R} \;\vert\; x > 0$ ).

Why do we use logarithms?

Logarithms show up all over math, science, engineering, and computing. Here’s why:

They scale down large numbers
They convert multiplication into addition
They reverse exponentiation

They scale down large numbers

Many real-world phenomena grow or shrink exponentially (e.g. population growth, viral infections, radioactive decay, financial interest, …). These changes happen so fast that it’s hard to describe them with linear math.

Why? Linear math assumes steady, additive growth. It’s like climbing stairs, flight over flight. Exponential growth is like climbing the same stairs but skipping increasingly more and more flights with every step. Each step is multiplicative in stead of additive.

Continuous multiplicative growth quickly outpaces our ability to model or interpret it with simple arithmetic, and that’s where logarithms come in, since they convert exponential relationships into linear relationships (but do not change the underlying data).

In other words, logarithms linearize exponential growth : They “compress” fast-growing data into a scale we can handle more easily.

For an interactive version of this image, see GeoGebra

What do we see graphed?

Linear functions grow at a steady, continuous pace
All logarithmic functions pass through the point $(1, 0)$
Logarithmic functions grow slowly
Exponentials ( $e^x$ ) grow rapidly
Logarithms are the inverse of exponentials

Compared to exponential growth like $e^x$ , logarithmic functions such as $l o g (x)$ grow very slowly. This “compression” of scale makes it less-complex to analyze, as the curve flattens out and almost behaves linearly across a wide range of input values. This allows us to apply simpler, linear arithmetic to model and work with phenomena that are otherwise exponential.

They turn multiplication into addition

The Product Rule is one of the most powerful features of logarithms:

log⁡(a⋅b)=log⁡(a)+log⁡(b)\log(a\cdot b) = \log(a) + \log(b)

It tells us that the logarithm of a product is equal to the sum of the logarithms of the individual factors. To put it simply: Multiplying values inside a logarithm is the same as adding their logarithms. This might seem a little abstract at first, so let’s use a simple analogy and then dive deeper into the math.

Why does the Product Rule work?

Logarithms are the inverse of exponentiation, and exponentiation has the same property: When you multiply numbers in the base of an exponential, you add their exponents, given that the base of all numbers is the same.

bx⋅by=bx+yb^x\cdot b^y = b^{x+y}

This is just a basic property of exponents: when you multiply powers of the same base, you add the exponents. Don’t worry, I have added examples below. If we take the logarithm of both sides of the equation above, we get:

logb(bx⋅by)=log(bx+y)log_{b}(b^x\cdot b^y) = log(b^{x+y})

Using the logarithm rule for powers , we can simplify the right-hand side:

logb(bx⋅by)=x+ylog_{b}(b^x\cdot b^y) = x+y

Now, from the product rule , we can see that:

logb(bx⋅by)=logb(bx)+logb(by)log_{b}(b^x\cdot b^y) = log_{b}(b^x) + log_{b}(b^y)

Which results in:

logb(bx⋅by)=x+y=logb(bx)+logb(by)log_{b}(b^x\cdot b^y) = x+y = log_{b}(b^x) + log_{b}(b^y)

And this is exactly the product rule.

Example

Let’s make this more concrete with numbers. We have two numbers, 100 and 10, and we want to compute the logarithm of their product:

log10(100⋅10)=log10(1000)log_{10}(100\cdot10)=log_{10}(1000)

Now. using the product rule

log_{10}(100) + log_{10}(10)

We compute that

log_{10}(100) = 2

log_{10}(10) = 1

Hence,

log_{10}(100) + log_{10}(10)=3

And, indeed:

log10(1000)=3⇔103=1000log_{10}(1000) = 3 \Leftrightarrow 10^3=1000

Why is this useful?

Simplifying Calculations : The Product Rule makes complex logarithmic expressions easier to simplify and calculate, especially when dealing with large numbers or unknowns.
Breaking Down Multiplications : If you need to multiply two values but want to avoid directly multiplying them (e.g. to avoid complexity), you can first take their logarithms, add them, and then take the antilog (inverse logarithm) to find the product. This was especially useful before calculators, when logarithmic tables were common.
Dealing with Exponentials in Data : In real-world applications like data science, physics, or machine learning, many processes involve multiplying values that could be better handled with logarithms. By breaking multiplication into addition, it often becomes computationally simpler and more stable.

They Reverse Exponentiation

Logarithms undo exponentials and this help solve equations where the unknown is an exponent. For example, if you know

2^x=16

You can solve for $x$ with

log_{2}(16) = x = 4

So, logarithms help you solve for exponents — the exact inverse operation of exponentiation. This is why:

A logarithm is the inverse of an exponential function.

Why it matters

In many equations, especially in science and engineering, you know the argument and the base, but you need to find the exponent. That’s when you turn to logarithms.

The Three Common Types of Logarithms

Common Logarithm (Base 10)
- Written as $log⁡(x)\log(x)$
- Used in scientific notation and calculators
Natural Logarithm (Base e)
- Written as $l n (x)$ where $\approx 2.718$
- Found in continuous growth/decay processes and advanced mathematics
Binary Logarithm (Base 2)
- Written as $log_{2}(x)$
- Used in computer science (e.g. data structures and algorithms)

Real-World Applications of Logarithms

Logarithms aren’t just abstract math — they’re part of everyday technologies:

Machine Learning & AI : Algorithms like Naive Bayes use logarithms to make probability computations more stable and efficient.
Search Engines : TF-IDF scores for search relevance use logarithmic scaling.
Audio & Sound : Decibels (dB) are a logarithmic measure of sound intensity.
Earthquakes : The Richter scale is logarithmic.
Finance : Compound interest is modeled exponentially; logs help reverse it.
Computer Science : Binary logarithms appear in time complexity, especially in search and sort algorithms (e.g., binary search: O(log n)).

The 7 laws of logarithms

The 7 laws (also called properties or identities) of logarithms are used to simplify, expand, or condense them. Depending on the situation, the laws can be applied to make computations easier.

1. Product rule

log⁡(a⋅b)=log⁡(a)+log⁡(b)\log(a\cdot b) = \log(a) + \log(b)

The logarithm of a product is the sum of the logarithms.

Example

log⁡10(100⋅1000)=log⁡10\log_{10}(100\cdot1000)=\log_{10}

2. Quotient rule

log⁡b(xy)=log⁡b(x)−log⁡b(y)\log_{b}(\frac{x}{y}) = \log_{b}(x) - \log_{b}(y)

The logarithm of a quotient is the difference of the logarithms.

Example

log⁡2(432)=log⁡2(32)−log⁡2(4)=5−2=3\log_{2}(\frac{4}{32})=\log_{2}(32) - \log_{2}(4) = 5 - 2 = 3

3. Power rule

log_{b}(x^p)=p\log_{b}(x)

The logarithm of a power is the exponent times the logarithm of $x$ .

Example

log⁡10(1003)=3⋅log⁡10(100)=3⋅2=6\log_{10}(100^3) = 3\cdot\log_{10}(100) = 3\cdot2=6

4. Change-of-Base rule

log⁡b(x)=log⁡k(x)log⁡k(b)\log_{b}(x) = \frac{\log_{k}(x)}{\log_{k}(b)}

The Change-of-Base rule allows changing the base of a logarithm to a different base.

Example

log⁡2(8)=log⁡10(8)log⁡10(2)≈0.9030.301≈3\log_{2}(8)=\frac{\log_{10}(8)}{\log_{10}(2)}\approx\frac{0.903}{0.301}\approx3

5. Zero Exponent rule

log_{b}(1)=0

Regardless of its base, the logarithm of 1 is always 0.

6. Log of 1 rule

log_{b}(b)=1

The logarithm of the base to itself is always 1.

7. Log of base rule

b^{\log_{b}(x)}=x

The base raised to the log of a number returns the number

Example

2^{\log_{2}(10)}=10

History of Logarithms

Logarithms were invented by John Napier in the early 1600s to simplify calculations. Before calculators, scientists used logarithm tables to perform long multiplications and divisions. The invention of the slide rule, which used logarithmic scales, revolutionized engineering and astronomy.

Conclusion

Logarithms are one of the most elegant tools in mathematics. They allow us to simplify multiplication, deal with exponential growth, and make real-world problems manageable—from data science to earthquake measurement. Even if you start with zero math background, understanding logarithms gives you access to a whole new world of problem-solving techniques.

If you’re learning machine learning, algorithms, or even just trying to understand scientific scales, logs will be your friend. And now, you know exactly what they are and why they matter.

From Neural Nets to Hashmaps — Why I’m Relearning the Fundamentals

Stefan Nieuwenhuis — Wed, 09 Apr 2025 00:00:00 +0000

“You don’t really understand a concept until you’ve taught it.”

I recently set out on a mission to revisit fundamental data structures—not just to refresh my knowledge, but to better articulate and document them as part of my public learning journey. This post kicks off a new series where I’ll be blogging my notes and learnings as I dive deeper into Data Structures & Algorithms (DSA).

In this first entry, we’ll explore one of the most essential and elegant structures: hashmaps (also known as dictionaries in Python).

🧠 Why Start with Hashmaps?

As a Machine Learning Engineer, I often interact with complex distributed systems and large-scale data pipelines. But I’ve learned over the years that deep mastery of foundational data structures gives you an edge when debugging, optimizing, or explaining complex systems.

Hashmaps are ubiquitous in machine learning codebases, from feature stores and caches to logging metadata, configs, and parameter storage.

Let’s break them down from the ground up.

🧩 Why Hashmaps Matter (Even in ML)

You might ask: Why should someone working on multi-armed bandits or collaborative filtering care about hashmaps?

Because maps — aka dictionaries or hash tables — are everywhere in production ML:

Counting term frequencies or user-item interactions? → Use a hashmap.
Storing cached embedding vectors for reuse? → Use a hashmap.
Implementing a feature store or a key-value-based retrieval backend? → Definitely a hashmap.

And beyond ML, hashmaps are the go-to tool for engineers working on performance-critical backend systems — just like the ones powering Booking.com’s search, availability, and personalization flows.

So instead of just skimming the docs, I sat down and re-implemented the core operations, step by step. What I found was surprisingly delightful.

🔧 How a Hashmap Actually Works

At a high level, a hashmap is a key-value store that lets you do this:

prices = {'hotel_1': 89, 'hotel_2': 120}
print(prices['hotel_1']) # → 89

But under the hood?

The key ('hotel_1') is passed through a hash function , turning it into a numeric index.
That index maps to a bucket in an array.
If two keys map to the same index (a collision ), the hashmap resolves it — often using chaining , where multiple key-value pairs are stored in a list at that index.

This simple trick makes average-case lookup, insert, and delete all O(1).

It’s blazing fast. And it’s why modern feature stores, caching layers, and even graph algorithms use them constantly.

🔄 When I Relearned It, I Noticed…

Something clicked. Not in a “textbook” way, but in a real-world recommender system kind of way.

Take the “Group Anagrams” problem. It feels abstract at first, but then you realize it’s just a question of key design. You hash on a sorted string — a clever fingerprint — and group words accordingly.

That’s exactly what we do in ML when creating hashed feature buckets or aggregating click events by session ID.

Revisiting these problems now feels like seeing old friends through a new lens: with the eyes of someone who has fought latency bugs and wrangled production data.

🧪 My Practice Flow

As part of this DSA refresh, I’ve been solving classic hashmap-related LeetCode problems, including:

I’m not just solving them to get green ticks. I’m solving them to understand what makes solutions elegant, efficient, and robust enough to scale.

📈 Complexity Recap

Operation	Average Case	Worst Case
Insert	O(1)	O(n)
Lookup	O(1)	O(n)
Delete	O(1)	O(n)

Yes, worst case is linear due to collisions — but with good hash functions and low load factors, you rarely hit it. Modern languages (Python, Java, Go, etc.) optimize aggressively here.

🛠️ Common Use Cases in ML Engineering

Here’s where I see hashmaps in practice:

Feature lookup in online prediction services
Embedding tables (backed by a key-value store)
Experiment tracking configs (e.g., logging which variant a user saw)
Hyperparameter tuning frameworks

Understanding how they behave under the hood helps me reason about performance bottlenecks—especially when dealing with large-scale or high-throughput services.

📈 Final Thoughts

Revisiting the hashmap wasn’t just a refresher for me—it was a reminder of how much power lies in simplicity. As I continue this DSA refresher series, I’ll keep connecting the dots between textbook knowledge and real-world machine learning engineering.

🚀 Why I’m Sharing This Publicly

I’m building this blog as a transparent record of my learning process — not just to prep for interviews, but to sharpen my engineering instincts.

It’s part of a larger project where I’m also:

Building a real-time recommender system from scratch with FastAPI + Redis + Spark
Deploying everything to my bare-metal Kubernetes homelab
Measuring end-to-end performance with Prometheus + Grafana
Open-sourcing the entire thing

So whether you’re a fellow ML engineer, a systems-minded developer, or a recruiter curious about my thought process — welcome aboard.

📣 Let’s Learn Together

If you’re also revisiting the fundamentals — or if you’re deep in the weeds of ranking models and want to get more hands-on with infra — I’d love to connect.

This is just the first in a series of DSA posts. Next up: Sliding windows, prefix sums, and graph traversal for recommender systems, and much more.

👉 Check out the DSA series here
👉 Follow the full Recommender From Scratch project here
👉 Let’s connect on LinkedIn and GitHub

See you in the next post.

Shadow DOM: What it is and how it works

Stefan Nieuwenhuis — Fri, 03 Mar 2023 15:43:39 +0000

The web has come a long way since the early days. Today, developers can create complex web applications using a variety of tools and frameworks. However, with this complexity comes a new set of challenges, such as ensuring that the styles and behavior of a web application are consistent across different browsers and platforms. This is where the Shadow DOM comes in.

In this article, we'll explore the Shadow DOM in more detail, including its syntax, use cases, advantages, and disadvantages.

What is Shadow DOM?

Shadow DOM is a technology that enables developers to create encapsulated DOM trees, which are separate from the main document tree. These DOM trees are attached to custom elements, and provide a way to isolate the styles and behavior of the custom element from the rest of the document. This means that styles and behaviors defined in the Shadow DOM will only affect the custom element, and not any other elements on the page.

How does it work?

When a custom element is defined with Shadow DOM, it creates a new Document Fragment that is attached to the custom element. This Document Fragment contains a new DOM tree that is separate from the main document tree. Any styles or behaviors defined in the Shadow DOM will only affect elements within this new DOM tree.

To attach Shadow DOM to a custom element, developers use the attachShadow() method of the HTMLElement class. This method takes an object with two properties: mode and delegatesFocus. The mode property determines whether the Shadow DOM tree is open or closed, while the delegatesFocus property determines whether the custom element can receive keyboard focus.

class MyElement extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    // Add elements to shadow DOM tree here
  }
}

Once we've created the Shadow DOM tree, we can add elements to it just like we would with the regular DOM. Here's an example:

class MyElement extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const div = document.createElement('div');
    div.textContent = 'Hello, Shadow DOM!';
    shadow.appendChild(div);
  }
}

In this example, we've created a custom element called MyElement, and attached a Shadow DOM tree to it with the mode set to 'open'. We've then created a new <div/> element, set its text content to 'Hello, Shadow DOM!', and added it to the Shadow DOM tree using the appendChild() method.

Examples of how it can be used

Custom input element

Let's say you want to create a custom input element that looks and behaves differently from the standard HTML input element. You can define a custom element with Shadow DOM, and use CSS to style the input element within the Shadow DOM. Here's an example:

class MyInputElement extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({mode: 'open'});
    const input = document.createElement('input');
    input.setAttribute('type', 'text');
    input.setAttribute('placeholder', 'Enter text here');
    shadow.appendChild(input);
    shadow.style.display = 'inline-block';
    shadow.style.border = '1px solid #ccc';
    shadow.style.padding = '5px';
  }
}

customElements.define('my-input', MyInputElement);

In this example, we've created a new custom input element called MyInputElement. We've attached Shadow DOM to this element using the attachShadow() method, and set the mode to 'open'. We then created a new input element within the Shadow DOM, and added some styling using CSS.

To use this custom input element, we simply use the <my-input> tag in our HTML:

<my-input></my-input>

Custom button element

Another example of using Shadow DOM is to create a custom button element. Let's say you want to create a button that has a different look and feel from the standard HTML button element. You can define a custom element with Shadow DOM, and use CSS to style the button within the Shadow DOM. Here's an example:

class MyButtonElement extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({mode: 'open'});
    const button = document.createElement('button');
    button.textContent = this.getAttribute('label') || 'Button';
    shadow.appendChild(button);
    shadow.style.display = 'inline-block';
    shadow.style.border = '1px solid #ccc';
    shadow.style.padding = '5px';
    shadow.style.backgroundColor = '#f0f0f0';
    button.style.border = 'none';
    button.style.backgroundColor = '#f0f0f0
  }
}

customElements.define('my-button', MyButtonElement);

To use this custom input element, we simply use the <my-button> tag in our HTML:

<my-button></my-button>

Use cases

The Shadow DOM has several use cases, including:

Creating reusable web components: With the Shadow DOM, developers can create encapsulated web components that can be used in any web application without interfering with the styles and behavior of other components.
Styling web components: The Shadow DOM provides a way to encapsulate the styles of a web component, so that they don't interfere with the styles of other components on the page.
Creating custom elements with default styles: The Shadow DOM allows developers to define default styles for a custom element, which are applied only to the elements within the Shadow DOM tree.

Advantages of Shadow DOM

Encapsulation

One of the main advantages of Shadow DOM is that it allows developers to encapsulate the styles and behavior of a custom element, preventing it from being affected by styles and scripts outside of its DOM tree. This makes it easier to maintain and reuse custom elements across different parts of the web application.

Improved Styling

With Shadow DOM, developers can use CSS to style their custom elements, without affecting the rest of the document. This means that they can use class names and selectors that would otherwise conflict with styles in the rest of the document.

Improved Performance

Shadow DOM can also improve the performance of web applications by reducing the amount of CSS and JavaScript that needs to be loaded and executed. This is because styles and scripts can be defined within the Shadow DOM tree, rather than in the main document tree.

Disadvantages of Shadow DOM

Complexity

Shadow DOM can be a complex technology to work with, and may require a deep understanding of the web platform and JavaScript to use effectively. This can make it difficult for less experienced developers to use in their web applications.

Legacy Browser Support

Another potential disadvantage of Shadow DOM is that it is not supported in legacy browsers. This can limit the reach of web applications that rely on Shadow DOM, and may require developers to use fallbacks or alternative solutions for unsupported browsers.

Accessibility

Finally, Shadow DOM can have implications for accessibility, as it may prevent users from being able to navigate or interact with the custom element using keyboard navigation. This can be mitigated by ensuring that the custom element is accessible using alternative methods, such as ARIA attributes.

Conclusion

Shadow DOM is a powerful web technology that can provide many advantages to web developers, including improved encapsulation, styling, and performance. However, it also has some potential disadvantages, such as complexity, limited browser support, and accessibility issues.

Despite these challenges, Shadow DOM remains an important tool in the web developer's toolbox, and can be used effectively in many web applications. To use Shadow DOM effectively, it is important to have a deep understanding of the technology and its implications for web development, and to carefully consider the needs of the application and its users.

Fake news: 6 false claims about Web Components

Stefan Nieuwenhuis — Tue, 01 Jun 2021 13:57:58 +0000

6 False claims about Web Components

Web Components aren't supported by browsers
Web Components can't be used in JavaScript Frameworks and Libraries
Web Components are dead
Web Components cannot accept complex data
You are forced to use Shadow DOM
Web Components are Google Technology

About the author

Stefan is a JavaScript Web Developer with more than 10 years of experience. He loves to play sports, read books and occasionally jump out of planes (with a parachute that is).

☞ If you like this article, please support Stefan by buying him a coffee ❤️.

1. Web Components aren't supported by browsers

This screenshot was taken on May 20, 2021, from WebComponents.org, and most browsers, except for IE11 and Safari, offer full support for Web Components.

2. Web Components can't be used in JavaScript Frameworks and Libraries

The support for Web Components in frameworks and libraries like Angular and VueJs is excellent and ever-growing! Just a quick peek at Custom Elements Everywhere tells you that Custom Elements are fully supported by almost every popular framework and library. The only caveat is React. It does support Web Components, but not entirely.

3. Web Components are dead

Many people claim that Web Components are dead, not supported completely and will never find a place in mainstream development, whatever that may be.

But, in fact, the opposite is true. Custom Elements are more popular than ever! More than 10 percent of all page loads in Google Chrome are pages that contain Web Components.

Besides that, companies like Mc Donalds, Apple, GitHub, Twitter, Google, Salesforce, ING & SAP are using Web Components for both their public-facing applications as internal tools.

Browser support is flourishing as well as JavaScript framework support. I think that we safely could say: Web Components have never been so alive!

4. Web Components cannot accept complex data

This idea originates from a fundamental misunderstanding of the DOM and its inner workings. Four misconceptions are:

Custom Elements are HTML Elements.
HTML Elements don't have properties; only attributes.
Attributes can only be strings.
Web Components can only accept strings in attributes.

Custom Elements are indeed HTML Elements but are DOM nodes as well, and because of that, accept complex data as properties, using JavaScript and the DOM.

5. You are forced to use Shadow DOM

Never used Custom Elements without the Shadow DOM? Think again. Just go to GitHub, open the Developer's console and paste the following code:

const isCustomElement = ({ tagName }) => tagName.includes(`-`);
const usesShadowDom = ({ shadowRoot }) => !!shadowRoot;
const allCustomElements = [...document.querySelectorAll(`*`)].filter(
  isCustomElement
);
console.log(`All Custom Elements: ${allCustomElements}`);
console.log(
  `All Custom Elements w/ Shadow DOM: ${allCustomElements.filter(
    usesShadowDom
  )}`
);

Shadow DOM is extremely powerful, because it encapsulates your components and prevents CSS and JavaScript from leaking in and out, but is completely optional. Here's a simple, and shadowless, example that works perfectly:

class ElementWithoutShadowDom extends HTMLElement {
  constructor() {
    super().innerHTML = `<div>A Custom Element without Shadow DOM</div>`;
  }
}

customElements.define(`no-shadow`, ElementWithoutShadowDOM);

6. Web Components are Google Technology

The Web Components specs are open standards with multiple contributors, and stakeholders.

For example:

The HTML Module proposal was picked up by Microsoft.
The HTML Template Instantiation was proposed by Apple.
The IDE standardization for Web Components initiative was lead by the Visual Studio Code (VSCode) Team.

Final thoughts

There are lots of false claims about Web Components, and today, we've debunked six of them. With support from (almost all) browsers, major JavaScript Frameworks and Libraries, and (big tech) companies, its popularity is growing every day. There is no reason why you shouldn't use it.

I hope you'll try this fully native, interoperable, flexible, and reusable technology soon!

[tutorial] How to create a Web Component?

Stefan Nieuwenhuis — Tue, 25 May 2021 16:32:54 +0000

Welcome back to the Web Components 101 Series! We're going to discuss the state of Web Components, provide expert advice, give tips and tricks and reveal the inner workings of Web Components.

In today's tutorial, we're going to teach you the fundamentals of Web Components by building a <name-tag> component step by step!

First, we have to learn the rules. Then, we're going to set up our development environment.

Next, we'll define a new HTML element, going to learn how to pass attributes, create and use the Shadow DOM, and use HTML templates.

About the author

Stefan is a JavaScript Web Developer with more than 10 years of experience. He loves to play sports, read books and occasionally jump out of planes (with a parachute that is).
☞ If you like this article, please support me by buying me a coffee ❤️.

The basic rules

Even Web Components have basic rules and if we play by them, the possibilities are endless! We can even include emojis or non-Latin characters into the names, like <animal-😺> and <char-ッ>.

These are the rules:

You can't register a Custom Element more than once.
Custom Elements cannot be self-closing.
To prevent name clashing with existing HTML elements, valid names should:
- Always include a hyphen (-) in its name.
- Always be lower case.
- Not contain any uppercase characters.

Setting up our development environment

For this tutorial, we're going to use the Components IDE from the good folks at WebComponents.dev. No set up required! Everything is already in place and properly configured, so we can start developing our component straight away. It even comes with Storybook and Mocha preinstalled and preconfigured.

Steps to set up our dev env

Go to the Components IDE
Click the Fork button in the top right of the screen to create your copy.
Profit! Your environment is set up successfully.

Defining a new HTML Element

Let's have a look at index.html.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    highlight-next-line
    <script src="./dist/name-tag.js" type="module"></script>
  </head>

  <body>
    <h3>Hello World</h3>
    highlight-next-line
    <name-tag></name-tag>
  </body>
</html>

On line 5, we include our component with a <script>. This allows us to use our component, just like any other HTML elements in the <body> (line 10) of our page.

But we don't see anything yet, our page is empty. This is because our name tag isn't a proper HTML Tag (yet). We have to define a new HTML Element and this is done with JavaScript.

Open name-tag.js and create a class that extends the base HTMLElement class.
Call super() in the class constructor. Super sets and returns the component's this scope and ensures that the right property chain is inherited.
Register our element to the Custom Elements Registry to teach the browser about our new component.

This is how our class should look like:

class UserCard extends HTMLElement {
  constructor() {
    super();
  }
}

customElements.define('name-tag', UserCard);

Congrats! You've successfully created and registered a new HTML Tag!

Passing values to the component with HTML attributes

Our name tag doesn't do anything interesting yet. Let's change that and display the user's name, that we pass to the component with a name attribute.

Attributes provide extra information about HTML tags, always come in name/value pairs, and could only contain strings.

First, we have to add a name attribute to the <name-tag> in index.html. This enables us to pass and read the value from our component

<name-tag name="John Doe"></name-tag>

Now that we've passed the attribute, it's time to retrieve it! We do this with the Element.getAttribute() method that we add to the components constructor().

Finally, we're able to push the attribute's value to the components inner HTML. Let's wrap it between a <h3>.

This is how our components class should look like:

class UserCard extends HTMLElement {
  constructor() {
    super();

    this.innerHTML = `<h3>${this.getAttribute('name')}</h3>`;
  }
}
...

Our component now outputs "John Doe".

Add global styling

Let's add some global styling to see what happens.

Add the following CSS to the <head> in index.html and see that the component's heading color changes to Rebecca purple:

<style>
  h3 {
    color: rebeccapurple;
  }
</style>

Create and use the Shadow DOM

Now it's time to get the Shadow DOM involved! This ensures the encapsulation of our element and prevents CSS and JavaScript from leaking in and out.

Add this.attachShadow({mode: 'open'}); to the component's constructor (read more about Shadow DOM modes here).
We also have to attach our innerHTML to the shadow root. Replace this.innerHTML with this.shadowRoot.innerHTML.

Here is the diff of our constructor:

...
constructor() {
  super();
  this.attachShadow({mode: 'open'});
- this.innerHTML = `<h3>${this.getAttribute('name')}</h3>`;
+ this.shadowRoot.innerHTML = `<h3>${this.getAttribute('name')}</h3>`;
}
...

Notice that the global styling isn't affecting our component anymore. The Shadow DOM is successfully attached and our component is successfully encapsulated.

Create and use HTML Templates

The next step is to create and use HTML Templates.

First, we have to create a const template outside our components class in name-tag.js, create a new template element with the Document.createElement() method and assign it to our const.

const template = document.createElement('template');
template.innerHTML = `
  <style>
    h3 {
      color: darkolivegreen; //because I LOVE olives
    }
  </style>

  <div class="name-tag">
    <h3></h3>
  </div>
`;

With the template in place, we're able to clone it to the components Shadow Root. We have to replace our previous "HTML Template" solution.

...

class UserCard extends HTMLElement {
  constructor(){
    super();
    this.attachShadow({mode: 'open'});

-   this.shadowRoot.innerHTML = `<h3>${this.getAttribute('name')}</h3>`;
+   this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
}
...

What about passing attributes?!

Although we've added some styles, we see a blank page again. Our attribute values aren't rendered, so let's change that.

We have to get out attribute's value to the template somehow. We don't have direct access to the components scope in the template, so we have to do it differently.

<div class="name-tag">
  <h3>${this.getAttribute('name')}</h3>
</div>

This won't work since we don't have access to the component's scope in the template.

We have to query the Shadow DOM for the desired HTML Element (i.e. <h3>) and push the value of the attribute to its inner HTML.

constructior() {
  ...
  this.shadowRoot.querySelector('h3').innerText = this.getAttribute('name');
}

The result is that we see "John Doe" again on our page and this time, it's colored differently and the heading on the main page stays Rebecca purple! The styling we've applied works like a charm and is contained to the Shadow DOM. Just like we wanted to: No leaking of styles thanks to our component's encapsulating properties.

Bonus: Update styles

Update the <style> in the template to make our component look a bit more appealing:

.name-tag {
  padding: 2em;

  border-radius: 25px;

  background: #f90304;

  font-family: arial;
  color: white;
  text-align: center;

  box-shadow: 2px 2px 5px 0px rgba(0, 0, 0, 0.75);
}

h3 {
  padding: 2em 0;
  background: white;
  color: black;
}

p {
  font-size: 24px;
  font-weight: bold;
  text-transform: uppercase;
}

Closing thoughts about how to create a Web Component from scratch

The game of Web Components has to be played by a handful of basic rules but when played right, the possibilities are endless! Today, we've learned step by step how to create a simple, <name-tag> component by defining Custom Elements, passing HTML attributes, connecting the Shadow DOM, defining and cloning HTML templates, and some basic styling with CSS.

I hope this tutorial was useful and I hope to see you next time!

Web Components 101: Why use Web Components?

Stefan Nieuwenhuis — Fri, 21 May 2021 00:00:00 +0000

Welcome back to the Web Components 101 Series! We're going to discuss the state of Web Components, provide expert advice, give tips and tricks and reveal the inner workings of Web Components.

In this article, we'll explain why we're so excited about Web Components and why you want to use them. We also do some myth-busting along the way. Are you excited already?

About the author

Posts in the Web Components 101 series

What are Web Components?
Why use Web Components? (this post)

Why use Web Components?

JavaScript frameworks offer lots of advantages:

Save energy. Modern JavaSCript frameworks are packed with best practices, scaffolding tools, paradigms, and industry standards, which enables us to build and publish an app in no time. It enables developers to focus on actual development instead of the tools and architecture.
Reusable code. Components built with a JavaScript framework are interchangeable (within applications using the same framework), so teams don't have to invent the square wheel twice.
A common language for everyone. Using a JavaScript framework generates a common understanding between developers. Everyone "speaks" the same, common language and is on the same page.

It's not surprising that almost every JavaScript app is built with a (modern) JavaScript framework or library, so why should we use Web Components instead of using our favorite framework? What problems does providing a native component model solve?

(Brand) Consistency

Consistent applications offer user-friendly interfaces and have high conversion rates. Inconsistent applications offer the exact opposite and undermine brand consistency. Having your apps split up into component libraries or a Design System, improves brand consistency but if and only if they are compatible with all different tech stacks.

Web Components, with its web-standards-based APIs, is interchangeable between all different tech stacks and JavaScript frameworks and libraries and provides the perfect technical base for brand consistency throughout all applications.

Maintainability

Building sustainable and maintainable applications is one of the hardest challenges in Web Development. Code is continuously copied from one (part of the) application to another, essentially creating new versions that have to be maintained indefinitely, which results in maintenance hell.

Web Components can be maintained by one (team of) developers and shared with others. The maintainers take care of the components, while the consumers can fetch updates automatically (e.g. with npm) and continue their work without the fear of maintenance hell.

Reusability

Keep It Simple Stupid, and Don't Repeat Yourself are the mantra's that we keep repeating and is a key part of building comprehensible, maintainable, and reusable apps. It is one of the hardest challenges in web development. With Web Components, we're solving this by defining markup in JavaScript. The author is free to change the HTML, CSS, and JavaScript, while the consumer can benefit from the changes automatically without the need of upgrading the code manually.

Interoperability

JavaScript frameworks like Angular, React and VueJs are awesome! They are packed with best practices, scaffolding tools, paradigms, and industry standards, which enable us to build and publish an app in no time, but aren't very interoperable - they don't communicate with each other very well. This is because they all have different, non-interchangeable component models.

Web Components are completely based on web standards and are compatible with (or without) any JavaScript library or framework. That means, that they are completely interoperable between frameworks and applications. It now becomes possible to support multiple applications with UI components from a single codebase (Design Systems and mono repositories).

Readability

The most important audience for our code is humans (ourselves and other people), as we are the ones who will make or break the program in the future. Unfortunately, this doesn't always resonate and many HTML pages end up in an expressionless, and unreadable <div/> soup, like Google's Gmail page:

Web Components allows us to organize the <div/> soup into comprehensible, readable, semantic-friendly code by creating custom elements wherever we see fit. Here's an example of how it would look like:

<google-mail>
  <mail-list>
    <mail-item from="john.doe@company.com">
      <h2>Hello World</h2>
      <article>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
      </article>
    </mail-item>
  </mail-list>
</google-mail>

Full encapsulation

The Shadow DOM allows web browsers to isolate DOM fragments. It means that we don't have to worry about styles and logic leaking to and from our Web Components. In other words: They are fully encapsulated.

Web Components are perfectly compatible with any JavaScript framework of library

)

As mentioned in the first article of the Web Components 101 Series, the support for Web Components from JavaScript frameworks and libraries is excellent and growing! Web Components can be used with:

Angular
AngularJs
React
Vue.js
Svelte
Vanilla JavaScript

Busting myths about Web Components

Why not use Web Components? There are a lot of myths about why not to use Web Components. The main reason is that they are built on evolving web standards, which have their flaws and limitations. I've seen some myths go around and now it's time to bust them!

Web Components can't be server-side rendered (SRR)

Busted! Since Web Components are based on web standards, they can be server site rendered perfectly. It might be hard to do if you build a solution from scratch, but libraries like SkateJs and Stencil will do all the heavy lifting for you.

Web Components don't work with JavaScript frameworks/libraries

Both true and false. As mentioned in the first article of the Web Components 101 Series, all JavaScript frameworks, except React are fully compatible. React supports Web Components, but passes all data to Custom Elements in the form of HTML attributes. For primitive data this is fine, but the system breaks down when passing rich data, like objects or arrays. Developers will need to reference their Custom Elements using a ref and manually attach event listeners with addEventListener.

Web Components aren't accessible (a11y)

Busted! The main reason why folks think that Web Components aren't accessible is that HTML content is included in the Shadow DOM and not the main DOM, but in reality, this doesn't affect accessibility at all! The a11y information is exposed correctly through the accessibility API and screenreaders can access content in the Shadow DOM without any difficulties.

Web Components aren't production-ready

Busted! Folks assume that because Web Components are built on evolving web standards, they aren't production-ready but that's not true! All W3 standards are continuously evolving and that means that no technology would ever be production-ready, which is nonsense.

Besides that, Apple, Salesforce, and GitHub are all using Web Components in production. Do you need more proof?

Closing thoughts about why we use Web Components

Although JavaScript frameworks and libraries offer developers many perks, they have their drawbacks as well and this is where Web Components can fill the gap perfectly. Based on web standards, Web Components are perfect for (brand) consistency, are maintainable, reusable, interoperable, and readable. They are also fully compatible with (or without) any JavaScript framework/library and offer full encapsulation.

Many myths account for a negative image of Web Components and why folks aren't using them, but most of them are busted and nothing stands in the way of you using their full potential!

Web Components 101: What are Web Components?

Stefan Nieuwenhuis — Thu, 20 May 2021 20:10:36 +0000

Welcome to the Web Components 101 Series! We're going to discuss the state of Web Components, provide expert advice, give tips and tricks and reveal the inner workings of Web Components.

Today, more than 10% of all page loads in Google Chrome are pages that contain Web Components! Big tech companies like Apple, Google and Facebook are also investigating ways of using Web Components in their applications and JavaScript Frameworks (e.g. Angular and React). Quite impressive for a technology officially introduced in 2011 and standardized only recently.

Web Components are getting more popular everyday, that's why this is the perfect moment to start learning about this awesome technology!

About the author

Posts in the Web Components 101 series

What are Web Components? (this post)
Why do you need Web Components? (coming soon)

What are Web Components?

Web Components are full HTML elements with custom templates, APIs and Tag Names. They allow you to create new HTML tags, extend existing HTML tags or extend the components from other developers. They can be used in any web application, are compatible with (or without) any JavaScript library or framework (e.g. React, Angular, Vue.js, Next.js) and will work with all modern browsers.

Its foundation is its API, which brings a Web Standards-based way to create reusable components using nothing more than vanilla JavaScript, HTML and CSS.

The four Standards used are:

Custom Elements.
HTML Templates.
Shadow DOM.
ES Modules.

Let's have a more detailed look at these Web Standards.

1. Custom Elements

Custom Elements is a set of APIs that allows you to create new HTML tags. With this API, we can instruct the parser how to properly create an element and how it reacts to changes.

There are two types of custom elements:

An autonomous custom element, which can be used to create completely new HTML elements.
A customized built-in element, which can be used to extend existing HTML elements or other Web Components.

So, the Custom Elements API is very useful for creating new HTML elements, but for extending existing or other Web Components as well.

2. HTML Templates

With HTML templates, we can create reusable code fragments inside a normal HTML flow that aren't rendered immediately. They can be cloned and inserted in the document during runtime with JavaScript and scripts, and resources inside will not be fetched or executed until the template is stamped out. It also doesn't matter how many times a template is used, since it's cloned in the browser and only parsed once; A great performance boost!

A HTML Template syntax looks like this:

<template>
  <h1>Web Components 101</h1>
  <p>HTML Templates are awesome!</p>
</template>

When the page renders, a template is empty. The contents are stored in a DocumentFragment without browsing context. This is done to prevent it from interfering with the rest of the application, meaning that it only renders when requested; Another performance boost!

3. Shadow DOM

The Shadow DOM API allows web browsers to isolate DOM fragments (including all HTML and CSS) from the main documents DOM tree. Its inner working are almost similar to that of an <iframe/> where the content is isolated from the rest of the document, with the main difference that we still have full control over it.

What is the DOM?

With HTML, we're able to easily create pages that have both presentation and structure. It's very easy for us humans to understand, but computers need a bit more help: Enter the Document Object Model, or DOM.

When the browser loads a web page, it translates the author's HTML into a data model, which is stored in a tree of nodes. This tree is called the DOM and is a live representation of the page. It has properties, methods and the best part is that it can be manipulated by...JavaScript!

The Shadow DOM shields it contents from its surrounding environment (a process called encapsulation), which prevents CSS and JavaScript code from leaking from and to a custom element.

ES Modules

Before ES Modules, JavaScript did not have a module system like other programming languages. Developers resorted to using <script/> tags to load JavaScript files into their applications and later on, several module definitions started (e.g CommonJS, AMD & UMD) to appear but none matured to a standard. This changed with the introduction of ES Modules and we finally have a standard module system.

The ES Modules API brings a standardized module system to JavaScript, which provides a way of bundling a collection of features into a library that can be reused in other JavaScript files.

Web Components and Browser Support

Which browsers support Web Components? Currently, all Evergreen browsers (Chrome, Firefox and Edge) offer full support for Web Components. That means, all APIs (i.e. Custom Elements, HTML Templates, Shadow DOM and ES Modules) are fully supported!

This screenshot from WebComponents.org shows the current browser support for Web Components.

Internet Explorer

Unfortunately, Internet Explorer 11 doesn't support Web Components, but Microsoft stops supporting IE11 on August 17, 2021, and in the meantime, polyfills are available to simulate the missing browser capabilities as closely as possible.

Safari

Safari does support Web Components, but it does not support Customized Built-in Elements, only Autonomous Elements. Luckily, the polyfills offer support for Safari as well.

Closing thoughts about Web Components

Modern Web Development becomes more complex everyday, and, now that the Web Platform and its standards are maturing, it makes more sense to use them more intensively. Web Components are the perfect example, based on 4 web-standard based APIs (Custom Elements, HTML Templates, Shadow DOM, and ES Modules).

It's ever increasing popularity proofs that Web Components are here to stay and that now is the perfect time to start learning about this amazing technology!

In the second post of the series, we're gonna discuss why Web Components are so amazing and why you want to use them.

Merry Christmas! And a happy new year!

Stefan Nieuwenhuis — Tue, 24 Dec 2019 14:47:45 +0000

Have a break from your work and spend time with your family and the ones you love. It's a holiday, so enjoy it to the fullest.

With love,

Stefan

3 reasons why I went framework agnostic and why you should do that too

Stefan Nieuwenhuis — Fri, 20 Dec 2019 10:06:25 +0000

I’m a web developer since 2003 and I’ve seen lots of tech stacks come and go. Back then there was no such thing as a JavaScript framework and the language was not as advanced as it is today. It was even considered an inferior language, compared to Java and C (while it actually is a completely different thing). With the introduction of frameworks like React, Angular and VueJs JavaScript finally became mainstream and now the web depends on it.

Today’s web is impossible to imagine without JavaScript frameworks. Building JavaScript applications with the help of a framework provide lot’s of advantages like:

Save energy. Modern JavaScript frameworks are packed with best practices, scaffolding tools, paradigms and industry standards which enables developers to set up an app in no time. It enables developers to focus on developing the actual app instead of the tools and the architecture required.
Reusable code. Components build with a JavaScript framework are interchangeable, so teams don’t have to invent the square wheel twice.
A common language for teams. Using a JavaScript framework generates a common understanding between both front- and backend developers. Everyone speaks the same, common language. It’s because of these benefits that almost all frontend development teams are using JavaScript frameworks to build apps.

The other side of the coin…

In my time as a web developer, I’ve worked on numerous projects and a new project always starts with choosing a suitable JavaScript framework. What a perfect way to start a project! A framework will solve all of my problems and will save me a lot of time and energy! Other teammates and even other teams will completely understand the architecture and components I’ve built, Right?

Let me give you 3 real-world examples from companies I worked for:

I used to work for an enterprise-size company where multiple frontend development teams worked on different parts of an app. All teams choose Angular as their preferred JavaScript framework. Together they’ve built a shared components library in Angular (v2) to save time, money and energy, but there was a catch. Angular (v4) came out and a few teams did an upgrade. The new version contains some breaking changes and the teams quickly realized that the shared components became useless. The idea of the shared components library was to save time, money and energy, but the opposite was actually the case. Teams have to invest extra time, money and energy in upgrading the shared components library; A waste and a source of frustration.
Another project I worked on was for another enterprise company that has developed an app in AngularJs. It still works, but the responsible team has moved on and did other projects and so is their tech stack. They moved forward and switched to Angular as their preferred JavaScript framework. New team members are hired and aren’t expected to learn AngularJs anymore. But guess what? That application, built with AngularJs, which still is going strong needs a new feature to provide a better user experience to the customers.
I worked for a company where multiple frontend development teams, with different tech stacks, worked on different parts of an app. The teams are known to be self-steering and very autonomous. A challenge for companies that want to provide a consistent user experience and look-and-feel to end-users. The big problem for the teams (and the company) is that components are unexchangeable between teams, which is hugely time-consuming and cost-inefficient.

The common theme running through these real-world examples is inefficiency and I bet that it happens in your company too.

The challenge as a company is to increase autonomy within teams and leave them free in the stack choices they make, but in the meantime, you also want to produce high-quality products without incurring too many costs.
The challenge for development teams is not te be held back by legacy or tech stacks which doesn’t suit the way a team works. Developing must be fun for a team in order to produce high-quality apps.

Companies where development teams building apps with modern JavaScript frameworks like Angular, React or VueJs will face the following challenges:

Migrating applications to other frameworks or even upgrading them is very time consuming, very costly and very frustrating
Components can’t be exchanged between teams, resulting in reinventing the wheel several times which results in wasted time, money and energy.
It’s very time consuming, hence a waste of money and energy, to provide a generic look and feel between different parts of an application developed by several teams with a different tech stack

How to face those challenges?

Hello framework-agnostic web components!

Note: If you’re not familiar with framework-agnostic web components, there is a very good introduction you can read here.

Framework agnostic components libraries will provide a solution for the challenges described above. The idea of framework-agnostic components libraries is pretty simple but rather complex to do. Development teams are still able to choose a tech stack fit to their needs and develop their part of an app. In that way, the autonomy of teams is guaranteed and productivity will stay enhanced. At the same time, a company develops a framework independent components library, which components are interchangeable between development teams. The key to success is the interchangeability between teams and the agnostic character of components.

3 reasons why you should switch to framework-agnostic components libraries

Here is why you should switch to framework-agnostic components libraries:

No more legacy code. It’s very easy to migrate or upgrade your stack because all the components in the library are framework agnostic. Hence compatible with every tech stack.
No more reinventing a square wheel over and over again. Components are compatible with every stack, so there is no need to build the same with different tech stacks. Just imagine how much time, money and frustration that will save!
With generic components, it’s easy to provide a uniform look and feel to an application, built by several teams with different tech stacks.

Stefan helps developers to become Framework Agnostic. If you find his content helpful, you can buy him a coffee here and get his exclusive e-book "10 reasons to go framework-agnostic" for free!

How to build a modal window with Stencil TDD style?

Stefan Nieuwenhuis — Thu, 19 Dec 2019 11:03:59 +0000

Allow me to show you how to build a modal window with Stencil.

Coding with relatively new tools can be challenging due to the lack of (good) tutorials. Especially when you have a specific thing like a modal overlay in mind.

So, that’s why I’ve decided to build my own modal overlay component with StencilJS and share my experiences and to write this tutorial to help you understand the possibilities of StencilJS.

Check out this repo for the source.

What is Stencil?

Stencil is a compiler that generates Web Components which combines the best concepts of the most popular frameworks into a simple build-time tool. It provides extra API's that makes writing fast components simpler. APIs like Virtual DOM, JSX, and async rendering make fast, powerful components easy to create, while still maintaining 100% compatibility with Web Components.

The developer experience is also tuned and comes with life reload and a small dev server baked into the compiler.

Stencil was created by the Ionic Framework team to help build faster, more capable components that worked across all major frameworks.

Let’s start building a Modal

One common and frequently used UI component is a modal window, a content container that displays above the rest of the content and contains a clear call to action. It’s sometimes accompanied by an overlay that covers the rest of the web page or app. And that is what we’re going to build today!

Component design

The name of our component is my-component. This is the default name generated by the starter and for convenience and keeping this tutorial in scope, I’ve decided to let the name as is. You’re completely free to rename it at any time.

It has the following attributes:

Open<boolean>: Shows the modal window component;
Transparent<boolean>: Toggles transparency of the overlay;

The components has the following method:

render: Renders content to the screen.

Setting up our application

Before we can start building the component we have to set up a development environment, which is very easy with the starter, provided by our friends from Stencil.

Note: You need npm v6 or higher in order to complete this tutorial!

Stencil can be used to create standalone components or entire apps. Open a new terminal window and run the following command:

npm init stencil

After running init you will be provided with a prompt so that you can choose the type of project to start.

Since we’re building a single component, select the third option, which generates a development environment, installs all necessary dependencies and scaffolds the component’s code.

The next step is to provide a name for the project. For this tutorial, it doesn’t really matter which name you pick. I wanted to be extremely original and named my project: my-modal.

Stencil provides the developer with a very basic, hello world example to understand a bit better what’s going on and how an application is organized. It’s not in the tutorial’s scope to elaborate on this, but you can read more about this here.

Alright! We’re done setting up our application’s infrastructure!

Writing our first tests

Since we’re creating a component TDD style, let’s start off right away with writing our first tests.

Stencil provides many utility functions to help test Jest and Puppeteer. For example, a component’s Shadow Dom can be queried and tested with the Stencil utility functions built on top of Puppeteer. Tests can not only be provided mock HTML content, but they can also go to URLs of your app which Puppeteer is able to open up and test on Stencil’s dev server.

The starter generated a test file already (./src/components/my-component/my-component.e2e.ts), which contains a few basic unit tests to get the gist on testing Web Components. Open this file, study it and replace it with the following content:

What happened?

We import the necessary packages from the testing libraries provided in Stencil core.
We create a my-component element and append it to the DOM. This is done in the beforeEach method, which is called before every unit test.
We expect that my-component successfully renders in the DOM.
We expect that we find a div decorated with a class, called overlay.

Let’s run our tests with the following command:

npm run test

…Only to see that all of them fail. So let’s change that immediately!

Open ./src/components/my-component/my-component.tsx, study the example code and replace it with the following:

Notice the following parts of the component:

The @Component decorator. This decorator provides metadata about our component to the compiler.
You find a default ES6 JavaScript Class right under the decorator. This is where you’ll write the bulk of your code to bring the component to life.
In the class you find the render() function. This is used by the component to render content to the screen. It returns JSX.
In the HTML template, you find a <slot/> container, which is a placeholder inside a web component that you can fill with your own markup.

Learn more about Stencil components here.

If we run the tests again, they all pass. Hooray! Now it’s time to implement more logic and make our component actually useful.

Opening the modal window

Before we start implementing the logic for opening the modal, let’s write some more tests.

We want to cover the following cases:

It should display the overlay while the modal is open.
If set, the overlay should be transparent.

This results in the following test cases, which you need to add to the test file:

Whoah! What happened here?

We set different properties (open & transparent) with the component.setProperty() method.
We wait for the changes made to the component with the waitForChanges() method. Both Stencil and Puppeteer have an asynchronous architecture, which is a good thing for performance. Since all calls are async, it's required that await page.waitForChanges() is called when changes are made to components.
We check if the element is decorated with the expected CSS classes.

Read more about testing Stencil components here.

And, of course, if we run our tests they’ll fail miserably again, so let’s open the component’s code (my-component.tsx) and make the tests pass.

What did we do?

We’ve added properties open & transparent. They can be recognized by the @Prop() decorator, a class that’s imported from @stencil/core.
We’ve changed our class definition in the HTML template and check if we need to make the modal visible and make the overlay transparent.

Closing the modal window

In order to close the modal, we need to set the open property to false. We’ll implement a method for that in our sample code later.

Let’s write the tests necessary and make them pass:

All tests are in green again and we have a fully operating modal, which looks terrible…

Add the following styling classes to ./src/components/my-component/my-component.css:

Looks much better now!

The proof is in the pudding

All that we’ve done is writing tests and make them pass by adding code to the component, but the real proof is to check if it actually works, so let’s update our index.html file.

Here we create an instance of the component itself and decorate it with an id in order to be able to access it later on. We also added a button, which acts as a trigger to open the modal.

In the script, we created two references. One for the modal component and one for the button. Next, we’ve created two events to test if opening and closing it works properly.

Last, but not least, we added an eventListener to the modal itself, which listens for a click event. If it’s triggered, the modal will close.

It’s a wrap

That’s it! There’s much room to improve this component, like extending the modal content container template with a header and footer, cancel/confirmation buttons, etc. etc. If you see any points for improvement or spot a mistake in my code, please please leave create a pull request or leave a message in the comments!

Feel free to check out the code in this git repository.

Stefan helps developers to become Framework Agnostic. If you find his content helpful, you can buy him a coffee here and get his exclusive e-book "10 reasons to go framework-agnostic" for free!