Forem: Tim Smith

Who needs an accessible website?

Tim Smith — Wed, 12 Feb 2025 17:28:00 +0000

Have you ever tried using a website while blindfolded? For many people, it would be near impossible to do, even with the most accessible of websites. There are people who use the web every single day with a variety of disabilities which can impact their user experience, yet too few frontend developers concern themselves with such experiences.

In some cases, I believe this lack of concern stems from a lack of knowledge on coding for accessible experiences. In other cases, developers may not even be aware of their users with disabilities or know that those users may be struggling to use the website. The worst offenders, in my opinion, are the developers who cut accessibility from their code because it isn't seen as a sexy new feature, although I'm sure there are many users who would disagree.

In this article, I will discuss some specific users to keep in mind when designing and building an accessible website. In addition, I will demonstrate ways in which a poorly designed UI or UX can lead to difficulty when using the web.

How do we use the web?

Surfing the web has become ubiquitous in our society and many of us have been doing it since we were young. It's become an intuitive and almost second nature experience to open a browser, load a website, and consume content.

Because it's become such a mundane part of existence, I have never spent much time thinking about how I'm even interacting with the device. If someone asked what senses you use when you visit a webpage, what would you say? The most obvious one for most people would be sight, but there are other senses which may be less obvious.

Using three senses while on a website

On any given website, we will likely be using a combination of 3 different senses as we interact: vision, hearing, and touch. The way in which we use these senses depends on the website being visited, the content to consume, and the conditions under which we're visiting the site. Below, I have listed a few ways that each of these senses are used when visiting a webpage:

Vision: Used when reading text, looking at an image, or watching a video
Hearing: Used when a noise plays, a video has sound, or music is playing
Touch: Used when a phone responds with a vibration

The majority of users to a website will be able to mix and match these senses for an immersive experience. There is, however, a minority of users who may not be able to use all 3 senses.

What if any of those three senses are missing?

So now the question is, what happens when one or more of those senses aren't available when using a site that was intended to be used with all 3? If proper precautions are not taken when the page is being built, the page could become unusable for a visitor.

I think most developers would agree that the more people who can use our stuff, the better it can be. To begin working toward everyone being able to use your site, it's important to know why those senses are unavailable and plan accordingly. This is where accessibility comes into play.

Disabilities which affect user experience

Although I'm sure you've guessed that there are disabilities related to vision, hearing, and touch which may hinder someone's ability to use your site, there are actually a few others to consider as well. I will be discussing 4 separate disabilities which can be affected and considerations we can take as engineers to make their experience on our products just as enjoyable as those without disabilities.

Visually impaired users

When we think of visually impaired people, we tend to think about people who are legally or completely blind. While users who fall into these categories should be considered when building a webpage, visual impairment is not limited to these two buckets.

While talking about ways to address accessibility concerns, let's go over the primary types of visual impairment to consider.

Nearsightedness and farsightedness

The first group to consider when implementing accessibility into a webpage are users with Myopia (nearsightedness) and Hyperopia (farsightedness). While many of these users will wear glasses to assist them in viewing your webpage, there are still measures which can be taken to ensure a more positive experience such as keeping font sizes at a minimum of 15-16px.

Blindness

Although we already mentioned users with blindness, it's worth discussing in greater detail who they are and how they interact with a webpage. Users with this disability typically don't have any vision at all. To make technology easier to use for those without eyesight, screen readers such as JAWS, NVDA, Windows Narrator, or Apple VoiceOver can be used to navigate and consume information.

Color blindness

Color blindness is not generally thought of as a disability, even though it can dramatically affect the way in which a user interacts with UI elements. For instance, if a website has instructions that are color based such as "Click the green button", that will be a difficult user interface to navigate.

In addition, there should be an adequate contrast between background and foreground colors to ensure maximum readability. If you're unsure about the contrast on your website, you can use a tool like the WebAIM contrast checker to determine if the level of contrast on your site meets accessibility standards.

Limited vision

The final group of users with visual impairments to consider are those with limited vision. This is often caused by cataracts, glaucoma, macular degeneration, and more. Fortunately, if you've taken the precautions already mentioned for visually impaired users, there shouldn't be any additional work necessary for colors and sizes.

Anyone having difficulty seeing

To help illustrate why implementing accessibility into a website is important for everyone, we can even broaden the scope of the users we're building for. Not all users have visual impairments, but anyone (visually impaired or not) could be browsing a website while in direct sunlight which can make it difficult to read. Ensuring there is sufficient contrast and the font size is large enough can even help those trying to use the web under temporarily difficult conditions.

How to make your site more accessible for visually impaired users

As discussed above, there are multiple steps which can be taken to allow the maximum number of users to interact with your website if they have visual impairments.

Make sure the contrast between your foreground and background colors meet accessibility standards
Don't assign value to colors alone
Keep font sizes large enough that they are easily readable
Ensure that screen readers are able to find and read the information

Hearing impaired users

There are also a significant number of internet surfers who are deaf or hard of hearing. While these users may be able to interact with the site visually, there are still steps we can take to ensure maximum usability on the site.

Before going over solutions to improve the user experience for those with hearing impairments, let's look at who could fall into this category.

Deaf

A user who is completely deaf will not be able to hear any audio on your website. This could include notification bells, music, or audio from various media sources.

Hard of hearing

Users who are hard of hearing have some sort of hearing loss which makes it difficult to hear or understand everything, particularly at lower volumes. While these users may be able to hear sounds on your website, they can also benefit from the steps taken to accommodate the deaf users.

Anyone in a loud environment

If you've ever been at a loud restaurant or concert and try to watch a video or listen to something, you know how difficult it can be to get all the information being presented. Anyone in this situation will also be able to use the web more easily if precautions are taken for those with an auditory impairment.

To illustrate how information can be misconstrued if a video is not properly captioned, I will direct your attention to a meme from the mid 2000s.

How to make your site more accessible for audibly impaired users

The solutions for those with hearing impairments are the same, regardless of the level or reason for impairment.

When using a sound, also provide text for the user to read (captions for videos and audio transcriptions)
Avoid adding music to spoken word, where possible, as this can make the spoken word more difficult to understand

Users with motor impairments

There are varying levels and reasons for motor impairments, but it's important to build in accommodations for each level of impairment.

Loss or damaged limbs

A user who is missing limbs or is limited in the use of their limbs may find it difficult to use and navigate on your website.

Loss of fine motor skills

Some users may have the use of all of their limbs, but lack the dexterity to use them for minute functions such as clicking on small buttons or links. Users who fall into this category could include those with Parkinson's disease or Rheumatism (arthritis).

Anyone on a bumpy car or train ride

Trying to accurately press a button or link can be difficult when the device being used is moving all over the place. While temporary, this also qualifies as a motor impairment and users in this circumstance will also find it easier to use your website if accommodations are made.

How to make your site more accessible for users with motor impairments

Improvements to your website for those with motor impairments will come in the form of support for different input technologies and UI element sizes.

If I were to ask you to click the buttons in the demo below, you may not have any trouble doing so since both buttons are stationary. This gets more difficult if the targets begin moving. To simulate motion in the demo, simply check the "Show motion" checkbox. Though it is a contrived example, it demonstrates how the buttons could move if the device being used is moving around quite a bit for the user.

After enabling motion, try to click the small button and then try to click the large button. I'm willing to bet that, of the two, the larger button is easier to click. This is because the target for the user to click is larger, so it doesn't require as much finesse to do.

So how do we make our websites more accessible for those with motor impairments?

Make sure navigation and interaction is possible with a keyboard alone for those who cannot use a mouse
Keep targets large if possible to reduce difficulty in interacting with various elements

Users with cognitive impairments

The final type of users we will discuss today are those with cognitive disabilities. This category covers a wide variety of conditions and situations, though most can be addressed with only a few precautions. Let's take a look at some potential cognitive impairments to plan for.

Autistic users

A visitor to your website with autism will likely be easily distracted and may find inconsistencies in navigation frustrating. To improve their user experience, try to keep page navigation as simple as possible.

Attention Deficit Hyperactivity Disorder (ADHD)

Users with ADHD will be distracted by movement on the site and find it hard to concentrate on long passages of text. To help with this, either eliminate motion altogether or provide an option to limit the motion and try to break up text into smaller chunks.

Users with anxiety

Some users visiting your site may have anxiety, feeling a lot of pressure to use the site in a certain way or accomplish certain tasks. If the site is unclear about usage or next steps, it could cause a user with anxiety to panic. To help these users, provide clear and concise instructions for users and don't put time limits on things where possible.

Users with dementia and Parkinson's dementia

Although users with dementia and Parkinson's dementia may not experience panic in the same way as a user with anxiety, they will likely take longer to comprehend the directions and complete tasks on the website. Fortunately, the steps you take to help users with anxiety will also help those with dementia. Simply providing adequate instructions and avoiding time limits will improve user experience dramatically. Score!

Temporary cognitive impairments

Also important to consider when building out websites are those with temporary cognitive impairments. I know what you're thinking: what are temporary cognitive impairments? I'm glad you asked. Anyone can experience temporary cognitive impairments since they are typically based on situations and circumstances.

Below are some examples of temporary cognitive impairments to account for:

Tired
Drunk
Hungover
High
Irritated
Angry
Distracted
Grieving

While there aren't any steps to take directly for these conditions, implementing code for the previous cognitive impairments should improve the user experience for these users as well.

Simple steps to take to improve accessibility

There are a few things you can do immediately to improve the accessibility of your site. Below you will find information about those improvements.

Problem	Solution
No information about buttons in screen screen reader (play, pause, etc)	Add `aria-labels` to buttons or links which lack useful or descriptive text
Poor heading structure in the data	Ensure headings are being properly utilized to make documents easy to understand (h3 should not be a direct descendant of an h1)
Modals, alerts, or other UI elements may not get focus which makes it difficult to interact with them	Try to avoid UI elements which cover the screen. If necessary, make sure they get focus and can be used with only a keyboard

Conclusion

You never know who is going to visit your website or what challenges they may face in using your site, so implementing methods for maximum usability is imperative. The first step to improving the accessibility on your site is to understand those who may be using the tools you're building.

In this post, we've discussed several potential visitors, what challenges they may face when using your website, and some ways you can improve their experience based on those challenges. Go forth and make the web a more accessible place!

If you have any thoughts or questions, feel free to reach out to me on X (Twitter) at @iam_timsmith.

Dialogs vs. Modals: Is there a difference?

Tim Smith — Thu, 21 Sep 2023 15:36:35 +0000

You may hear developers talking about dialogs and modals on websites as being similar things. Are they really the same though? The answer is: sort of. Modals are a type of dialog, but not all dialogs are modals. They do have similar appearances and functionality, but with a key difference. In this blog post, I'll explore modals and dialogs and explain the difference while showing you how they can be used natively in the browser.

Please note: I will be using the term "dialog" to represent a non-modal dialog and the term "modal" to represent a modal dialog. This is to describe the behavior of each rather than the HTML element to build them.

Dialogs and modals?

While both dialogs and modals can appear similar, there are different reasons for using each. First we'll discuss what they are and how they're used and then we'll discuss how they're different.

How are dialogs and modals similar?

Dialogs and modals can serve similar purposes: to display some data or collect some data outside the flow of the normal document. This could be a form collection, a call-to-action, or something similar that you want to be front-and-center for a user. Typically, people refer to these things as "popups".

I'm sure you've seen them all over the web if you've been using the internet for any amount of time. Typically, people complain about these because they can be disruptive when using a website. Because of this, it's important to use them in this fashion sparingly. One of the two items is more disruptive than the other though...

How are dialogs and modals different?

The way in which dialogs and modals differ has to do with how it allows the user to interact with the document when it's open. What does that mean? Let's talk about each one:

A dialog still allows a user to interact with other content on the page while it's open (i.e. click buttons and links visible around the dialog)
A modal locks down the page until something is done. This is typically done with a background that covers all other content so the modal must be dealt with. This is the more disruptive of the two options.

Understanding the differences between the two will allow you to make the right choice about which option is best for your situation. As a general rule, you should reach for the dialog unless it's absolutely necessary to prevent the user from interacting with other elements.

The dialog element

In years past, building dialogs and modals consisted of nesting divs inside of divs while applying some styles to make it look and behave a certain way using javascript and css. While some of this is still necessary due to it's interactive nature, the dialog has come a long way since then.

One of the big problems around the dialog components of old are a lack of accessibility. They just weren't easy to understand and use with screen readers. There was a role="dialog" attribute which could be applied, but many times accessibility is unfortunately an afterthought.

Despite this, the web has evolved quite a bit in the last several years to make accessibility much more "baked in" through the use of semantic elements. Because of this, we have a dialog element in HTML5 which takes care of a lot of these things for us. In addition to being accessible, the dialog element gives us the ability to use it as both a dialog and a modal, although the way to do this may not be super intuitive.

Dialog element basics

A dialog element is hidden by default and accepts children to be displayed inside the dialog. It also accepts an open attribute which decides whether the dialog should be visible to the user or not. Past that, it's got all the same attributes you would expect on a generic HTML element (class, id, aria-stuff, etc).

How do I use a dialog?

Now that we've discussed what attributes a dialog element can have, we should probably talk about how to actually use the thing. I mentioned that there is an open attribute available on a dialog element. By changing this value, you can show and hide the dialog box. That's great, but how do you actually do that? First, lets create a function which toggles the dialog between open and closed:



const toggleDialog = () => {
  // Get the dialog element
  const dialog = document.getElementById("dialog");
  // Figure out what the 'open' attribute is set to
  const open = dialog.getAttribute("open");
  // Set the dialog's 'open' value accordingly
  if (open) {
    dialog.removeAttribute("open");
  } else {
    dialog.setAttribute("open", "true");
  }
};

When using HTML, the dialog will be shown if the open attribute is present, regardless of what the value is. In the function above, I am looking to see if the dialog has the open attribute set. If so, it removes the attribute but if the open attribute is missing, it adds it with a value of true.

Next, I will create the dialog itself. For now, I will just create a basic dialog element with some content inside:



<dialog id="dialog">I'm a dialog</dialog>

Finally, I want a button the user can click to control the dialog. Clicking the button once will show the dialog and clicking the button a second time will hide the dialog.



<button onclick="toggleDialog()">This button toggles a dialog</button>

Once this is built out, your result should look something like this:

How do I use a modal?

Although my HTML code will be the same for the modal (except for the dialog ID), the function being called will be different for a modal. This is because the browser provides a method which comes built-in to handle the modal's behavior. Unlike the dialog, a modal requires two separate buttons to handle opening and closing the dialog. This is because any buttons outside the dialog will be inaccessible while it is open. Because of this difference, I will create functions for each task:



const openModal = () => {
  // Get the modal element
  const modal = document.getElementById("modal");
  // Call the built-in 'showModal' method to display the modal
  modal.showModal();
};

const closeModal = () => {
  // Get the modal element
  const modal = document.getElementById("modal");
  // Call the built-in 'close' method to close the modal
  modal.close();
};

The button and dialog should look pretty much the same as the previous code except for an additional button to close the modal:



<button onclick="openModal()">This button opens a modal</button>
<!--The dialog element being used as a modal-->
<dialog id="modal">
  <p>I'm a modal</p>
  <!-- A button to be able to close the modal -->
  <button onclick="closeModal()">Close</button>
</dialog>

With this code in place, clicking the button should display something like this:

The ::backdrop pseudoselector

You may notice that a key difference between the dialog and modal is a backdrop which covers all of the content behind the modal. This is what makes a modal different because it prevents the user from accessing the page content until the modal is closed. This backdrop doesn't look very interesting though. Lucky for us, there is a pseudoselector that can be used to target and style the backdrop so it better matches your use case. You can use the ::backdrop pseudoselector like this:



dialog::backdrop {
  background: #111111;
}

It's worth noting that the backdrop only appears on modals, so the pseudoselector will not have any impact on the dialogs you're displaying.

Accessibility

I mentioned earlier that accessibility is a big benefit we get from the dialog element in HTML5, but what does that mean? There is a role="dialog" attribute which can be assigned to an element to tell a screen reader that the item is a dialog. In addition, an aria- tag should be added to tell the screen reader whether the element is visible or not.



<div role="dialog" aria-hidden="true">
  <p>This is a dialog</p>
</div>

By using the dialog element, the browser takes care of these things for us! So instead of the code above, we can simply write:



<dialog>
  <p>This is a dialog</p>
</dialog>

While the two attributes may not seem like a big deal, it may not always be something you think of when you create a dialog or modal. Using a dialog element allows us to focus on building cool things instead of getting into the nitty gritty and sometimes guessing on which aria- attributes are appropriate.

Making my dialogs cool

As previously discussed, my dialogs are pretty lame. I think it's time to add some styles. In the spirit of Max Goof, let's build a modal he might have looked at for his favorite singer, Powerline. First, I'll set some CSS variables based on some of the palettes I've seen online:



:root {
  --background: #111;
  --text: #fff;
  --yellow: #d1933f;
  --red: #9b2a4e;
  --purple: #7044a5;
}

Now that I have some colors ready to go, it's time to start styling. Here's some styles I'm using for all the things that aren't the dialogs:



html,
body {
  height: 100%;
  width: 100%;
  margin: 0;
  padding: 0;
}

body {
  font-family: sans-serif;
  color: var(--text);
  text-align: center;
  position: relative;
  display: flex;
  align-items: center;
  justify-content: center;
}
body:before {
  content: "";
  display: block;
  position: absolute;
  inset: 0;
  background-image: url("/bg.jpg");
  background-size: cover;
  background-position: top center;
  z-index: -1;
}
body:after {
  content: "";
  display: block;
  position: absolute;
  inset: 0;
  background: radial-gradient(transparent, black);
  z-index: 0;
  line-height: 1.5rem;
}

main {
  position: relative;
  z-index: 1;
}

a {
  color: var(--text);
  background: var(--red);
  padding: 0.25rem;
  text-decoration: none;
  transition: background 0.3s;
}
a:hover {
  background: linear-gradient(
    to bottom right,
    var(--yellow),
    var(--red),
    var(--purple)
  );
}

button {
  background: var(--yellow);
  font-size: 1.1rem;
  padding: 0.5rem;
  margin: 1rem;
  border: 2px solid var(--red);
  border-radius: 8px;
  cursor: pointer;
}
button:hover {
  box-shadow: 0 0 1rem var(--red);
}

.headline {
  font-size: 1.5rem;
  font-weight: bold;
  text-transform: uppercase;
  color: var(--text);
  text-shadow: 5px 5px 0 var(--red);
}

I would like to style the dialog as well as the backdrop according to the palette I've chosen so it doesn't stick out like a sore thumb. Below are the styles I'll be using for the dialog:



dialog {
  position: fixed;
  background: linear-gradient(
    to bottom right,
    var(--yellow),
    var(--red),
    var(--purple)
  );
  margin: 0 auto;
  text-align: center;
  width: 400px;
  top: 50%;
  transform: translateY(-50%);
  border-radius: 8px;
  border: 1px solid var(--purple);
}
dialog::backdrop {
  background: rgba(74, 62, 89, 0.4);
}

Now my modal looks like this:

You can see the full code for this at https://github.com/iamtimsmith/dialog-vs-modal and you can visit the finished site at https://dialog-vs-modal-nine.vercel.app

Conclusion

Dialogs and modals have become a common part of the web, but it's not always clear which one is appropriate for a given situation. Now you'll know that a dialog is used when the user should still be able to interact with the main page content, while a modal should be used when the dialog should prevent the user from accessing the rest of the page. With this in mind, you can hopefully build better and more accessible user experiences when using a popup.

Have questions? You can find me on Twitter at @iam_timsmith.

Using Variables in CSS

Tim Smith — Tue, 21 Dec 2021 14:40:32 +0000

When I was first starting to learn web development, I remember being annoyed with writing the same hex code for a color over and over then finding out the color had to change and searching through code to find every instance. It was a huge pain! At the time, this was one of the pain points that made css preprocessors like Sass and Less so appealing since they allowed you to use variables in your styles.

Fortunately, we live in a golden age of technology for web development where smart and passionate people are pushing the boundaries of what our tooling can do. As such, engineers have been hard at work making improvements to plain old css. One such improvement is the ability to use variables within your .css files! In this article, I'll teach you how to use variables in your css files and what the limitations are.

Why are CSS variables important?

If you've been writing css for a while (or haven't), I'm sure you've encountered a file with the same color value peppered in throughout the code. Even worse is when you have the same value used across several files. Simply having them there isn't such a big deal, but what if you need to change them down the road? You'll have to find every instance of that color and change it manually. It also means that if you are going to do something like a light and dark theme, you'll have to write duplicate code for each theme based on class. Consider the code below:

body.light {
    background: #fff;
    color: #ff0000;
    font-size: 16px;
}

body.light button {
    background: #ff0000;
    color: #fff;
    border: 1px solid #ff0000;
}

body.dark {
    background: #222;
    color: #c0ffee;
    font-size: 16px;
}

body.dark button {
    background: #c0ffee;
    color: #222;
    border: 1px solid #c0ffee;
}

Obviously the code above wouldn't be that big of a deal to change, but if this file continued on and on with these colors you can imagine why it would be useful to make a change in one place and have it update everywhere. The code below shows how this code can work with variables.

body {
    background: var(--primary);
    color: var(--secondary);
    font-size: 16px;
}

button {
    background: var(--secondary);
    color: var(--primary);
    border: 1px solid var(--secondary);
}

You can see how concise the code is in the example. Because the values for variables can be reassigned, the --primary variable can be changed based on the body class rather than duplicating code with different values.

How to set up variables in CSS

To create a variable in your CSS, you need to decide what the scope of the variable will be. Variable creation is the same regardless of the scope, so the code below will apply anywhere although the selector may be different.

.sample-selector {
    --color: purple;
}

The example above shows how you can create an element with the sample-selector class. You will be able to access the --color variable from any child of the .sample-selector element. You can also create global css variables by using the :root selector which targets the html element. The --color assignment using the root selector would look like this:

:root {
    --color: purple;
}

Since the variable is assigned to the root element, you can use it anywhere in the styles with no problem. Going back to the idea of using themes, you could set a different variable value based on what class is assigned to the html element. That would look like this:

:root.light {
    --primary: #fff;
    --secondary: #ff0000;
}
:root.dark {
    --primary: #222;
    --secondary: #c0ffee;
}

By using CSS variables in this way, you don't have to add styles for both light and dark themes on each element. Instead, you can use and reuse a variable with a different value based on the theme class assigned to a given element.

Are there any limitations?

Although css variables have solved a lot of problems for front-end developers, it is not without flaws. If you've spent time writing SCSS or something similar, you may have used variables and mixins to handle media queries. This cannot be done with CSS variables which is a bit of a bummer. In addition, CSS variables can't store a url. This would be useful if you had to reuse an image in different places, but it doesn't work.

Conclusion

Overall, CSS variables are a very cool innovation within your styles. They make it very easy to not only write reusable styles, but update them or expand on them further down the road. I highly recommend checking them out in your next project and seeing what you think about them.

Have questions? You can find me on Twitter at @iam_timsmith.

How to use React Context

Tim Smith — Mon, 13 Dec 2021 14:47:26 +0000

Have you ever had to pass a piece of state three or four levels deep along with a method to update the state? If so, you have likely either suffered in silence or looked into libraries such as Redux. The team behind React heard these complaints from the community and decided it was high time they created an out-of-the-box solution for this. Their solution is a part of the React library and is called "Context". In this post, you'll learn how to set up and use Context in your project.

Life before context

Before getting into Context, I'd like to explain the problem that context solves for anyone who is newer to React. Back in "Ye Olden Times" before global state management, you had two options for state that was used in different places: keep state in the top-most component and pass it down or manage state in each component that needed it by writing the same code in each component.

The latter solution is bad because it means writing duplicate code all over. This is a pain (and can be dangerous) because if you have to update that logic down the road, you may miss a spot where the code is duplicated and then there's a divergence in your logic. We want to avoid this.

The first option presented doesn't sound too bad until you have a complex application with several children and grandchildren. Then if a great grandchild needs the state (or the ability to change the state) in the topmost component, it has to be passed down through each level even if it's not being used by the other levels. To illustrate, I'll give an example below:

const React, { useState } from 'react';

const IncreaseButton = ({count, setCount}) => {
    return (
        <button
            onClick={() => setCount(count + 1)}
        >
            Increase value to {count + 1}
        </button>
    )
}

const DecreaseButton = ({count, setCount}) => {
    return (
        <button
            onClick={() => setCount(count - 1)}
        >
            Decrease value to {count - 1}
        </button>
    )
}

const Clicker = ({count, setCount}) => {
    return (
        <div>
            <IncreaseButton count={count} setCount={setCount}/>
            <DecreaseButton count={count} setCount={setCount}/>
        </div>
    )
}

const App = () => {
    const [count, setCount] = useState(0);

    return (
        <div>
            <p>{count}</p>
            <Clicker count={count} setCount={setCount} />
        </div>
    );
}

In the ~~completely impractical~~ example above, you can see that I have a state which is being passed into a button container called Clicker which renders two buttons with their own logic which uses the count and setCount variables. You can also see that Clicker isn't doing anything with the count and setCount data, but it still has to be passed through to reach the components that need it.

While this isn't a particularly realistic example, these sorts of things became a very common practice prior to global state management tools. Because of this, tools like Redux became very popular even though in most cases it was probably overkill. As a result, the engineers at Facebook came up with an elegant solution to solve the global state problem with as little complexity as possible and called it Context.

How to create a context

Creating a context is pretty simple. All you need to do is import the method and assign it to a variable. Just like that, you're done!

import {createContext} from 'react';

const MyContext = createContext();

If you're using TypeScript, you will also need to set types for your Context, so React knows what to expect.

import {createContext} from 'react';

interface IMyContext {
    ...
}

const MyContext = createContext<IMyContext>();

Congratulations! You have created your first context!

What's a Context Provider?

Good question! A context provider provides the context.

Okay, okay. That was a pretty corny joke. For real though, they couldn't have chosen a better name for this piece. The context provider is a component which wraps anything you'll need context in to "provide" the context to those components.

One of my favorite ways to do this is to include it as a component in the same file as the context itself, which makes it easy to know where to find it.

// MyContext.jsx
import React, {createContext, useState} from 'react';

export const MyContext = createContext({
    count: 0,
    setCount: () => {},
});

export const MyContextProvider = ({children}) => {
    const [count, setCount] = useState(0);

    return (
        <MyContext.Provider value={{count, setCount}}>
            {children}
        </MyContext.Provider>
    )
}

Although this is how I do it, you could just as easily put a provider wherever you'd like. The only required prop for the provider is value which could be any type of data if you're only using 1 piece of data in your context. For more than one item in your context, you need to pass it as an object which should match the stuff in your context. For instance, in the example above, the MyContext object is expecting a count and a setCount key. The value in the provider has an object with the same count and setCount keys being set.

Using the Context Provider

The next step when using Context in your project is to wrap any components (and their children) in the provider. In the example below, I will assume that every component should have access to my context so I will put it in the App.jsx (topmost) file.

import React from 'react';
import { MyContextProvider } from './MyContext';

const App = ({ children }) => {
    return (
        <MyContextProvider>
            {children}
        </MyContextProvider>
    );
}

Now that the provider is wrapped around everything else in your app, all of the things in your app know about the context. You're ready to start using your context!

How do I use context?

So you have your context created and your components inside the provider...now what? Now you can get the data from context and use it wherever you need it. There are a few different ways to do this, so I'll show you both.

Using a consumer

The first way to do this is to use something called a consumer. This is created using the context and should wrap the comoponent you'd like to use the context in, which will give you access to the context variables. Only this method will work inside of class components. The code below shows how this will work with the context I set up in previous examples.

import React from 'react';
import { MyContext } from './MyContext';

const MyComponentWithContext = () => {
    return (
        <MyContext.Consumer>
            {(context) => (
                <p>The current count is {context.count}</p>
            )}
        </MyContext.Consumer>
    );
}

If you'd prefer, you can also use destructuring inside the consumer to only get the stuff you actually want to use. The highlighted code below shows the code that would be different by doing this.

import React from 'react';
import { MyContext } from './MyContext';

const MyComponentWithContext = () => {
    return (
        <MyContext.Consumer>
            {({count}) => ( <p>The current count is {count}</p> )} </MyContext.Consumer>
    );
}

The useContext hook

In my last post, I talked about many of the different hooks that are available in React. They have become the more common way to do things because they allow you to write ~~everything~~ most things as functional components.

When using the useContext hook, you still need to make sure you're inside the provider, but you don't have to mess around with consumers anymore. Like the consumer, you can use destructuring with the useContext hook to only get the variables you need. If I refactor the component from above to use the useContext hook, it looks like this:

import React, { useContext } from 'react';
import { MyContext } from './MyContext';

const MyComponentWithContext = () => {
    const {count} = useContext(MyContext);

    return (
        <p>The current count is {context.count}</p>
    );
}

To use this hook, you import it from React, import the specific context you're getting data from, and tell it what data you want from the context. To me, this solution looks much cleaner and has better readability but it's totally personal preference when using functional components.

What if I have multiple contexts?

If you need more than one context, that's not a problem. You can have as many as you'd like. You will just need to wrap the providers around the components that need the data. This may look like the example below if you have more than one context:

import React from 'react';
import { MyFirstContextProvider } from './MyFirstContext';
import { MySecondContextProvider } from './MySecondContext';
import { MyThirdContextProvider } from './MyThirdContext';

const App = ({ children }) => {
    return (
        <MyFirstContextProvider>
            <MySecondContextProvider>
                <MyThirdContextProvider>
                    {children}
                </MyThirdContextProvider>
            </MySecondContextProvider>
        </MyFirstContextProvider>
    );
}

Assuming that you've wrapped your whole app in the providers, you can now use the context from any of these providers in any component. The only other thing to watch out for is which context you're importing when using the consumer or hook. If you need to get data from MySecondContext, then you need to be sure and use that specific context when creating the consumer or calling the useContext hook.

Conclusion

React Context is a game-changer if you need to reuse the same data all over the application. It adds a ton of flexibility without adding additional libraries or lots of complexity. Try it out in your next project and let me know what you think!

You can find me on Twitter at @iam_timsmith.

React 101: The Basics

Tim Smith — Tue, 30 Nov 2021 15:54:12 +0000

React is one of the most in demand tools in the job market these days, but if you don't know it should you just skip it? You could, but I still think it's worth learning. I'm going to teach you some basics about react to get you started. This should be enough information to give you an understanding of what React is and how to set it up.

What is React?

React is a JavaScript library built by Facebook which creates a virtual DOM and allows a website or web application to update (or react) based on changes in data. It has been growing in popularity since it's release in 2016, even overthrowing jQuery as the most in-demand JavaScript skill, a title which jQuery had held for about a decade.

Why is React useful?

Part of the reason for the popularity has to do with the direction of data flow in a React application. In the past, a webpage would load the static HTML, then load the JavaScript to make changes to the page as needed. If that involved updating any data on the page, there would be a "flicker" where you'd see the original content before it was updated via JavaScript.

React was a gamechanger because it modified the paradigm to be data-driven. In a React application, the state (data) is passed into the view (HTML). When the view is changed or interacted with, an action is called which updates the state and re-renders the view with the new data. This is called unidirectional flow and can be very helpful.

How to set up a React project

When React first came out, setting up a project was a headache. There weren't any tools or starter projects out there to get things up-and-running very quickly so things like Webpack had to be configured manually each time. Since then, several projects have come out which make setting up a React project a piece of cake. The items I discuss below are not an exhaustive list by any means, but they are some of the more popular options. Before we get into tooling, lets go over some basics so you understand how the application interacts with the HTML on the page.

Creating an instance of React

I have written a post about setting up a React project using Parcel as a bundler which can give a more detailed walkthrough about getting a React application up and running from scratch. There are multiple ways to do this but some of the more common build tools include Webpack, Parcel, and Snowpack.

Create-React-App

Back when I first started learning React, there was a lot of talk about the difficulty in figuring out how to configure webpack. This was not only complicated but time consuming each time a new project started. The community felt this pain and decided to do something about it. The result is create-react-app (or CRA), a starter which bootstraps a project with a minimal structure.

Creating a new project with this library is as easy as running the command npx create-react-app new-app. Just like that, it will create a new directory called new-app (or whatever value you pass in) with a rudimentary structure as well as a configuration built to work on a React project without any assumptions about which tools will be used.

Using Next.js for a project

An alternative to Create React App is Next (or Next.js). Unlike CRA, Next is an opinionated framework which offers build tools, routing, server-side rendering, and static site generation out-of-the-box. This is a popular option which is used by companies like Nike, TikTok, Netflix Jobs, Twitch.

Originally, Next was created for server-side rendering which means that all of the code is built on the backend and sent to the client which then renders it. Create React App doesn't offer this ability which may or may not be a big deal for your project. The primary benefit to server-side rendering, or SSR, is that it's really easy for SEO crawlers to get the content on your site since it's all being sent from the server instead of being built in the browser after the user visits the url. If you're building a web app where SEO isn't a concern, then you likely won't have to worry about SSR.

Using Gatsby for a project

Another popular solution (and the one I've used for 4 years at the time of this post) is Gatsby. I've written several posts about Gatsby as well as how to improve the default SEO component which comes with a default Gatsby project. Needless to say, I'm a big fan.

So, what is Gatsby? I'm glad you asked. Gatsby is a Static Site Generator, or SSG, which means that you can create a site using React components and then build the site which creates static HTML pages from your React components. This means that sites are blazing fast when the browser renders a page because it doesn't have the extra bloat that comes along with tons of libraries which block rendering or slow down performance.

In addition to being crazy fast, Gatsby offers routing, graphql, and optimized images without any customization. Plus, if you do need something special added on like a CMS or other tool, Gatsby offers tons of plugins to assist with this. SSG also adds SEO benefits since the code is being compiled into HTML, so there's not much difference between Next and Gatsby in that regard.

Which should I choose?

As I mentioned before, you should use Create React App when SSR and SEO are not a concern (webapps, admin panels, cms, etc). Choosing between Next and Gatsby is a bit more complex since both offer SSR and SSG nowadays. Choosing which is right for your project really depends on whether you're looking for server-side rendering or static site generation and which one you prefer. Performance differences are neglegible and both support TypeScript, testing, other features.

The big difference between server-side rendering and static site generation is that SSR collects data each time the page is fetched and renders whatever is collected while SSG collects data at build time and builds static files from that data. For example, if you were using a CMS for content management and SSR on the frontend, you could simply refresh the page after updating a blog post and see the updates. If you were using a CMS and updated the same blog post, you wouldn't see updates in a statically generated site until ran another build so it could pull in the updated data.

What are some features of React?

React has become one of (if not THE) most in demand front end library for good reason. It offers features which make front ends data-driven and reactive. I will cover some of these benefits below so you can decide if React is the right tool for the project you're looking to build.

Unidirectional data flow

A unidirectional data flow means that data only flows one way. This is important because other frameworks and libraries allow data to be cchanged from both the front and back ends which can get hairy to troubleshoot. So how does unidirectional data flow work? First, the state, or data, is passed to the view and it's children. The view can then call actions if data needs to be updated. Once the action is called, it updates the state which then causes the view to re-render. This may sound confusing, but I have placed a diagram below to help illustrate how this is unidirectional.

Unidirectional flow chart

State management

Because of the unidirectional flow, React provides a state management system. This is a way for your application to track the data being used and re-render your components when that data is updated. I have written a blog post about state management in class components and also about building a search bar using state with the new hooks system.

The state can be managed within an individual component or passed around wherever it's needed, making the site really reactive to data changes. There are also tools which make it easy to share state all around the app without having to pass it from component to component to component, but we'll go over those more later.

Component structure

Another feature of React is the ability to build reusable components for your project. This is a really cool feature because you can write a chunk of code and drop it in wherever you want it (even with unique data each time!) without having to rewrite the same code in each spot.

Each component can also accept props, or variable data which can then be used to render data in the component. By using props, you can build out the basic structure of a component without any actual hard-coded text or images and pass props in to make those things dynamic each time you use the component.

I have written a blog post about creating components using the class component structure and will soon write one about writing functional components using hooks for state and lifecycle methods.

The React ecosystem

One of the more complicated things to learn is the ecosystem around React. Since it is such a popular tool, there are LOTS of different libraries which can be used to do a variety of things. Below I will talk about some of the libraries used for common challenges when building a React application.

Required libraries

When using React for a project, there are two libraries that are required to make it work: react and react-dom. You can install both in your application by running the command:

npm i react react-dom

React is a library which contains the code needed for state management and component creation. React DOM is the library specific to web development which allows the use of DOM elements (such as div, h1, or p) in your components. With these two libraries, you can start building out a React project.

Of the solutions I mentioned earlier, Gatsby and Create React App both come with these already installed. When setting up a Next application, these libraries need to be installed alongside the Next library.

Other popular libraries

Aside from the required libraries, there are a lot of libraries to choose from. These are all optional, so it's worth looking into each one for your needs and seeing which one works best for your project and preferences.

State Management

React contains a state management system called Context which allows state to be managed on a global scale and used where it's needed. This comes built in and doesn't require any other libraries to be installed, but I thought it was worth mentioning here because it's a viable solution out-of-the-box.

Another really popular library for global state management is called Redux. This is a very widely used library and uses actions, reducers, and stores to handle state. In short, a component calls an action which is then analyzed by the reducer to decide how to update state. There can be more to this method such as sagas and thunks but in it's most basic form, this is an overview of how it works.

Routing

While libraries like Next and Gatsby have routing built-in, Create React App does not so you may need to set it up yourself. The most popular library for this is React Router. Another popular option in the past was called Reach Router, but the two have become merged as of version 6.

These libraries allow you to establish a path to use in the url and a component to render when that path is visited. For what it's worth, under the hood Gatsby uses Reach Router while Next uses it's own file-system based router.

Testing

Along with React, Facebook developed a tool for testing JavaScript called Jest. When used by itself, Jest is primary good for testing logic. It doesn't handle any sort of DOM rendering or snapshot testing, so another library is needed for that. The two most commonly used tools for DOM testing are Enzyme and React Testing Library. They both do pretty much the same thing, so it's really just a matter of preference. For end-to-end testing, the most commonly used library is Cypress.

Styles

In addition to normal css, there are different tools which can be used for styling in your React applications. Styled Components is a popular option and allows you to write your styles directly in your JavaScript code. Sass is another commonly used option which has many benefits of css with some "special sauce" on top. Of course, you can also use tools such as Bootstrap, Material UI, etc.

Conclusion

As you can see, React has a lot to offer when building front-end applications. It is one of the most in-demand skills for a developer seeking a job. There is a huge community and as a result tons of options when building out a project.

Getting started with React Hooks

Tim Smith — Sat, 12 Jun 2021 00:00:00 +0000

A few years ago I wrote a post about class components vs stateless functional components and why you should use each one. At the time of writing, those were the two types of components and many developers yearned for a way to use functional components with state and lifecycle methods.

Back in "the old days", you'd have to use a class component if you wanted access to state or lifecycle methods. This led to either a lot of unnecessary class components just in case they ever needed state or a lot of time converting stateless functional components over to class components because the requirements for the functional component changed and required something only a class component could offer.

Fortunately, the team behind React heard these complains and took action. With the release of React 16 came something called "hooks". These hooks allow you to use state, a lifecycle method, and much more from a functional component! Today I'll be showing you how to use some of the more common hooks as well as how to create your own custom hook.

The useState hook

Perhaps the most commonly used hook is the useState hook which is used to create a state item. From the hook, you get the data itself from state as well as a method to update the state. Below is an example of how to use the useState hook in a component:

import React, { useState } from 'react';

const MyComponent = () => {
    const [count, setCount] = useState(0);

    return (
        <div>
            <p>Number of Clicks: {count}</p>
            <button onClick={() => setCount(count + 1)}>
                Click Me!
            </button>
        </div>
    );
}

The code above is a simple example to show how this hook works. First, import the useState named variable from the React library (or you can just use React.useState if you prefer). Next, you're going to create a const which receives an array of variables: the first is the data itself from the state and the second is the method to update the data within this state item. The names are arbitrary and should be representative of whatever data you're storing. The standard convention for the method name is to begin with set followed by the camel-case name of your data variable.

Once you have the state created, you can use the data variable (in our example it is count) to output the data and the update method (setCount in the example) to change state. The argument passed into the update method is the value to which the state should be set.

Congratulations! You just used your first hook!

Using TypeScript with useState

When using TypeScript in your project with strict set to true in your tsconfig.json file, you will likely get an error about not being able to use a variable with a possible undefined value. The solution to this is to set the expected type when calling the useState hook. The code below shows how to do this on the highlighted line.

import React, { useState } from 'react';

const MyComponent = () => {
    const [count, setCount] = useState<number>(0);
    return (
        <div>
            <p>Number of Clicks: {count}</p>
            <button onClick={() => setCount(count + 1)}>
                Click Me!
            </button>
        </div>
    );
}

The useEffect hook

The second most used hook is likely the useEffect hook which gives us access to a lifecycle method. In a class component, there are a handful of lifecycle methods you can use to make things happen at various points during the component's "lifecycle". Among the most commonly used were componentDidMount and componentDidUpdate which would allow you to do something after the component had loaded and rendered.

The useEffect hook replaces these two lifecycle methods and allows you to do things after the component has rendered. It also allows us to pass in dependencies which determines when the hook will run which will help with performance. It's also worth mentioning that there can be more than one useEffect hook in a component to accomodate changes for different dependencies. The code below illustrates how to use the useEffect hook in a functional component:

import React, { useState, useEffect } from 'react';

const MyComponent = () => {
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        setLoading(false);
    }, []);

    return (
        <div>
            <p>Is page loading? {loading.toString()}</p>
        </div>
    );
}

In the code above, you can see the syntax to use for a useEffect hook. It is a function which accepts two arguments: another function with the logic you want to run and an array of dependencies. The hook will have access to any variables within the component, so scoping isn't a problem. Looking at the example, I have set a piece of state, loading to true. Once the page is finished rendering, the useEffect hook will be called where setLoading is called and changes the state to false. This is useful for showing loading spinners.

Depedencies in the useEffect hook

You may also notice I have passed an empty array as the second argument. By doing this, you can tell the useEffect hook you want it to run after the component is rendered but don't run again. If you wanted to make the hook listen for changes to re-run if necessary, you would just add the variable to watch in the array. I have updated the example below to contain a button which sets the loading state to true along with a dependency to watch so it runs each time the loading state is changed:

import React, { useState, useEffect } from 'react';

const MyComponent = () => {
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        setLoading(false);
    }, [loading]);

    return (
        <div>
            <p>Is page loading? {loading.toString()}</p>
            <button onClick={() => setLoading(true)}>Reload Me!</button>
        </div>
    );
}

Creating event listeners in your component

In some cases, you may need to create an event listener in your component. I have used this to create keypress events and right click events. If you need to do this in your component, it should be done in the useEffect hook because you must wait for the component to be rendered to access the browser variables such as document or window. Below is an example to show how you can add an event to your component.

import React, { useEffect } from 'react';

const MyComponent = () => {
    const onKeyPress = (e) => {
        alert(`You pressed the ${e.key} key!`);
    }

    useEffect(() => {
        document.addEventListener('keydown', onKeyPress);
    }, []);

    return (
        <div>
            <p>My Component</p>
        </div>
    );
}

If you're doing anything with keypresses, I've found https://keycode.info to be hugely helpful.

When the component unmounts, you'll see an ugly error in the console which tells you that you can't called on an unmounted component. To fix this, you can add a return function to the useEffect hook which will run when the component is unmounted. Added to the example above, this would look something like the highlighted lines:

import React, { useEffect } from 'react';

const MyComponent = () => {
    const onKeyPress = (e) => {
        alert(`You pressed the ${e.key} key!`);
    }

    useEffect(() => {
        document.addEventListener('keydown', onKeyPress);
        return () => { document.removeEventListener('keydown', onKeyPress); }   }, []);

    return (
        <div>
            <p>My Component</p>
        </div>
    );
}

The useContext hook

I will mention another hook called useContext, but this will not be a comprehensive post on React context. I will simply show you how to use the hook in the event that you need to. First, what is Context? Along with hooks, the team behind React added a feature which allowed for global state management and called it Context. By using this tool, you can keep items in state outside of a specific component and use it where needed.

The example below assumes you have already created a context with an item called food in another file and already wrapped the app in the Context Provider. To use the useContext provider, you need the context itself. Once you've called the hook, you can use destructuring to get specific items within the context.

import React, { useContext } from 'react';
import MyContext from './MyContext';

const MyComponent = () => {
    const { food } = useContext(MyContext);

    return (
        <div>
            <p>My favorite food is {food}!</p>
        </div>
    );
}

Using this hook, you can get any piece of state contained in the context and passed into the provider. This makes it really easy to have a "single source of truth" in your project without any extra libraries and without a ton of unnecessary code.

The useReducer hook

What if you come from a Redux background or have a more complex application which requires you to track all of your state changes? For that, React provides a useReducer hook where you can use (you guessed it!) a reducer for your state.

The useReducer hook accepts two arguments: the reducer and an initial state. From the hook, you can get an array which contains the current state for the reducer as well as a dispatch function which allows you to update the state. Because the dispatch function is always available, you don't have to use a useEffect hook to call it like you do with useState.

import React, { useReducer } from 'react';

const initState = {
    slices: 8,
}

const reducer = (state, action) => {
  switch (action.type) {
    case 'TAKE_SLICE':
      if (state.slices === 0) return { slices: 0 };
      return { slices: state.slices - 1 };
    case 'PUT_BACK':
      if (state.slices === 8) return { slices: 8 };
      return { slices: state.slices + 1 };
    default:
      return;
  }
};

const MyComponent = () => {
    const [state, dispatch] = useReducer(reducer, initState);

    return (
        <div>
            <p>There are currently {state.slices} slices of pizza left.</p>
            <button onClick={() => dispatch({type: 'TAKE_SLICE'})}>Take a slice!</button>
            <button onClick={() => dispatch({type: 'PUT_BACK'})}>Put the slice back!</button>
        </div>
    );
}

This is not so different from a simple Redux store with a reducer, so it should feel pretty familiar if you've used that library before. If you haven't used Redux, it allows you to pass an action type into dispatch which then calls the reducer. Inside the reducer, you would typically create a switch statement which listens for specific action types and updates state based on the action type it's listening for.

In the example above, it is listening for the TAKE_SLICE action type to reduce the slices variable by one (to a minimum of 0) and the PUT_BACK action type to increase the slices variable by one (to a maximum of 8).

Are there more hooks?

There are still more hooks which can be used for various purposes such as useMemo, useRef, useCallback, and others. If you're interested in reading more about those or you have a use case that doesn't fit with the hooks I have talked about, you can check the React documentation for additional hooks. It talks about several additional hooks and provides examples and syntax for each one.

Creating a custom hook

You can also create custom hooks if none of the available hooks suit your needs. To do this, you can create a function (typically started with use) which handles any sort of logic needed for the hook to work. Below is an example of how you can do this:

import { useEffect, useState } from 'react';

export const useFetch = (url) => {
    const [data, setData] = useState(null);

    const handleFetch = async (url) => {
        const res = await fetch(url);
        const json = await res.json();
        return json;
    }

    useEffect(() => {
        setData(handleFetch(url));
    }, []);

    return data;
}

The code above is a pretty basic (and not ideal) hook for fetching data to illustrate how this can be done. It takes a url, fetches data when useEffect runs, then returns that data. In a component, calling this hook may look something like this:

import React from 'react';
import { useFetch } from './useFetch';

const MyComponent = () => {
    const post = useFetch('https://some-fake-site.com');

    return (
        <div>
            <h1>{post.title}</h1>
            <div dangerouslySetInnerHTML={{__html: post.content}} />
        </div>
    )
}

By creating a custom hook, you can extract logic from a plugin and turn it into a piece of reusable code so your components don't become a mile long and really repetitive. This certainly isn't something that needs to be used, but it is possible if it suits your use-case.

Conclusion

In this post, I've covered many of the popular hooks in React as well as how to create your own custom hooks. Hopefully you are able to see the benefit in using these hooks and you can add them to your development tool kit. As always, if you have any questions or comments, feel free to reach out to me on Twitter at @iam_timsmith!

Creating a better SEO component for Gatsby sites

Tim Smith — Mon, 01 Mar 2021 15:08:02 +0000

When you create a new project using the default starter for Gatsby, it gives you an SEO component with some basic contents. This is good for simple things such as a favicon, page title, and description. It leaves out other important pieces that can make a site even more optimized for both search engines and social sharing. In this post, I'll show you how to build a better SEO component which can help in marketing your Gatsby site. Even if you're not using Gatsby, the things discussed in this article will provide a framework for a solid SEO component. Let's get started!

Importing the packages we need

When creating the file for the SEO component, you should think about what you'll need the component to do. In this case, you will need the ability to create a react component, write jsx, insert information into the head of your page, and use graphql to get some data for default values. I will also be using the prop-types package to check for types on the incoming props.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby';

The packages above will accomplish all of the tasks I listed with flying colors. To handle the graphql query, I opted for the useStaticQuery hook rather than the StaticQuery component. That's just personal preference though, either will work just fine. Next you will create a basic component with some hard-coded data to make sure the component is working.

Creating a hard-coded component

In the basic version of the component, you will just be setting up the helmet element with a title and description. Then you can import it into a page and make sure you're seeing the hard-coded data in your page. Below is the code for the hard-coded component.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby';

const SEO = () => {
    return (
        <Helmet>
            <title>This is a title</title>
            <meta name='description' content='This is some content' />
        </Helmet>
    );
}

export default SEO;

Once the code in the SEO component is updated, you can import it into a file to make sure the title and description are changing for the page. There aren't any props to pass in yet, so it will just look like this:

// pages/index.js
import React from 'react';
import Layout from '../components/layout';
import SEO from '../components/seo';

const IndexPage = () => {
    return (
        <Layout>
            <SEO />
            <h1>This is the index page</h1>
        </Layout>
    );
}

export default IndexPage;

Making the title and description dynamic

Once the SEO component is imported and rendered, you should see that the title and description for the index page says "This is a title" and "This is some content", respectively. That's pretty good, but it's not very dynamic. To fix that, you will add props for a title and description and use that to fill out the SEO component.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby'

const SEO = ({title, description}) => {
    return (
        <Helmet>
            <title>{title}</title>
            <meta name='description' content={description} />
        </Helmet>
    );
}

SEO.propTypes = {
    title: PropTypes.string,
    description: PropTypes.string,
}

export default SEO;

Now that you have props for title and description, you can pass those in from the index page. Update the code for the index page with the following code:

// pages/index.js
import React from 'react';
import Layout from '../components/layout';
import SEO from '../components/seo';

const IndexPage = () => {
    return (
        <Layout>
            <SEO
                title='Home'
                description='This is the homepage for a gatsby website'
            />
            <h1>This is the index page</h1>
        </Layout>
    );
}

export default IndexPage;

Adding attributes to HTML element

You may want to add some elements to the html element for SEO purposes. This can be done using the Helmet component by adding an object with the desired attributes in the htmlAttributes prop. It is always a good idea to add a lang attribute to indicate the language in which the site is written. The modified code below shows how you can add attributes to the html element in the DOM.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby'

const SEO = ({title, description}) => {
    return (
        <Helmet htmlAttributes={{lang: `en`}}>
            <title>{title}</title>
            <meta name='description' content={description} />
        </Helmet>
    );
}

SEO.propTypes = {
    title: PropTypes.string,
    description: PropTypes.string,
}

export default SEO;

There are a number of attributes you can add to the html element, all of which can be added this way. Once you have all the html attributes added that you want, it's time to customize the title a little bit more.

Adding your first query to improve the page title

If you look at the title for your index page, it just says "Home". This is adequate, though you may want to put the site title in there so visitors know what site they're on. Here's where you need to start using queries to get data. Below, you can see the first query to get the site title and description from the gatsby-config.js file. This is where I will be pulling data from, though you could query WordPress data, Ghost data, or any other source. Below is the component with the query being performed through a hook. The documentation will also show how to use the StaticQuery component to achieve the same result.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby'

const SEO = ({title, description}) => {
    const data = useStaticQuery(graphql`
        query {
            site {
                siteMetadata {
                    title
                    description
                }
            }
        }
    `);

    return (
        <Helmet htmlAttributes={{lang: `en`}} titleTemplate={`%s | ${data.site.siteMetadata.title}`}>
            <title>{title}</title>
            <meta name='description' content={description || data.site.siteMetadata.description} />
        </Helmet>
    );
}

SEO.propTypes = {
    title: PropTypes.string,
    description: PropTypes.string,
}

export default SEO;

Using the code above, you have a title that displays in a format like "Page Title | Site Name" and provides a fallback description in the event that none is provided by the page. Now that you have the title and description taken care of, it's time to focus on social media sharing.

Providing a canonical URL and favicon

Providing a canonical url and a favicon in your SEO strategy can also help to build your online profile. Setting these up can be done by adding a query for the favicon and providing the slug for the current page. In addition, I will include a base url from the gatsby-config.js file and add a prop to pass in a slug for the current page.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby'

const SEO = ({title, description, slug}) => {
    const data = useStaticQuery(graphql`
        query {
            site {
                siteMetadata {
                    title
                    description
                    siteUrl
                }
            }
            favicon: file(name: {eq: "favicon"}) {
                publicURL
            }
        }
    `);

    return (
        <Helmet htmlAttributes={{lang: `en`}} titleTemplate={`%s | ${data.site.siteMetadata.title}`}>
            <title>{title}</title>
            <meta name='description' content={description || data.site.siteMetadata.description} />
            <link rel='canonical' href={`${data.site.siteMetadata.siteUrl}${slug}`} />
            <link rel='shortcut icon' href={data.favicon.publicURL} />
        </Helmet>
    );
}

SEO.propTypes = {
    title: PropTypes.string,
    description: PropTypes.string,
    slug: PropTypes.string,
}

export default SEO;

Now when you refresh your page, you should see the favicon you selected in the browser tab you're using. If you open up the html on your site, you should also see the canonical url in the head section.

Adding social sharing cards

Have you ever shared a link on social media and felt disappointed when it didn't pop up with a photo, title, and excerpt? I know I have, so I want to make sure that doesn't happen when someone shares a page of mine. To do this, you need to add both twitter tags and OG tags.

Adding Twitter cards

When setting up up your webpage to be shared on social media sites, there are a few different "categories" of meta tags you need to know about. The first is "twitter". According to the Twitter docs, it will look for twitter tags first and fall back to OG tags if none are found so we will set those up first.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby'

const SEO = ({title, description, slug}) => {
    const data = useStaticQuery(graphql`
        query {
            site {
                siteMetadata {
                    title
                    description
                    siteUrl
                }
            }
            favicon: file(name: {eq: "favicon"}) {
                publicURL
            }
        }
    `);

    return (
        <Helmet htmlAttributes={{lang: `en`}} titleTemplate={`%s | ${data.site.siteMetadata.title}`}>
            <title>{title}</title>
            <meta name='description' content={description || data.site.siteMetadata.description} />
            <link rel='canonical' href={`${data.site.siteMetadata.siteUrl}${slug}`} />
            <link rel='shortcut icon' href={data.favicon.publicURL} />
            <meta name='twitter:card' content='summary_large_image' />
            <meta name='twitter:site' content='@iam_timsmith' />
        </Helmet>
    );
}

SEO.propTypes = {
    title: PropTypes.string,
    description: PropTypes.string,
    slug: PropTypes.string,
}

export default SEO;

The 2 additional lines of code above establish what type of card you want to display when the page is shared as well as what the twitter site is for the website creator.

Adding OpenGraph tags

The next meta tags to add are called OpenGraph, or OG, tags which will provide the data for social media sites to generate the cards when your content is shared. To do this, you need to add another prop for an image and, like the title and description, add a query to get a fallback image for use if none is provided.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby'

const SEO = ({title, description, image, slug}) => {
    const data = useStaticQuery(graphql`
        query {
            site {
                siteMetadata {
                    title
                    description
                    siteUrl
                }
            }
            favicon: file(name: {eq: "favicon"}) {
                publicURL
            }
            social: file(name: {eq: "timsmith-social"}) {
                publicURL
            }
        }
    `);

    return (
        <Helmet htmlAttributes={{lang: `en`}} titleTemplate={`%s | ${data.site.siteMetadata.title}`}>
            <title>{title}</title>
            <meta name='description' content={description || data.site.siteMetadata.description} />
            <link rel='canonical' href={`${data.site.siteMetadata.siteUrl}${slug}`} />
            <link rel='shortcut icon' href={data.favicon.publicURL} />
            <meta name='twitter:card' content='summary_large_image' />
            <meta name='twitter:site' content='@iam_timsmith' />
            <meta name='og:title' content={title} />
            <meta name='og:description' content={description || data.site.siteMetadata.description} />
            <meta name='og:image' content={`${data.site.siteMetadata.siteUrl}${image || data.social.publicURL}`} />
            <meta name='og:type' content='website' />
            <meta name='og:url' content={`${data.site.siteMetadata.siteUrl}/${slug}`} />
            <meta name='og:site_name' content={data.site.siteMetadata.title} />
        </Helmet>
    );
}

SEO.propTypes = {
    title: PropTypes.string,
    description: PropTypes.string,
    image: PropTypes.string,
    slug: PropTypes.string,
}

export default SEO;

Now when a user shares your page on any social media site that supports OpenGraph protocols, it will generate a card with an image, title, description, and URL. Hopefully this will help to drive engagement with the link since it provides so much information before even being clicked. Because of the fall backs, if no description is provided it gives the default site description; if no image is provided, it gives the default site image. Having these fallbacks means that even if you forget to include those things, the end-user on a social media site will still get an appealing card with which to engage.

Adding the new props to the existing index page would look like this:

// pages/index.js
import React from 'react';
import Layout from '../components/layout';
import SEO from '../components/seo';

const IndexPage = () => {
    return (
        <Layout>
            <SEO
                title='Home'
                description='This is the homepage for a gatsby website'
                image='https://placeimg.com/300/300'
                slug='/'
            />
            <h1>This is the index page</h1>
        </Layout>
    );
}

export default IndexPage;

Using Schema.org data in SEO component

Getting into Schema.org markup is outside the scope of this article, but I will talk about how you could implement it into a Gatsby SEO component if you wanted to. This is completely optional, so if you don't need to add this, you can skip ahead.

What is Schema.org markup?

In a nutshell, Schema.org markup is just a way to provide more information about the data on a webpage to search engines so they can index your site in a more efficient way. It also allows the search engine to serve your page to more relevant queries, making you visible to more of the people searching for your site.

Adding it to the SEO component

My solution to add Schema information to the SEO component is not a complex one, though it gets the job done. It is simply to add it as children of the component. The reason for this has to do with how many options are available for schemas and what the contents of those schemas look like. It would be A LOT of work to build out a component that could handle all of the possibilities for that. To make my life a little easier, I just made it possible to add whatever children the particular piece of content called for. This would make it possible to any schema desired without having to try and plan for every option or constantly add onto the SEO component whenever a schema changed or got added. The code to do this can be found below.

// components/seo.js
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import {useStaticQuery, graphql} from 'gatsby'

const SEO = ({title, description, image, slug, children}) => {
    const data = useStaticQuery(graphql`
        query {
            site {
                siteMetadata {
                    title
                    description
                    siteUrl
                }
            }
            favicon: file(name: {eq: "favicon"}) {
                publicURL
            }
            social: file(name: {eq: "timsmith-social"}) {
                publicURL
            }
        }
    `);

    return (
        <Helmet htmlAttributes={{lang: `en`}} titleTemplate={`%s | ${data.site.siteMetadata.title}`}>
            <title>{title}</title>
            <meta name='description' content={description || data.site.siteMetadata.description} />
            <link rel='canonical' href={`${data.site.siteMetadata.siteUrl}${slug}`} />
            <link rel='shortcut icon' href={data.favicon.publicURL} />
            <meta name='twitter:card' content='summary_large_image' />
            <meta name='twitter:site' content='@iam_timsmith' />
            <meta name='og:title' content={title} />
            <meta name='og:description' content={description || data.site.siteMetadata.description} />
            <meta name='og:image' content={`${data.site.siteMetadata.siteUrl}${image || data.social.publicURL}`} />
            <meta name='og:type' content='website' />
            <meta name='og:url' content={`${data.site.siteMetadata.siteUrl}/${slug}`} />
            <meta name='og:site_name' content={data.site.siteMetadata.title} />
            {children}
        </Helmet>
    );
}

SEO.propTypes = {
    title: PropTypes.string,
    description: PropTypes.string,
    image: PropTypes.string,
    slug: PropTypes.string,
    children: PropTypes.node,
}

export default SEO;

To help show the context in which this will be used, I will use a fake blog post as an example. Below is a component with a hard-coded title, description, image, and slug to keep things simple. These would likely come from a graphql query in a real world example.

// templates/post.js
import React from 'react';
import Layout from '../components/layout';
import SEO from '../components/seo';

const BlogPost = () => {
    const title = 'This is the blog post';
    const description = 'This is the content for the blog post.';
    const image = 'https://placeimg.com/300/300';
    const slug = '/this-is-the-blog-post';

    return (
        <Layout>
            <SEO
                title={title}
                description={description}
                image={image}
                slug={slug}
            >
                <script type='application/ld+json'>
                    {`{
                        '@context': 'https://schema.org',
                        '@type': 'LiveBlogPosting',
                        '@id': 'https://mysite.com${slug}',
                        'headline': ${title},
                        'description': ${description}
                    }`}
                </script>
            </SEO>
            <img src={image} alt={title} />
            <h1>{title}</h1>
            <p>{description}</p>
        </Layout>
    );
}

export default BlogPost;

The example above is a very simple example as far as schemas go, but it illustrates how you can use the JSON-LD format to markup your blog post data using the SEO component.

Wrapping Up

In this post, I have talked about building a better SEO component for a Gatsby site. This includes basics like a page's title and description as well as social media aspects like OpenGraph protocols. I even touched on using Schema.org markup with the new SEO component. This is all designed to make your life easier as a developer so you aren't writing the same code for every page. Whether you're using Gatsby or good old React, this component will make your life easier and at the same time improve your site's indexability for search engines.

Using the Pug Templating Engine Part 4 - Includes & Mixins

Tim Smith — Fri, 19 Feb 2021 16:25:06 +0000

Now that we've covered templating, logic, and layouts, it's time to cover the last major piece of Pug: includes and mixins. These concepts also fall into the DRY category and can help make your life as a developer much easier. First up? Includes.

How to use includes in Pug

Imagine you've got a piece of your site that will be used in various places on your site, such as a contact form. If you wanted that on two different pages, you'd have to create the form manually on each page even though they're exactly the same. Again, that leads to issues with having to update something in multiple locations. Who wants to do that?

This is exactly the reason Pug gives us the ability to use includes. Includes allow you to write some static code (no dynamic data) and put it wherever you want in the templates. In our form example, the form code would just be standard Pug templating. The code below shows what's in my form template.

// includes/form.pug
form(action='/action-goes-here' method='post')
    label(for='name') Name:
    input(type='text' name='name' id='name')
    label(for='message') Message:
    textarea(name='message' id='message')
    input(type='submit' value='Submit')

I have created a simple form with a name input, a message input, and a submit button. Rather than writing that out (or copying and pasting) everywhere I want it, I can include it. I will be using the page examples from my previous post to illustrate how things fit together. Below is an example showing how to include the form in my hello.pug page.

// hello.pug
extends layout.pug

block content
    h1 Hello, world!
    include includes/form.pug

block scripts
    script console.log('Hello, world!')

Below the h1 tag, I have added a line with the include keyword followed by the path to the file I want to include in the markup. Now the markup for that page will look like this:

<!-- output -->
<html>
    <head>
        <title>My Site</title>
    </head>
    <body>
        <header>
            <a href='/'>Home</a>
        </header>

        <h1>Hello, world!</h1>
        <form action="/action-goes-here" method="post">
          <label for="name">Name:</label>
          <input type="text" name="name" id="name">
          <textarea name="message" id="message"></textarea>
          <input type="submit" value="Submit">
        </form>

        <footer>
            <p>Site Footer</p>
        </footer>
        <script>console.log('Hello, world!')</script>
    </body>
</html>

Honestly, that's really all there is to know about includes. You write code, then include it somewhere. It is worth noting that using when using includes, the whole file is included. There's not any way to only pull certain pieces out for reuse. This is also the way you pull other data such as mixins into the current file. What if you needed this sort of idea, but with dynamic data? That's where mixins come into play.

What are mixins used for in Pug?

Mixins allow you to write chunks of Pug markup with or without dynamic data, then use that markup anywhere you want. This allows you to write a sort of "mold" of a component, then fill it out with relevant data later on. A common example of this concept is cards on social media sites. Every post gets the same basic card to put the content and user info into, but it's just filling the component with different information each time instead of being written out every time it appears.

So how do you create a mixin? Below is an example of a mixin to display a post of some sort.

// mixins/post.pug
mixin post(title, content)
    article
        h2= title
        p= content

Voila! Just like that, you have a post component. When the mixin is called, a title and content argument can be passed in and displayed appropriately. Pretty cool, huh? Now that the post mixin is ready, let's use it in a page.

// hello.pug
extends layout.pug
include mixins/post.pug

block content
    h1 Hello, world!
    include includes/form.pug

    +post('This is the title', 'This is the content')

block scripts
    script console.log('Hello, world!')

The hello.pug page looks pretty much the same as before, but with a few changes. First, there is an include statement beneath the extends layout.pug line. This is how we include the file which holds the mixin. Because it's a mixin and not just markup, it's not going to actually display anything where the include is placed. Instead, you need to call the mixin with a plus sign.

As you can see, the example above calls the post mixin, +post() with two arguments being passed in. Using the mixins in templates is pretty straightforward and should feel similar to writing JavaScript function. In the example, the title argument is "This is the title" and the content argument is "This is the content".

After using the mixin in a template, the compiled markdown will look like this:

<!-- output -->
<html>
    <head>
        <title>My Site</title>
    </head>
    <body>
        <header>
            <a href='/'>Home</a>
        </header>

        <h1>Hello, world!</h1>
        <form action="/action-goes-here" method="post">
          <label for="name">Name:</label>
          <input type="text" name="name" id="name">
          <textarea name="message" id="message"></textarea>
          <input type="submit" value="Submit">
        </form>

        <article>
            <h2>This is the title</h2>
            <p>This is the content</p>
        </article>

        <footer>
            <p>Site Footer</p>
        </footer>
        <script>console.log('Hello, world!')</script>
    </body>
</html>

It's not hard to see how this capability can make development go much faster. Passing data between code chunks or iterating over posts to spit out data programmatically is much easier when it can be done this way. Overall, you should have all of the skills needed to build most things using Pug as a templating engine, but I would like to talk about one more thing before I wrap up this post.

Pugception

All of the concepts we've discussed can be used together. For instance, you could create a block inside of an include. You could put a block inside of a mixin. You could even put a block inside of a mixin inside of an include which is in another mixin. The possibilities are endless, though the deeper you go, the harder it is to maintain the project.

I just wanted to illustrate just how flexible Pug can be to meet just about any need you may have when creating your templates.

Conclusion

Pug is an incredibly versatile templating engine for Nodejs applications. I have covered just about everything you need to build dynamic websites or applications as easily as you can. Maybe your next project will have a Pug frontend, maybe not. Either way, you know more than you did before (hopefully) and that's always a good thing.

Have questions? You can find me on Twitter @iam_timsmith.

Using the Pug Templating Engine Part 3 - Layouts

Tim Smith — Thu, 18 Feb 2021 16:10:57 +0000

So far in this series, I have covered basic templating and how to use logic when creating a frontend with Pug. Those things are enough to get a frontend up and running, but there's still more to learn which can make your developer experience much better. That's what I will be talking about in today's post.

How do I create layouts in Pug?

Pug allows you to use inheritance to create a layout for the frontend and then insert blocks of data into the layout where appropriate. If you've ever worked with something like Laravel, React, or even WordPress then this concept should feel somewhat familiar. If you haven't don't fret. I will explain what this means and why it's useful.

Imagine a time when you built a website using plain HTML and had to copy and paste the header and footer to every single HTML file you wrote. Then if you needed to update something down the road, you'd have to check EVERY SINGLE PAGE to make sure you updated it, lest you end up with broken links or images.

Template inheritance

Pug solves this issue using inheritance. What that means is that you can write your header and footer once, then extend it where you want it. This is beneficial for a few reasons: first, it saves lots of time because you don't have to write the same thing over and over (or copy and paste while checking formatting), and second because when an update is needed it can be done in one place. This is one way Pug allows you to follow a DRY (Don't Repeat Yourself) pattern when building things. The example below shows how you can set up a layout with a header and footer.

// layout.pug
html
  head
    title My Site - #{title}
  body
        header
            a(href='/') Home

        footer
            p Site Footer

Great! Now you've created a layout that doesn't actually do anything at the moment. How is that useful? In order to understand that, we need to talk about the other part of this section: blocks.

Adding blocks to a layout

To take advantage of the inheritance system, you will need to understand the concept of blocks. In short, you can specify places in your layout where content should be filled in. These places are called "blocks" and you create them by assigning them a name and then filling them out in other files. Think of it like a hamburger: We know we need a bun and patty on every burger, but we don't know what toppings are needed. In this example, the buns and patty would be the layout and the toppings would be the block so we can change the content without having to rewrite everything around it. Below is an example on how to set up blocks in the layout.

// layout.pug
html
  head
    title My Site
  body
        header
            a(href='/') Home

        block content

        footer
            p Site Footer

The change in the example above is pretty small. If you weren't looking for it, you might even miss it. All I did was add a block content where I wanted dynamic content to go. The block keyword is what indicates to Pug that this section is a block. The content is just an arbitrary name I created to indicate which block I wanted to place the content into. Blocks can be created wherever you like in the layout. Now that you have a block in place, how do we put content there?

Adding content to blocks

// hello.pug
extends layout.pug

block content
    h1 Hello, world!

The example above shows how to add dynamic content into the layout of a site using blocks. The first line is where you extend your layout file to include the contents of this file. It should be noted that the layout.pug portion of this line is actually a location relative to the current file, so in this example the current file and the layout file would be located in the same folder.

Below the extends line, you can see a block content section just like in the layout file. This is where you will insert dynamic content which will replace the block content line in the layout file when the page is rendered. Using the example I've created, the markup would look like this:

<!-- output -->
<html>
    <head>
        <title>My Site</title>
    </head>
    <body>
        <header>
            <a href='/'>Home</a>
        </header>

        <h1>Hello, world!</h1>

        <footer>
            <p>Site Footer</p>
        </footer>
    </body>
</html>

You could then create a second file with the following code to reuse the block with different content. This illustrates how beneficial the concepts of inheritance and blocks can be when building anything from small websites to enterprise level apps.

// second.pug
extends layout.pug

block content
    h1 This is the second page!

The code above would create a second page on our website with the following markup:

<!-- output -->
<html>
    <head>
        <title>My Site</title>
    </head>
    <body>
        <header>
            <a href='/'>Home</a>
        </header>

        <h1>This is the second page!</h1>

        <footer>
            <p>Site Footer</p>
        </footer>
    </body>
</html>

Can I use multiple blocks?

Notice how quick and easy it was to create the second page! 3 lines of code in the second.pug file generates a whole DOM for the new page complete with any styles attached to the layout. But what if you want to use more than one block? That's really not much different. You would just put another block somewhere in the layout file and call it the same way. The following example demonstrates how this works with a scripts block.

// layout.pug
html
  head
    title My Site
  body
        header
            a(href='/') Home

        block content

        footer
            p Site Footer

        block scripts

// hello.pug
extends layout.pug

block content
    h1 Hello, world!

block scripts
    script console.log('Hello, world!')

By adding a second block to the layout, you have the ability to add any script needed for a specific page to the DOM structure without having to load it on every page. Having this ability can greatly increase performance since libraries only needed on a single page don't have to be loaded on every other page as well.

Wrapping Up

Creating a layout can save lots of time and energy when building a website or application because it allows you to build it once and just extend it wherever needed. In addition, updates are a lot easier because you can simply update the layout file and it will change everywhere. In the next post, I will talk about how to use includes and mixins to further your ability to use a DRY approach to building things with Pug.

Have questions? You can find me on Twitter @iam_timsmith.

Using the Pug Templating Engine Part 2 - Logic

Tim Smith — Tue, 16 Feb 2021 14:13:31 +0000

In my previous post, I showed you how to create elements in Pug with classes, ids, attributes, and nesting. Today I'm going to show you how you can use variables and logic in your templates to make them dynamic and flexible, allowing you to write one template to hold lots of different pieces of information that are all formatted the same rather than writing out a separate HTML file for each one. Without further adieu, let's get started!

Creating and using variables within Pug

Using JavaScript inside a .pug file is very easy to do since it is a JavaScript templating language. Unlike php, where the code to be executed needs to be wrapped in a <?php ?> tag, all that's needed to set up a variable in Pug is a hyphen. If you then just want to put that variable into the DOM as-is, an equals sign can accomplish that. Though the example below isn't practical, it helps to show how variables can be set and used in their simplest form.

- const greeting = 'Hello, Tim'

p= greeting

// renders <p>Hello, Tim</p>

Variables created this way can be of any data type that can be used in JavaScript. Below is another example where the variable is creating an array of classes which should be applied to an element. This will illustrate how variables can be used as attributes.

- const classes = ['class-1', 'class-2']

div(class=classes) Hello

// renders <div class="class-1 class-2">Hello</div>

That's pretty cool, but what if I want to put it into a message to make, for instance, a more dynamic greeting? That can be accomplished using a string literal in the content for the element. The code below shows how this can be done.

- const name = 'Tim'

p Hello, #{name}

// renders <p>Hello, Tim</p>

In addition to just being able to print out the data from a variable, you can also manipulate it the same ways you could in plain JavaScript. This can come in handy if you're trying to make sure that all names are formatted the same or that all numbers are formatted the same. Below is an example of how you can render the variable just like it is above but in uppercase letters.

- const name = 'Tim'

p Hello, #{name.toUpperCase()}

// renders <p>Hello, TIM</p>

Having the ability to use JavaScript right in the templates makes them even more flexible because you can format things (in many cases) as it's being rendered rather than having to pass the variable through several steps before it is ready to display.

How do you use conditional logic?

As nice as it would be, users don't always fill out forms as much as we'd like. In those cases, we don't want the interface to show a message that just says "Hello, ". That would be pretty confusing to a user. To fix this, I will create some logic to display different messages depending on whether the name exists. The code for this can be found below.

If-Then statements

- const name = ''

if name
    p Hello, #{name}
else
    p Howdy, partner!

// renders <p>Howdy, partner!</p>

The conditional you see above is a simple, but common example of how logic can be used in templating. Similar to how elements are nested, you can see that conditional logic also uses indentation to determine what goes inside the if-then statement. The example shows an if statement with a check to see if the variable has a value. If so, it runs the code indented beneath it. If it evaluates to false, it will move to the else block where it runs the code indented below.

Switch Statements

If you have more than one path you need to evaluate for, you can also use a switch statement in Pug. If you've never used a switch statement, it allows you to provide a piece of data to evaluate. Inside the switch statement, you create "cases" where you provide as many possible matches (as well as a default) for the data being evaluated. Once a match is found, the switch statement executes whatever code is inside the case statement. If no match is found, the default case is used.

Below is an example of how to use a switch statement in a Pug template. In this template, I have created a case which looks at userId to determine which user to greet. The variable is set to 1, so when the switch statement executes it will follow the when 1 path. If the userId variable were set to 4, it would follow the default path since no specific case is set for that.

- const userId = 1

case userId
    when 0
        p Hello, John
    when 1
        p Hello, Tim
    when 2
        p Hello, Rita
    default
        p Howdy, partner

// renders <p>Hello, Tim</p>

Loops

Another common practice when setting up a dynamic webpage is looping over data. This is often done for menus, lists of data, or creating galleries. Writing a loop will feel similar to writing an if statement, in that we put our logic on one line and the code that should be executed is indented on the line below. The following example shows how you can render a grocery list from an array of items.

- const groceries = ['apple', 'banana', 'popcorn', 'pizza']

ul
    each item in groceries
        li= item

// renders:
// <ul>
// <li>apple</li>
// <li>banana</li>
// <li>popcorn</li>
// <li>pizza</li>
// </ul>

Looping over objects

Pug includes a really handy feature that is not as straightforward in regular JavaScript: iterating over objects. Fortunately, Pug allows you to do this in pretty much the same way as looping over an array, which makes it really easy to render key/value pairs if needed. This could be useful if the key is an element id and the value is the content for the element or other situations like that. If you need to iterate over an object, you can follow the example below.

- const foods = {fruit: "Kiwi", vegetable: "Carrot", dairy: "Milk", candy: "Snickers"}

ul
    each food, category in foods
        li My favorite #{category}: #{food}

// renders:
// <ul>
// <li>My favorite fruit: Kiwi</li>
// <li>My favorite vegetable: Carrot</li>
// <li>My favorite dairy: Milk</li>
// <li>pizza</li>
// </ul>

Wrapping Up

The ability to write JavaScript code in templates is a game changer both in terms of cleaner code and dynamic content. In this post, I've demonstrated some of the most common ways to use logic inside your templates when using Pug as a templating engine. In the next post, I'll show you how to simplify your templates using a DRY, or Don't Repeat Yourself, approach which will save time and effort.

Have questions? You can reach me on Twitter @iam_timsmith.

Using the Pug Templating Engine Part 1 - Markup

Tim Smith — Mon, 15 Feb 2021 14:14:47 +0000

If you've ever used something like Drupal, Laravel, or Adonis, you've likely encountered a template engine. A templating engine is a tool that a framework can use to assist in scaffolding a front-end for a website or webapp. The engines used in the aforementioned tools are Twig, Blade, and Edge, respectively. These languages allow you to write HTML like structures while retaining the ability to insert variables and use logic within the structure. Today I will be talking about one of the most popular templating languages for Node.js applications, Pug.

Pug, formerly known as Jade, released it's 1.0.0 version on December 22, 2013 after being in development for a few years. It has become a widely used templating engine for many websites, and for good reason: If you know how to write HTML, this will feel like a shorthand version of it. The key to writing Pug is indentation because when Pug is compiled into HTML, the indentation is how it determines how to nest the elements. There are some other items that make it a little different when writing it, but the elements, attributes, and structure are all the same as standard HTML.

How to create elements in Pug

Creating markup for a webpage in Pug may feel a bit strange at first, but after a bit will start to feel pretty intuitive. Part of this is due to the fact that you don't have to worry about closing tags, which can help lead to much cleaner files. Let's start by creating an h1 that says 'Hello, Pug'.

h1 Hello Pug

Believe it or not, the code above will create an h1 tag with the text "Hello Pug" inside. Pretty quick, right? Now, lets add a p tag (as a sibling, not a child) that says "What a beautiful day!". See if you can do it without looking at the next bit of code! When you're ready, here's what the code looks like for that:

h1 Hello Pug
p What a beautiful day!

Adding Classes and IDs to elements

What if we want to add a class to the p tag so we can give it some specific styles? If you're familiar with the tool called emmet, this will feel very familiar. If not, that's totally okay too. This won't take long to get used to either. To add a class to the p element, you can just add the selector you'd use in CSS to the element like so:

h1 Hello Pug
p.some-selector What a beautiful day!

Adding an ID to a tag works pretty much the same way. If you wanted to add an ID to the h1 tag, you could do it like so:

h1#some-id Hello Pug
p.some-selector What a beautiful day!

What if you have several classes you need to add? Pug's got you covered there too. Rather than adding the selector after the element, you can put an opening and closing parenthesis and write the class inside as though you were writing classes out on an element in HTML. There is one BIG difference though... Pug can accept the list of classes as a string (like HTML) or as an array, which can come in handy when getting a list of class names from JavaScript. The example below shows how you can write an element with multiple classes as both an array and as a string.

div(class="box box-shadow") Some content
// or
div(class=['box', 'box-shadow']) Some content

Adding other attributes

Okay, cool... but what if you need to add more than one attribute? We'll add an image with a class, src, and an alt tag. Adding attributes of any kind can be done this way, even classes and IDs. It should feel very similar to how they are written when adding them to an element in standard HTML. In the example below, you can see how to add attributes to an element.

h1#some-id Hello Pug
p.some-selector What a beautiful day!
img(class='image' src='https://placeimg.com/300/300' alt='Test Image')

Using an object for attributes

In some cases, you may want to use an object of attributes rather than writing each one out. This could be useful if you're getting attribute data from JavaScript and just want to be able to pass it into the element as-is. Perhaps you are programmatically building attributes that only one or two things changed on each iteration, who knows? Either way, attributes can be passed to elements as objects by using what's called the &attributes or "and attributes". This technique should be used with some caution because data being passed in this way is not sanitized at all and should be take care of before being used. Below is an example of an &attribute for the image we created.

h1#some-id Hello Pug
p.some-selector What a beautiful day!
img&attributes({class:'image', src: 'https://placeimg.com/300/300', alt: 'Test Image'})

Why is nesting important?

There's one more concept I would like to cover in the basics, and that is nesting. I mentioned earlier that this is how the compiler determines how the DOM should be structured as far as parents and children are concerned. To illustrate this, I will put a figure element around the img element I just created.

h1#some-id Hello Pug
p.some-selector What a beautiful day!
figure
    img(class='image' src='https://placeimg.com/300/300' alt='Test Image')

The code above doesn't look much different than it previously did, but it makes a difference in the final markup. I added a figure element below the p tag and then indented the image beneath the figure. Anything that is indented once below the figure tag will be a direct child of that tag. Had I placed the img without any indentation, it would have showed up as a sibling to the figure. This is why indentation is so crucial for determining structure in Pug.

Wrapping Up

While this has been a pretty quick introduction to templating with Pug, it should give you a basic understanding of how it compares to HTML and how it can be very beneficial in terms of readability and speed. In the next post, I will show you how you can use variables and logic in your templates to make them extremely dynamic.

If you have any questions or run into issues, you can find me on Twitter @iam_timsmith.

Let's build a search bar using React Hooks

Tim Smith — Mon, 04 Jan 2021 00:00:00 +0000

A few years ago I wrote an article called Let's build a search bar in React where I showed readers (you guessed it!) how to build a search bar in React. When I wrote that article, React Hooks didn't exist so it is written using class components. Since publishing the post, I've gotten several requests to rewrite the post showing how to build a search bar using React Hooks. After taking a break from blogging to focus on my family and being swamped with work, I'm happy to report that this is that post!

In this post, I will follow roughly the same structure as the original. In my last post I used Parcel to bundle all of my packages together and build my code. Parcel has made several improvements since that post, so I will stick with that build tool for this post.

Setting up the project

I will be using the command line interface to get my project set up. If you're new to the command line or need a refresher, I've written a blog post which explains most of the commands I will be using.

Creating the project folder and setting up a structure

To get started, I will be creating a project folder on my computer, then building out a file structure for my application. When using Parcel, you can choose how you want your project to be structured so I'm going to stick with the structure detailed below. First, the commands to set it up:

mkdir react-hooks-searchbar && cd $_

This command will create the folder for the project and move you into the folder. Next, you will create the app folder and all of the starting files in your project. Note: I'm using bash, so if you're using powershell or something similar, some of these commands won't work.

mkdir app && touch .gitignore index.html app/app.jsx

After entering the command above, your project structure should look like this:

app/
- app.jsx
.gitignore
index.html

Installing packages for the project

The next step is to install the dependencies for the project. For this project, I will keep it as basic as possible. Just like the first project, I will use React, ReactDOM, and Bulma for the front-end. Before you can install the dependencies for the project, you need to initiate the project.

npm init -y

The -y flag will answer yes to all of the questions asked when setting up a project with NPM, making things much quicker. Next, you need to install your dev dependencies. These are dependencies you will only be using in your development environment, so they don't need to be loaded on production.

npm install --dev parcel @babel/preset-react

Next you need to add the dependencies that will be used in a production environment.

npm install react react-dom bulma

Let's briefly talk about what each of the packages you've added is for:

React: A library to speed up development (seems obvious for a React tutorial, right?) Link
React-DOM: A library which allows React to interact with the DOM in a browser.Link
Parcel: A bundling library which requires no config. Link
@babel/preset-react: A library which tells Parcel how to handle JSX. Link
Bulma: A CSS framework that uses flexbox and is easy to use. Link

Checking out package.json and adding scripts

If you open your package.json file, you should see all of the dependencies listed under dependencies and devDependencies, respectively. While you have this file open, you can add scripts to run your project and babel to add babel presets. Though your versions may be different than mine when you're reading this, your package.json file should look similar to mine after adding the scripts and babel objects.

{
  "name": "react-hooks-searchbar",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "dev": "parcel index.html",
    "build": "parcel build index.html"
  },
  "babel": {
    "presets": ["@babel/preset-react"]
  },
  "dependencies": {
    "bulma": "^0.9.2",
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  },
  "devDependencies": {
    "@babel/preset-react": "^7.12.13",
    "parcel": "^1.12.4"
  }
}

Getting the index.html file ready

When Parcel begins to bundle the application, it's looking at the index.html file, which will then pull in our whole React application. Because of that, we need to fill the index.html file out with some code to tell it what to pull in. Overall, this will be a pretty simple html file. Once you have the file open in your code editor, you can type in html:5 (assuming you have emmet installed) and hit tab. The code editor will populate a bunch of default code and this will be the basis for your index.html file.

Once you have the basic scaffolding done, you need to add a div with the id of app to the body of your structure. After the div, you will need a script tag with the src being the app.jsx you created earlier. This is all you need in this file, though you can change the title of the page in the head if you like. Once all of this is done, your index.html file should look like the code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>React Hooks Search</title>
</head>
<body>
  <div id="app"></div>
  <script src="./app/app.jsx"></script>
</body>
</html>

Setting up the React Application

Now that the index.html file is set up, you can get started building your application. To get started, open up your app/app.jsx file and add the code below. This will just display an styled h1 tag that says "Search" to make sure that the configuration is working properly.

import React from 'react';
import ReactDOM from 'react-dom';
import 'bulma/bulma';

const App = () => {
  return (
    <div className="content">
      <h1>Search</h1>
    </div>
  );
}

ReactDOM.render(<App/>, document.getElementById(`app`));

Now if you start the application and visit http://localhost:1234, you should see a white background with black text that says "Search". To start the application, run the following command:

npm run dev

While using the dev script, Parcel will hot-reload the application so as you make changes to the project, it will automatically reload and update the page with the changes. This is a huge time saver since you won't have to keep starting and stopping the application.

What are React Hooks?

If you've read my previous blog posts about React Components or Building A Search Bar with React, you've seen both class and functional components.When those posts were written, only a class component could have a state. Since then, the React team has done a lot of work to make code much more concise and one of the ways they've achieved this is through hooks. Because of these huge improvements, it is possible to have state and lifecycle methods inside of a functional component.

While there are several hooks you can use for various purposes, I will just be focusing on one in particular. That hook is the useState hook, which allows you to create a piece of data as well as modify it without setting up a constructor or having to fuss with a class component.

Adding state to the App

The first step to using the useState hook is to import it from the react library. You can use it from the React object if you like, but I prefer to use named exports to keep the code a little cleaner. Your react import should now look like this:

import React, {useState} from 'react';

Now that you have imported the useState hook, you can create your state item. To do this, you will create a state variable and assign it a value. In this case, you will create a variable called list. You will also create a variable called setList which will be how you manipulate the state variable when needed. These names are arbitrary and can be whatever you like, though the typical naming convention is to put "set" before the capitalized name of the state variable. The code below illustrates how to add the list state with an array of items as the default value.

import React from 'react';
import ReactDOM from 'react-dom';
import 'bulma/bulma';

const App = () => {
  const [list, setList] = useState([
    "Go to the store",
    "Wash the dishes",
    "Learn some code"
  ]);

  return (
    <div className="content">
      <h1>Search</h1>
    </div>
  );
}

ReactDOM.render(<App/>, document.getElementById(`app`));

As you can see the variables are set to a useState function with the argument being the default value. In this case, it's an array of strings, though it could be any data type including null or you could even leave it empty.

Displaying and adding items

What good is having a list of items in state if the user can't see or add items in their list? The code below will show you how to display the items in an ordered list and create a field and button to add new items to the list. I am using the map() function here which iterates over an array and returns something. In this case the something being returned is jsx code to be rendered. The code below shows the updated code for the component.

import React, {useState} from 'react';
import ReactDOM from 'react-dom';
import 'bulma/bulma';

const App = () => {
  const [list, setList] = useState([
    "Go to the store",
    "Wash the dishes",
    "Learn some code"
  ]);

  const addItem = (e) => {
    e.preventDefault();
    const item = e.target.newItem.value;
    if (item) setList([...list, item]);
    e.target.reset();
  }

  return (
    <div className="content">
      <div className="container">
        <section className="section">
          <ul>
            {list.map((item, key) => (
              <li key={key}>{item}</li>
            ))}
          </ul>
        </section>
        <hr />
        <section className="section">
          <form className="form" onSubmit={e => addItem(e)}>
            <label htmlFor="newItem">Task:</label>
            <input
              type="text"
              className="input"
              name="newItem"
              id="newItem"
              placeholder="Something that needs to be done..."
            />
            <button className="button is-info">
              Add Item
            </button>
          </form>
        </section>
      </div>
    </div>
  );
}

ReactDOM.render(<App/>, document.getElementById(`app`));

You can see a function in the code above called addItem which gets the value of the input and add it to the array in state using the spread operator. Last, the function clears the data in the form so it's ready for the next task.

In the return, the component iterates over the items in the list array to display it for the user. When an item is added to the list array, the component will re-render and update the listed item with the new data.

Deleting Items

Now that the user can add items to their to-do list, you need to give them the ability to remove them. This will be done by adding a button to the right of each list item which triggers a function to find the item in the list array and removing it using the JavaScript filter method. Once that is done, the list being displayed will update with the specified item removed.

import React, {useState} from 'react';
import ReactDOM from 'react-dom';
import 'bulma/bulma';

const App = () => {
  const [list, setList] = useState([
    "Go to the store",
    "Wash the dishes",
    "Learn some code"
  ]);

  const addItem = (e) => {
    e.preventDefault();
    const item = e.target.newItem.value;
    if (item) setList([...list, item]);
    e.target.reset();
  }

  const handleDelete = (item) => {
    setList(list.filter(li => li !== item));
  }

  return (
    <div className="content">
      <div className="container">
        <section className="section">
          <ul>
            {list.map((item, key) => (
              <li key={key}>
                {item} <span className='delete' onClick={() => handleDelete(item)} />
              </li>
            ))}
          </ul>
        </section>
        <hr />
        <section className="section">
          <form className="form" onSubmit={e => addItem(e)}>
            <label htmlFor="newItem">Task:</label>
            <input
              type="text"
              className="input"
              name="newItem"
              id="newItem"
              placeholder="Something that needs to be done..."
            />
            <button className="button is-info">
              Add Item
            </button>
          </form>
        </section>
      </div>
    </div>
  );
}

ReactDOM.render(<App/>, document.getElementById(`app`));

Creating the Search Bar

Now that you have a functioning task list application, it's time to add the search functionality. This should be case insensitive and update in real-time. Doing this will require a search input which then uses a filter method on change to render only items in the list which match the search string.

import React, {useState} from 'react';
import ReactDOM from 'react-dom';
import 'bulma/bulma';

const App = () => {
  const [search, setSearch] = useState(``);
  const [list, setList] = useState([
    "Go to the store",
    "Wash the dishes",
    "Learn some code"
  ]);

  const addItem = (e) => {
    e.preventDefault();
    const item = e.target.newItem.value;
    if (item) setList([...list, item]);
    e.target.reset();
  }

  const handleDelete = (item) => {
    setList(list.filter(li => li !== item));
  }

  return (
    <div className="content">
      <div className="container">
        <section className="section">
          <input
            type="text"
            className="input"
            onChange={e => setSearch(e.target.value)}
            placeholder="Search..."
          />
          <ul>
            {list.filter(li => li.toLowerCase().includes(search.toLowerCase())).map((item, key) => (
              <li key={key}>
                {item} <span className='delete' onClick={() => handleDelete(item)} />
              </li>
            ))}
          </ul>
        </section>
        <hr />
        <section className="section">
          <form className="form" onSubmit={e => addItem(e)}>
            <label htmlFor="newItem">Task:</label>
            <input
              type="text"
              className="input"
              name="newItem"
              id="newItem"
              placeholder="Something that needs to be done..."
            />
            <button className="button is-info">
              Add Item
            </button>
          </form>
        </section>
      </div>
    </div>
  );
}

ReactDOM.render(<App/>, document.getElementById(`app`));

The code above adds an input and a check to see if the search string is included in any of the list items. This is not a perfect solution, but it's enough for a basic check and as a jumping off point if you need more specific functionality.

Conclusion

Just like that, you have a search bar built using React Hooks. The whole component (including imports and ReactDOM) is 63 lines long. This is compared to the original class component version which totaled 135 lines. By switching to hooks, the component becomes more readable and cuts the amount of code in half! Your application is ready create, read, delete, and search items in a task list.

Have questions? You can find me on Twitter at @iam_timsmith.