DEV Community: Masa Kudamatsu

Vanilla JS carousel that is accessible, swipeable, infinite-scrolling, and autoplaying

Masa Kudamatsu — Sun, 04 Aug 2024 06:52:33 +0000

TL;DR

A carousel that is accessible, swipeable, infinite-scrolling, and autoplaying can be coded from scratch with vanilla JS as follows.

For accessibility, implement instructions by the ARIA Authoring Practices Guide (see Sections 1 and 3 of this article).

For swipeability, use CSS Scroll Snap (Section 2).

For infinite scrolling, duplicate the first (last) slide, place it to the right (left) of the last (first) slide, and use the scrollTo() method to instantly “scroll” to the original one for creating an illusion of infinite scrolling (Section 4).

For autoplaying, use the setInterval() method. To stop autoplaying for good user experiences, employ the Intersection Observer API and the event listeners for pointerenter, focus, touchstart, and resize events (Section 5).

The exact code can be found in the CodePen demo for this article.

Why do I write this article?

There is a bunch of articles on how to build a carousel from scratch with vanilla JavaScript. But as far as I know, no one writes about a particular type of carousels: (1) accessible, (2) swipeable, (3) infinite-scrolling, and (4) autoplaying.

W3C Web Accessibility Initiative (2024b) explains how to build a carousel that is (1) accessible, (3) infinite-scrolling, and (4) autoplaying. But it is not swipeable.

A carousel by van der Schee (2021) is (2) swipeable and (4) autoplaying, which is beautifully done. But it’s not accessible or infinite-scrolling.

Buljan (2022) provides a code snippet for (3) infinite-scrolling and (4) autoplaying carousels with the use of CSS animation. It’s an elegant snippet of code, but it’s not accessible or swipeable.

This article grabs the best bits of code from these three carousels and brings them together to create a carousel that is accessible, swipeable, infinite-scrolling, and autoplaying.

The carousel to be built in this article, with the third slide shown

1. HTML for accessibility

This section heavily relies on the ARIA Authoring Practices Guide (W3C Web Accessibility Initiative 2024a and 2024b).

There are various websites for web accessibility, but as far as I can see, the ARIA Authoring Practices Guide is the most authoritative.

1.1 Carousel container

We start with a container <div> with class="carousel":



<div 
  class="carousel"
  role="group" 
  aria-label="Ryoan-ji Temple’s Rock Garden" 
  aria-roledescription="carousel" 
>
</div>

For accessibility, three attributes are necessary:

role="group" tells screen readers that all the child elements have related functionality to work together as one UI object (MDN contributors 2024a)
aria-label tells screen readers what the carousel is about. You can use aria-labelledby instead if the carousel title is another HTML element inside the carousel container.
aria-roledescription="carousel" tells screen readers that the <div> element is a carousel. According to W3C Web Accessibility Initiative (2024b), if the web page is in a language other than English, use the corresponding word in that language instead of "carousel" (e.g., aria-roledescription="スライダー" in Japanese).

According to W3C Web Accessibility Initiative (2024a), the role="group" should not be used, however, if the carousel is a landmark region, that is, a top-level section of the page along side <header>, <footer>, <main>, <aside>, <nav>, and <form> (see W3C Web Accessibility Initiative 2024c for more on landmark regions). In this case, use <section>:



<section
  class="carousel"
  aria-label="Ryoan-ji Temple’s Rock Garden" 
  aria-roledescription="carousel" 
>
</section>

Below we assume our carousel is not a landmark region, which is likely to be true in most cases.

1.2 Slide wrapper

Inside the carousel container, we first add a slide wrapper <div> with class="carousel__slides" (where I adopt the BEM convention to name classes):



<div 
  class="carousel"
  role="group" 
  aria-label="Ryoan-ji Temple’s Rock Garden" 
  aria-roledescription="carousel" 
>
  <!-- ADDED FROM HERE -->
  <div
    class="carousel__slides"
    aria-atomic="false" 
    aria-live="off" 
  >
  </div>
  <!-- ADDED UNTIL HERE -->
</div>

For accessibility, we need two ARIA attributes:

aria-atomic="false" tells screen readers that, when its text content gets updated, they should announce only the updated part rather than the entire content (MDN contributors 2024b).
aria-live="off" tells screen readers not to announce text content when it is updated. This is because, when the carousel autoplays, screen reader users do not want to hear the updated text content every time the next slide appears while they are reading another part of the page (W3C Web Accessibility Initiative 2024b).

The aria-live attribute value should be replaced with polite when the carousel autoplay is disabled. This way, every time the screen reader users manually switch the slide, the updated content does get announced.

We will use vanilla JS to toggle the aria-live value whenever autoplay is turned off (and on) in Sections 5.2 and 5.3 below.

1.3 Slide containers

Let’s add four slide containers. Of course, you can add more than 4 slides. But for the ease of exposition, I stick to 4 slides throughout this article.



<div 
  class="carousel"
  role="group" 
  aria-label="Ryoan-ji Temple’s Rock Garden" 
  aria-roledescription="carousel" 
>
  <div
    class="carousel__slides"
    aria-atomic="false" 
    aria-live="off" 
  >
    <!-- ADDED FROM HERE -->
    <div
      class="carousel__slide"
      role="group"
      aria-label="1 of 4"
      aria-roledescription="slide"
    >
    </div>
    <div
      class="carousel__slide"
      role="group"
      aria-label="2 of 4"
      aria-roledescription="slide"
    >
    </div>
    <div
      class="carousel__slide"
      role="group"
      aria-label="3 of 4"
      aria-roledescription="slide"
    >
    </div>
    <div
      class="carousel__slide"
      role="group"
      aria-label="4 of 4"
      aria-roledescription="slide"
    >
    </div>
    <!-- ADDED UNTIL HERE -->
  </div>
</div>

Each slide container <div class="carousel__slide"> should have three attributes for accessibility:

role="group" tells screen readers that its child elements constitute a single slide as a whole.
aria-label identifies each slide. In the above example, we use "1 of 4" etc. to tell screen reader users which slide they are reading right now. However, you can use any other string to identify each slide.
aria-roledescription="slide" tells screen readers that the <div> element is a slide. According to W3C Web Accessibility Initiative (2024b), if the web page is in a language other than English, use the corresponding word in that language instead of "slide" (e.g., aria-roledescription="スライド" in Japanese).

1.4 Slide content

Each slide container can have anything as its child elements, ranging from a single <img> element to a set of elements that constitute an interactive card.

For the ease of exposition, we use a single <img> element throughout this article:



<div 
  class="carousel"
  role="group" 
  aria-label="Ryoan-ji Temple’s Rock Garden" 
  aria-roledescription="carousel" 
>
  <div
    class="carousel__slides"
    aria-atomic="false" 
    aria-live="off" 
  >
    <div
      class="carousel__slide"
      role="group"
      aria-label="1 of 4"
      aria-roledescription="slide"
    >
      <!-- ADDED FROM HERE -->
      <img src="https://translating-japanese-gardens.pages.dev/ryoanji/ryoanji-banner-spring-1882.jpg" width="991" height="702"/>
      <!-- ADDED UNTIL HERE -->
    </div>
    <div
      class="carousel__slide"
      role="group"
      aria-label="2 of 4"
      aria-roledescription="slide"
    >
      <!-- ADDED FROM HERE -->
      <img src="https://translating-japanese-gardens.pages.dev/ryoanji/ryoanji-banner-summer-1882.jpg" width="991" height="702"/>
      <!-- ADDED UNTIL HERE -->
    </div>
    <div
      class="carousel__slide"
      role="group"
      aria-label="3 of 4"
      aria-roledescription="slide"
    >
      <!-- ADDED FROM HERE -->
      <img src="https://translating-japanese-gardens.pages.dev/ryoanji/ryoanji-banner-autumn-1882.jpg" width="991" height="702"/>
      <!-- ADDED UNTIL HERE -->
    </div>
    <div
      class="carousel__slide"
      role="group"
      aria-label="4 of 4"
      aria-roledescription="slide"
    >
      <!-- ADDED FROM HERE -->
      <img src="https://translating-japanese-gardens.pages.dev/ryoanji/ryoanji-banner-winter-1882.jpg" width="991" height="702"/>
      <!-- ADDED UNTIL HERE -->
    </div>
  </div>
</div>

where I include four of my own photographs of Ryoan-ji Temple’s Rock Garden, a UNESCO World Heritage site in Kyoto. We should add alt text for accessibility and, if the carousel is below the fold, implement lazy loading with loading="lazy" for performance. But that’s not the main topic of this article. So I omit those considerations here.

1.5 Navigation dots

Those tiny dots to navigate through carousel slides are often called navigation dots (or navdots for short).

Many UX design experts say you should avoid nagivation dots because they are too small to click (e.g., Friedman 2022, who suggests several alternatives to nagivation dots). However, in my humble opinion, nagivation dots are ubiquitous enough to assume that they actually help the user realize what they are seeing is a carousel. So in this artciel I go with nagivation dots.

In terms of user interface design, navigation dots should be rendered below the slides because touch device users would otherwise find the slide hidden by their own hand when tapping a navigation dot.

However, for accessibility, navigation dots should come before slides in the DOM tree because screen reader users would otherwise need to go back to read the slide after pressing a navigation dot (Weckenmann 2023):



<div 
  class="carousel"
  role="group" 
  aria-label="Ryoan-ji Temple’s Rock Garden" 
  aria-roledescription="carousel" 
>
  <!-- ADDED FROM HERE -->
  <div
    class="carousel__navdots"
    role="group"
    aria-label="Choose slide to display"
  >
    <button type="button" aria-label="1 of 4" aria-disabled="true"></button>
    <button type="button" aria-label="2 of 4" aria-disabled="false"></button>
    <button type="button" aria-label="3 of 4" aria-disabled="false"></button> 
    <button type="button" aria-label="4 of 4" aria-disabled="false"></button> 
  </div>
  <!-- ADDED UNTIL HERE -->
  <div
    class="carousel__slides"
    aria-atomic="false" 
    aria-live="off" 
  >
    <!-- Omitted for brevity -->
  </div>
</div>

The navigation dot container needs the following two attributes for accessibility:

role="group" tells screen readers that its child elements work together as the navigation control
aria-label tells screen readers that what purpose this group of buttons serves for

Each navigation dot is then rendered as a <button type="button"> element with two ARIA attributes.

First, aria-label refers to the corresponding slide’s accessible name. Here you could in theory use aria-labelledby to refer to the id attribue value of each slide. However, perhaps surprisingly, the implementation of aria-labelledby differs across screen readers (PowerMapper 2023, as cited by GrahamTheDev 2020). It’s best to directly label each navigation dot.

Second, aria-disabled should be true for the navigation dot that corresponds to the current slide. It effectively tells screen reader users which slide is currently shown. We will toggle this value with vanilla JavaScript in Section 3.6 below.

That's all for how to make navigation dots accessible. Before moving on, however, let me discuss a couple of alternative approaches to mark up navigation dots.

First, navdots can be marked up with <a> elements as jump links to slides (by assigning the id attribute to each slide). See Coyier (2019) for a simple example. The swipeable and autoplaying carousel by van der Schee (2021) also uses this approach.

However, the jump-link approach is not convenient to create infinite-scrolling carousels as we will see in Section 4 below. This is why I go for <button> elements and use vanilla JavaScript to scroll the carousel.

Second, navigation dots can also be marked up as tabs. This approach is known as the "tabbed" pattern (as opposed to the "grouped" pattern adopted in this article). See W3C Web Accessibility Initiative (2024d) and Deque Systems (undated) for how to implement the "tabbed" pattern.

However, Webb (2021) reports that low-vision and blind users find the "tabbed" pattern very confusing. Given this piece of evidence, I believe the "grouped" pattern is better to mark up navigation dots.

2. CSS for swiping to slide

Now that we get HTML right for accessibility, let’s start working on CSS so that touch device users can swipe the carousel to see the next and previous slides.

2.1 Setting each slide width

First of all, set the width of the carousel and each slide:



.carousel {
  width: 991px;
}
.carousel__slides,
.carousel__slide {
  width: 100%;
}

The above implements a carousel where each slide is 991px wide (because each image is 1882px wide) and only one slide is shown at a time.

If you want to show multiple slides (possibly partly hidden outside the window edges) on both sides of the center slide, rewrite the above CSS code as follows:



.carousel {
  width: 100%;
}

where setting the carousel width is delegated to its parent element. Without explicitly specifying the width of the slide wrapper and each slide, the image’s intrinsic width will be the width of each slide while the slide wrapper takes the same width as the carousel container.

2.2 CSS Scroll Snap for slides

Here is the most important part of CSS to make a carousel swipeable:



.carousel__slides {
  display: flex;
  column-gap: 20px; /* optional */
  overflow: auto;
  scroll-snap-type: x mandatory;
}
.carousel__slide {
  flex: 0 0 auto;
  scroll-snap-align: center;
}

The display: flex arranges slides horizontally while overflow: auto makes the slide wrapper scrollable to reveal overflown slides. The column-gap is optional: it allows you to add whitespace between a pair of slides. The flex: 0 0 auto makes sure that each slide won’t get magnified or shrunk unexpectedly due to the carousel’s width.

Crucial to display the current slide at the center of the slide wrapper is the pair of scroll-snap-type (for the slide wrapper) and scroll-snap-align: center (for each individual slide). This technique, known as CSS Scroll Snap, is well-documented elsewhere (e.g., Rifki (2020)).

This way, touch device users can swipe the carousel to the left, or to the right, to reveal slides initially hidden. CSS Scroll Snap makes sure that the slide is shown at the center after each swiping gesture.

Many carousel plugins had been created before all major browsers supported CSS Scroll Snap around the year of 2020. Which means they use JavaScript to achieve the same feature, causing a bulky bundle size and worsening the performance (cf. Hempenius 2021).

The most popular carousel library, Swiper, has updated its API to support CSS Scroll Snap with what it calls CSS mode. It seems to me that this causes Swiper’s API more complicated than necessary, which prompted me to build a carousel from scratch (and write this article).

2.3 Disable scroll bars

However, the above CSS code reveals a scroll bar. We do not need it as the navigation dots will serve the same purpose. Hide the scroll bar is, however, a little tricky:



.carousel__slides {
  scrollbar-width: none; /* for Firefox and latest Chromium */
}
.carousel__slides::-webkit-scrollbar {
  display: none; /* for Safari and legacy Chromium */
}

The scrollbar-width property is supported only by Firefox (since late 2018) and those Chromium browsers released in early 2024 (Can I Use 2024). As a fallback, we need the ::-webkit-scrollbar pseudo element (see John 2023 for more detail).

3. CSS and JS for Navigation Dots

Let’s style navigation dots and make them accessible dynamically.

3.1 Positioning navigation dots

First, let’s position the navigation dots below the slides. In Section 1.5 above, we have written nagivation dots first and slides second in the HTML code. With CSS, we need to reverse this order.



.carousel {
  padding-bottom: 60px;
  position: relative;
}
.carousel__navdots {
  bottom: 0;
  position: absolute;
}

The use of position: relative allows the navigation dots to be placed anywhere inside the carousel container. The padding-bottom creates a space below the slides for navigation dots. Its exact value can be anything to achieve your own design, of course.

Then, the navigation dot container is positioned on the lower edge of the carousel container (with bottom: 0).

Next, style the navigation dot container to set the layout of dots:



.carousel__navdots {
  bottom: 0;
  column-gap: 16px; /* ADDED */
  display: flex;  /* ADDED */
  justify-content: center;  /* ADDED */
  left: 0; /* ADDED */
  position: absolute;
  right: 0; /* ADDED */
}

The flexbox along with column-gap allows navigation dots to be equally spaced (by 16px in this example). The justify-content: center and the pair of left: 0 and right: 0 center-aligns the navigation dots horizontally relative to the carousel container.

3.2 Styling each navigation dot

Second, style each individual navigation dot:



.carousel__navdots button {
  /* reset default button style */
  -moz-appearance: none;
  -webkit-apperance: none;
  appearance: none;
  border: 0;
  cursor: pointer;
  /* style as a grey dot */
  background-color: #9a9a9a; 
  border-radius: 50%;
  height: 10px;
  padding: 0;
  width: 10px;
}

The first five CSS properties reset the default style of <button> elements (Shadeed 2020). The rest is up to you. Here each dot is a grey circle with the diameter of 10px.

3.3 Dynamic styling

Finally, style the focus and active states of navigation dots:



.carousel__navdots button:focus-visible {
  outline: 2px solid #0060a8; /* blue */
  outline-offset: 2px;
}
.carousel__navdots button.is-active {
  background-color: #0060a8; /* blue */
}

The .is-active class will be added with JavaScript to indicate which slide is currently shown.

3.4 JS for click event handler

This and next subsections heavily rely on the technique proposed by Buljan (2022).

Let’s first collect the components of the carousel:



// Components
const carouselContainer = document.querySelector('.carousel');
const slideWrapper = document.querySelector('.carousel__slides');
const slides = document.querySelectorAll('.carousel__slide');
const navdotWrapper = document.querySelector('.carousel__navdots');
const navdots = document.querySelectorAll('.carousel__navdots button');

Next, retrieve and/or set parameters:



// Parameters
const n_slides = slides.length;
const n_slidesCloned = 0;
let slideWidth = slides[0].offsetWidth;
let spaceBtwSlides = Number(window.getComputedStyle(slideWrapper).getPropertyValue('grid-column-gap').slice(0, -2)); // drop px at the end
function index_slideCurrent() {
  return Math.round(slideWrapper.scrollLeft / (slideWidth + spaceBtwSlides) - n_slidesCloned);
}

The first one n_slides is simply the number of slides in the carousel. Rather than hardcoding a number, it’s set to be slides.length so that we won’t need to change any code when a new slide is added to the carousel.

The second one n_slidesCloned will play a crucial role when we make the carousel infinitely-scrolling. For the time being, however, it’s set to be zero.

The third one, slideWidth, is the width of each slide. It assumes all the slides are of equal width. It is defined with let, because the slide width can change when the user resizes the browser window width (see Section 3.7 below).

The fourth one, spaceBtwSlides, is the width of whitespace between the pair of slides next to each other. Again, it is defined with let as the width of whitespace can change in response to browser window resizing (see Section 3.7 below).

Finally, index_slideCurrent() computes the index of the slide currently shown from how much the slide wrapper is scrolled (slideWrapper.scrollLeft). We use this value to choose which navigation dot gets the .is-active class and thus changes its color to blue.

Next, let’s attach a click event handler to each navigation dot:



// Nav dot click handler
function goto(index) {
  slideWrapper.scrollTo((slideWidth + spaceBtwSlides) * (index + n_slidesCloned), 0);
}
for (let i = 0; i < n_slides; i++) {
  navdots[i].addEventListener('click', () => goto(i));
}

Now clicking each navigation dot will reveal its corresponding slide.

3.5 Smooth scrolling

When the navdot click handler executes the scrollTo() method, the slides scroll abruptly. However, we want to create an illusion of the sliding movement so that the user will perceive the carousel as scrolling horizontally.

For this purpose, the CSS property scroll-behavior needs to be set as smooth:



.carousel__slides.smooth-scroll {
  scroll-behavior: smooth;
}

Here, I apply the smooth scrolling only when the slide wrapper gets the .smooth-scroll class, which is done at the end of the JS script at the time of page load:



// Initialization
slideWrapper.classList.add('smooth-scroll');

This way, we are able to turn the smooth scrolling on and off programatically for the purpose of making the carousel infinitely-scrolling. See Section 4.2 below for the detail.

3.6 JS for dynamically styling navigation dots

We start with a helper function that applies the .is-active class to a navigation dot with the given index:



// Marking the nav dot for the current slide
function markNavdot(index) {
  navdots[index].classList.add('is-active');
  navdots[index].setAttribute('aria-disabled', 'true');
}

If you are unsure of why we also need to toggle the value of the aria-disabled attribute, go back to Section 1.5 above.

We then create another helper function that runs markNavdot() for the one corresponding to the currently shown slide:



// Updating the marked nav dot
function updateNavdot() {
  const c = index_slideCurrent();
  if (c < 0 || c >= n_slides) return;
  markNavdot(c);
}

The second line is unnecessary at this moment, but it plays a crucial role when we make the carousel infinitely-scrolling by duplicating the first slide and placing it to the right of the last one (so c >= n_slides applies when it is currently shown) or duplicating the last slide and placing it to the left of the first one (so c < 0 applies when it is currently shown). When these duplicate slides are shown, we do not want to update navigation dots because we immediately swap them with the original ones. See Section 4 for detail.

We then use a scroll event handler to execute the updateNavdot():



slideWrapper.addEventListener('scroll', () => {
  // reset
  navdots.forEach(navdot => {
    navdot.classList.remove('is-active');
    navdot.setAttribute('aria-disabled', 'false');
  });
  // mark the navdot
  updateNavdot();
});

Every time the user scrolls the carousel, the scroll event fires, removing the is-active class from all the navigation dots and marking the one that corresponds to the current slide.

Finally, we mark the first navigation dot upon the page loading:



// Initialization
markNavdot(0); // ADDED
slideWrapper.classList.add('smooth-scroll');

Here is the entire JS code added in this subsection:



// Marking the nav dot for the current slide
function markNavdot(index) {
  navdots[index].classList.add('is-active');
  navdots[index].setAttribute('aria-disabled', 'true');
}
// Updating the marked nav dot
function updateNavdot() {
  const c = index_slideCurrent();
  if (c < 0 || c >= n_slides) return;
  markNavdot(c);
}
slideWrapper.addEventListener('scroll', () => {
  // reset
  navdots.forEach(navdot => {
    navdot.classList.remove('is-active');
    navdot.setAttribute('aria-disabled', 'false');
  });
  // mark the navdot
  updateNavdot();
});

// Initialization
markNavdot(0); // ADDED
slideWrapper.classList.add('smooth-scroll');

3.7 Responsive design

The above code can cause trouble if the carousel slide width and its spacing changes depending on the window width. Desktop users may frequently change the browser window size. So we need to set the resize event handler to keep slideWidth and spaceBtwSlides updated:



window.addEventListener('resize', () => {
  // update parameters
  slideWidth = slides[0].offsetWidth;
  spaceBtwSlides = Number(window.getComputedStyle(slideWrapper).getPropertyValue('grid-column-gap').slice(0, -2)); // drop px at the end and conver the string into number
});

At this stage, the standard carousel is up and running.

Now we are ready to make the carousel infinitely-scrolling.

4. JS for infinite-scrolling

An infinite-scrolling carousel is rather easy to implement if we forget about user interactions. Both Oliver (2017) and Pared (2021) show how to use CSS animation to make a carousel infinite-scrolling.

On the other hand, Buljan (2022) uses CSS transition instead, which allows him to add user interactions via navigation dots and next/prev buttons. But swiping gesture is disabled because the carousel "slides" by the translateX() CSS function.

But his approach enlightens me: to create an illusion of infinite-scrolling to the user, we need to duplicate the first slide to the right of the last one and then instantly "scroll" backward to the original first slide.

This section describes how I’ve manage to achieve this illusion for a swipeable carousel. Maybe there is a better way, though. Post a comment if you know something better.

4.1 Duplicating slides

To duplicate HTML elements, we can use the .cloneNode(true) method:



const firstSlideClone = slides[0].cloneNode(true);
firstSlideClone.setAttribute('aria-hidden', 'true');
slideWrapper.append(firstSlideClone);

The above code attaches the cloned first slide as the last in the series of slides. But this cloned slide serves no purpose to the screen reader users. So I add aria-hidden: true to it.

Likewise, we can attach the cloned last slide as the first in the series of slides:



const lastSlideClone = slides[n_slides - 1].cloneNode(true);
lastSlideClone.setAttribute('aria-hidden', 'true');
slideWrapper.prepend(lastSlideClone);

We can repeat this to clone the second slide (and the second-to-last slide) and so on, if you need to show multiple slides in a row for wide screen devices.

Now we should replace the paremeter n_slidesCloned:



const n_slidesCloned = 1; /* revised */

This way, the correct navigation dot gets marked (see Section 3.4 above).

4.2 Instantly scrolling back/forward to the original

Now we want to instantly scroll the duplicated slide with the original one in a way the user won’t notice it. This is tricky, however, because it conflicts with smooth scrolling. We need to disable it when we scroll back/forward to the original slide. And I've learned hard that the CSS smooth scrolling takes time to be disabled.

Remember that the .smooth-scroll class needs to be applied to the slide wrapper to enable smooth scrolling (see Section 3.5 above). So the helper function to instantly scroll back to the first slide takes the following shape:



function rewind() {
  slideWrapper.classList.remove('smooth-scroll');
  setTimeout(() => { // wait for smooth scroll to be disabled
    slideWrapper.scrollTo((slideWidth + spaceBtwSlides) * n_slidesCloned, 0);
    slideWrapper.classList.add('smooth-scroll');
  }, 100);
}

I find the delay of 100ms is enough for smooth scrolling to be disabled.

Similarly, here is the function to instantlly scroll forward to the last slide:



function forward() {
  slideWrapper.classList.remove('smooth-scroll');
  setTimeout(() => { // wait for smooth scroll to be disabled
    slideWrapper.scrollTo((slideWidth + spaceBtwSlides) * (n_slides - 1 + n_slidesCloned), 0);
    slideWrapper.classList.add('smooth-scroll');
  }, 100);
}

You might wonder why I don’t use scrollBy() or scrollIntoView() instead of scrollTo(). I tried both and found they were unreliable. The scrollBy(), when combined with CSS Scroll Snap, behaves unreliably: Safari fails to snap the slide at the center for some reason. The scrollIntoView() is not reliable for horizontal scrolling, as commented by Werner (2019).

Finally, we execute these helper functions when the cloned last/fist slide fully appears after the carousel is scrolled. For this purpose, we revise the scroll event handler (defined in Section 3.6 above) as follows:



// Handle scroll events
let scrollTimer; // ADDED
slideWrapper.addEventListener('scroll', () => {
  navdots.forEach(navdot => {
    navdot.classList.remove('is-active');
    navdot.setAttribute('aria-disabled', 'false');
  });

  // REVISED FROM HERE
  if (scrollTimer) clearTimeout(scrollTimer); // to cancel if scroll continues
  scrollTimer = setTimeout(() => {
    if (slideWrapper.scrollLeft < (slideWidth + spaceBtwSlides) * (n_slidesCloned - 1 / 2)) {
      forward();
    }
    if (slideWrapper.scrollLeft > (slideWidth + spaceBtwSlides) * ((n_slides - 1 + n_slidesCloned) + 1/2)) {
      rewind();
    }
  }, 100);
  // REVISED UNTIL HERE

  updateNavdot();
});

First, we use setTimeout() and clearTimeout() so that we won’t run the code for the instant scrolling while the user keeps scrolling the carousel.

Then, when the carousel is scrolled forward to reveal about half of the cloned first slide, the rewind() gets executed. Similarly, when the carousel is scrolled backward to reveal about half of the cloned last slide, the forward() gets executed.

I use half as the threshold because, for some reason, the scrollLeft value does not necessarily reflect the theoretical value based on the number of slides and its spacing. For example, when slideWidth is 312 and spaceBtwSlides is 20, the scrollLeft value may be 331.5 when the carousel hides one slide to the left. Buffering by half of the slide width prevents unexpected behavior from happening due to scrollLeft values.

There is one more reason for using _half_ as the threshold. Even when the user stops scrolling, CSS Scroll Snap makes the carousel continue scrolling until the slide takes its center position. Only then the above scroll event handler implements the code inside the setTimeout(). To activate this CSS Scroll Snap behavior, revealing at least half of the next element is enough.

This way, the rewind() and forward() functions get executed to swap the cloned slide with the original one without the user noticing it, creating an illusion of infinite scrolling.

4.3 Initial slide

Finally, we show the first slide, not the cloned last slide, upon page load:



// Initialization
goto(0); // ADDED
markNavdot(0);
slideWrapper.classList.add('smooth-scroll');

Note that goto(0) needs to be executed before adding the .smooth-scroll class to active smooth scrolling. Otherwise, the user may see the carousel scrolling from the cloned last slide to the first slide.

4.4 Why not jump-link navigation dots?

In Section 1.5 above, I wrote marking up navigation dots as <a> elements is “not convenient to create infinite-scrolling carousels”. This is because, as I explained in this section, we need to duplicate the first and last slides to create the illusion of infinite-scrolling. Then, the id attribute value for each slide will also be duplicated, causing jump-links to fail.

Maybe there is a workaround. Let me know if you have an idea, by posting a comment to this article.

Now we have the carousel infinite-scrolling. The last challenge is to make our carousel autoplay.

5. JS for autoplay

5.1 Moving to next slide

First of all, we need a function to execute for scrolling the carousel to the next slide:



function next() {
  goto(index_slideCurrent() + 1);
}

Then, by executing this function repeatedly, we can implement the autoplaying feaeture.

5.2 Starting to autoplay

To do so, we create a function to start autoplaying the carousel with the use of setInterval():



const pause = 2500;
let itv;
function play() {
  // early return if the user prefers reduced motion
  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
    return;
  }
  clearInterval(itv);
  slideWrapper.setAttribute("aria-live", "off");
  itv = setInterval(next, pause);
}

The pause variable sets the interval: in this example, the carousel automatically switches to the next slide every 2.5 seconds.

Then we define the play() function which starts autoplaying the carousel. It first checks the user preference on reduced motion. If the user disables animation, this function returns so that autoplay won’t start.

Then, set the aria-live attribute to be off so that screen readers won’t read out the carousel content every time the slide changes (see Section 1.2).

Finally, execute the next() function (defined in section 5.1 above) every 2.5 seconds. This setInterval() function is stored as the itv variable so that it will first get cleared with clearInterval() every time the play() runs. Otherwise, multiple setInterval() functions may run at the same time, changing the slide more frequently than every 2.5 seconds.

The interval of 2.5 seconds is probably too short in most cases. This short interval can make sense if the whole purpose of the carousel is to stress the presence of several examples of something in a short period of time with the detail of each unimportant.

For most cases, however, a longer interval is desirable to allow the user to understand what each slide is about. Friedman (2022) recommends five to seven seconds.

5.3 Stopping autoplay

It is very important to stop autoplay whenever the user interacts with the carousel:

It goes without saying that auto-rotation should stop entirely when a user interacts with a slice of the carousel, be it by hovering, focusing, or tapping through available options. Interrupting the exploration of selected items is a safe way to drive users away from the carousel for good. — Friedman (2022)

So we first define the helper function that stops autoplay:



function stop() {
  clearInterval(itv);
  slideWrapper.setAttribute("aria-live", "polite");
}

It clears the setInterval() function that implements autoplay. Then it sets aria-live to be polite so that screen readers will announce content changes when the user presses a navigation dot, for example (see Section 1.2 above).

5.4 Intersection Observer

The first instance to start autoplay is when the carousel fully enters into the user’s viewport. It doesn’t make sense to autoplay the carousel when it’s not shown entirely to the user.

For the same reason, the autoplay should stop when part of the carousel goes outside the viewport.

To implement this feature, we use the mighty Intersection Observer:



const observer = new IntersectionObserver(callback, {threshold: 0.99});
function callback(entries, observer) {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      play();
    } else {
      stop();
    }
  })
}

observer.observe(carouselContainer);

I use the threshold of 0.99. When the threshhold is 1, Edge fails to implement Intersection Observer as reported by Мария 2019. When the threshold is 0.999, MacOS Safari fails to start autoplaying when the entire carousel is shown upon page load, because it computes the intersectionRatio property (i.e. the fraction of the element visible inside the viewport) to be something like 0.9988713264465332. Indeed, Almand (2019) reports that “the number will be somewhere between 0.99 and 1.” So it is safe to set the threshold to be 0.99.

Also one important thing to remember is that the callback function will be executed when observer.observe() gets executed in the script (snewcomer 2018). This means that if the callback function is simply play(), the autoplay starts as soon as the page is loaded, defeating the whole purpose of using the Intersection Observer. Make sure you check whether the carousel is inside the viewport with entry.isIntersecting.

5.5 Togging autoplay for mouse users

Next, we want to disable autoplay whenever mouse users hover the cursor over the carousel. No one is happy if the carousel moves when he/she tries to click a button within the slide or one of those navigation dots.

For this purpose, we use pointerenter and pointerleave event listeners and attach them to the carousel container:



carouselContainer.addEventListener("pointerenter", () => stop());
carouselContainer.addEventListener("pointerleave", () => play());

5.6 Togging autoplay for keyboard users

Next, keyboard users do not want the carousel to move when they press the Tab key to focus on interactive elements inside it such as navigation dots.

For this purpose, we use focus and blur event listeners:



carouselContainer.addEventListener("focus", () => stop(), true);
carouselContainer.addEventListener("blur", () => {
  if (carouselContainer.matches(":hover")) return;
  play();
}, true);

The option true is necessary to catch the focus/blur event fired by any element inside the carousel container.

When the blur event fires, the above code first checks if the cursor is inside the carousel. If so, it won’t restart autoplay. This is for those mouse users who may use the Tab key to interact with buttons (maybe because they minimize the use of a mouse due to wrist injury).

The use of .matches(":hover") is a clever technique, suggested by Jacob (2019), to check whether the cursor is inside an element

5.7 Togging autoplay for touch device users

For smartphone and tablet users, it will be annoying to activate autoplay after swiping the carousel to look at a new slide.

In my humble opinion, the best UX in this case will be achieved by the following:



carouselContainer.addEventListener("touchstart", () => stop());

The touchstart event fires whenever the user touches the carousel, in which case autoplay stops. Unlike the pointerleave and blur events, however, I don’t restart autoplay when the touchend event fires.

The whole JS script for autoplay is as follows:



// Autoplay
function next() {
  goto(index_slideCurrent() + 1);
}
const pause = 2500;
let itv;
function play() {
  // early return if the user prefers reduced motion
  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
    return;
  }
  clearInterval(itv);
  slideWrapper.setAttribute("aria-live", "off");
  itv = setInterval(next, pause);
}
function stop() {
  clearInterval(itv);
  slideWrapper.setAttribute("aria-live", "polite");
}
// Start autoplay when the carousel is fully shown
const observer = new IntersectionObserver(callback, {threshold: 0.99});
observer.observe(carouselContainer);
function callback(entries, observer) {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      play();
    } else {
      stop();
    }
  })
}
// for mouse users
carouselContainer.addEventListener("pointerenter", () => stop());
carouselContainer.addEventListener("pointerleave", () => play());
// for keyboard users
carouselContainer.addEventListener("focus", () => stop(), true);
carouselContainer.addEventListener("blur", () => {
  if (carouselContainer.matches(":hover")) return;
  play();
}, true);
// for touch device users
carouselContainer.addEventListener("touchstart", () => stop());

5.8 Toggling autoplay for window resizing

There is one more thing to consider. We want to stop autoplay when desktop users resize the browser window size. This will prevent the carousel from sliding by the distance based on the previous window size.

So we revise the resize event listener (defined in Section 3.7 above) as follows:



let resizeTimer; // REVISED
window.addEventListener('resize', () => {
  slideWidth = slides[0].offsetWidth;
  spaceBtwSlides = Number(window.getComputedStyle(slideWrapper).getPropertyValue('grid-column-gap').slice(0, -2)); // drop px at the end

  // REVISED FROM HERE
  if(resizeTimer) clearTimeout(resizeTimer);
  stop();
  resizeTimer = setTimeout(()=>{
    play();
  }, 400);
  // REVISED UNTIL HERE
});

Similarly to the scroll event listener described above, with the use of setTimeout() and clearTimeout(), we wait to implement play() until the user stops resizing the window.

That's all. Now you have a carousel that is accessible, swipeable, infinite-scrolling, and autoplaying!

Last words

Perhaps the carousel that you need to build from scratch is not exactly the same as the one built above. However, I hope this article (along with many cited articles listed below) will open the door for you to build your own carousel from scratch!

Changelog

Aug 14, 2024 (v1.0.1): Revise TL;DR to indicate that Section 3 is also about making a carousel accessible.

References

Almand, Travis (2019) “An Explanation of How the Intersection Observer Watches”, CSS-Tricks, Sep 24, 2019.

Buljan, Roko C. (2022) “Infinite JavaScript Carousel”, Stack Overflow, Jul 15, 2022.

Can I Use (2024) “CSS property: scrollbar-width”, Can I Use?, acccessed on Jul 21, 2024.

Coyier, Chris (2019) “Real Simple Slider”, CodePen, May 7, 2019.

Deque Systems (undated) “Carousel (based on a tabpanel)”, Deque University, undated.

Friedman, Vitaly (2022) “Usability Guidelines For Better Carousels UX”, Smashing Magazine, Apr 13, 2022.

GrahamTheDev 2020 “They are indeed very similar, there is one key distinction...”, Stack Overflow, Jul 21, 2020.

Hempenius, Katie (2021) “Best practices for carousels”, web.dev, Jan 26, 2021.

Jacob (2019) “In modern browsers you can just do element.matches(':hover')”, Stack Overflow, Aug 12, 2019.

John, Theodore (2023) “Scrollbar Styling in Chrome, Firefox, and Safari — Customizing Browser Elements”, Medium, Jul 4, 2023.

Мария (2019) “Intersection Observer doesn't work in Edge”, Stack Overflow, May 29, 2019.

MDN contributors (2024a) “ARIA: group role”, MDN Web Docs, last updated Apr 17, 2024.

MDN contributors (2024b) “WAI-ARIA basics”, MDN Web Docs, last updated Jan 1, 2024.

Oliver, Jack (2017) “Infinite autoplay carousel”, CodePen, Nov 3, 2017.

Pared, Warren (2021) “Making an infinite CSS carousel”, Dev Community, Apr 12, 2021.

PowerMapper (2023) “WAI-ARIA Screen reader compatibility”, PowerMapper Screen Reader Tests, Dec 12, 2023.

Rifki, Nada (2020) “How to use CSS Scroll Snap”, LogRocket, Mar 9, 2020.

Shadeed, Ahmad (2020) “Styling The Good Ol' Button Element”, ishadeed.com, Feb 19, 2020.

snewcomer (2018) “That is the default behaviour. When you instantiate an instance of the IntersectionObserver, the callback will be fired...”, Stack Overflow, Nov 20, 2018.

van der Schee, Joost (2021) “Carousel with CSS scroll snap”, CodePen, Apr 17, 2021.

W3C Web Accessibility Initiative (2024a) “Carousel (Slide Show or Image Rotator) Pattern”, ARIA Authoring Practices Guide, last updated on Feb 13, 2024.

W3C Web Accessibility Initiative (2024b) “Auto-Rotating Image Carousel Example with Buttons for Slide Control”, ARIA Authoring Practices Guide, last updated on Feb 13, 2024.

W3C Web Accessibility Initiative (2024c) “Landmark Regions”, ARIA Authoring Practices Guide, last updated Feb 13, 2024.

W3C Web Accessibility Initiative (2024d) “Auto-Rotating Image Carousel with Tabs for Slide Control Example”, ARIA Authoring Practices Guide, last updated Feb 13, 2024.

Webb, Jason (2021) “When testing the "tabbed" pattern with live low-vision, blind, and deafblind users at Accessible360...”, Dev Community, Oct 2, 2021.

Weckenmann, Sonja (2023) “A Step-By-Step Guide To Building Accessible Carousels”, Smashing Magazine, Feb 17, 2023.

Werner, Thomas (2019) “Unfortunately scrollIntoView doesn’t seem to behave consistently across platforms...”, Dev Community, Apr 12, 2019.

Responsive images: DIY implementation in 6 steps

Masa Kudamatsu — Sat, 05 Aug 2023 23:25:00 +0000

TL;DR

If you as a web developer need to make images responsive to screen widths and device pixel ratios on your own, take this 6-step procedure:

Step 1: Figure out the maximum width of each image required by the design of your webpage. Let’s say, it is 624px.

Step 2: Convert the original image file into two versions: one with the maximum width (624px in our example) and the other with double the maximum width (1248px). Image resizing can easily be done with tools like sips, a command line tool of MacOS.

Step 3: Refer to these two image files with the following temporary <img> element:

<img
  sizes="100vw"
  srcset="image1248.png 1248w"
  src="image624.png"
/>

Step 4: Render the webpage with your favorite browser and click the RespImageLint bookmarklet. It gives you the correct value for the sizes attribute and the widths of additional image files needed to minimize the loading time across all screen types.

Step 5: Revise the HTML code by incorporating RespImageLint’s suggestions. In our example, it is something like:

<img
  sizes="
    (max-width: 600px) calc(100vw - 70px), 
    (max-width: 766px) calc(100vw - 141.25px), 
    624px
  "
  srcset="
    image624.png   624w,
    image990.png   990w,
    image1248.png 1248w
  "
  src="image624.png"
/>

Step 6: Convert the original image file into the ones suggested by RespImageLint, again using tools like the sips command line tool of MacOS. Then save them as indicated in the HTML code written in Step 5.

Below I elaborate on each step, after a brief explanation of why I’m writing this article.

Why writing this article?

[Feel free to skip this section: all the sections below are independent of what is written in this section]

Putting images on a webpage is hard. “[T]here are … 927 things you could (and some you really should) do that often go overlooked”, wrote Chris Coiyer (2021).

In particular, implementing responsive images is really complicated. You have to think about various screen widths and device pixel ratios in order to decide which widths of each image to prepare for minimizing the loading time.

While many services out there help you automate the generation of responsive image files and the associated HTML code, what if you have to do it all yourself?

I was recently in such a situation. I tried to find the easy-to-follow procedure of making images responsive with the minimum amount of effort. This article reports what I have arrived at.

There are many articles on responsive images across the web. But, as far as I know, they are all too lengthy, not very helpful for a quick DIY implementation. The closest to this article in spirit is Archibald (2021), which proposes “the lazy way” of implementing responsive images. This article intends to improve this “lazy” approach.

Step 1: Maximum image width

The original image files are most likely to be a lot larger than the size required by the design of your webpage. So the first step is to figure out how large each image file needs to be given the design of your website.

The maximum width of images is usually given by the design for desktop screens. But not necessarily. In the example given by Archibald (2021), it is when the screen width is 799px beyond which the images are shrunk to leave side margins.

For the ease of exposition below, let’s say our website design requires the images that are 624px wide at most.

Step 2: Image file conversion (Part I)

The second step towards responsive images is to convert the original image file into two versions of it: one with the maximum width (624px in our example) and the other with double the maximum width (1248px in our example).

The former is for non-retina screens (1x) while the latter is for retina screens (2x), when the user’s screen width requires the maximum image width identified in Step 1.

Enough to deal with 2x screens only

You might ask, “What about those device pixel ratios (DPR) other than 2x?” As far as I understand, we can ignore them. Here’s why.

Osmani (2021) argues that “[t]he human eye may not be capable of distinguishing the difference between images that are a 2x-3x DPR vs. an even higher resolution.”

He also reports:

Twitter capped their image fidelity at 2x, resulting in 33% faster timeline image loading times. They found that 2x was a sweet spot of both good performance wins with no degradation in quality metrics.

For more on this approach adopted by Twitter, see O'Brien (2019).

So we just need to care about 2x screens, even though higher resolution screens are widely available in the market today.

Image resizing tools

Now the question is how to resize your original images. According to Hempenius (2018):

Two of the most popular image resizing tools are the sharp npm package and the ImageMagick CLI tool.

If you are a Mac user, there is a third alternative: sips, which I find very easy to use. Dachis (2012) explains how to resize image files in a batch by using this command line tool installed in Mac OS by default. Following this article, you can do the following:

Make copies of your original image files and save them in a new folder.
In Terminal, moving to this folder with the cd command. Then execute the following command:

sips -Z 1248 *.png

which overwrites the original image files and resizes them to the width of 1248px (if the width is larger than the height) without distorting their aspect ratio.

If the height of an image is larger than its width, use the following command instead:

sips --resampleWidth 1248 *.png

This is what I have figured out by reading the documentation of sips.

Step 3: Draft HTML code

Now write down a draft of the HTML code to embed each image:

<img
  sizes="100vw"
  srcset="image1248.png 1248w"
  src="image624.png"
/>

Temporary `sizes` value

The value for sizes is temporary. It’s not easy to figure out the correct value for your webpage design (see Coyier 2020). It’s best to rely on an external tool that does all the hard job. That’s for Step 4 below.

Go with `w` descriptor, not `x` descriptor

The value for srcset is also temporary, just including the largest image file at this moment.

Note that I use the w descriptor. As far as I can see, the consensus among web developers is to use w, not x, for responsive images. Accoridng to Coyier (2020):

... x descriptors only account for a small percentage of responsive images usage. Why? They only let browsers adapt based on one thing: display pixel-density. A lot of times, though, our responsive images are on responsive layouts, and the image’s layout size is shrinking and stretching right along with the viewport. In those situations, the browser needs to make decisions based on two things: the pixel-density of the screen, and the layout size of the image. That’s where w descriptors and the sizes attribute come in ...

Use `src` for a fallback image file

Finally, the src attribute refers to a fallback image file in case the user’s browser does not support sizes or srcset attributes.

In which width should the fallback image file be? I cannot find any tip on this (please post a comment if you know any). My own reasoning concludes that the 1x screen version of the maximum width (624px in our example) is good enough. Here's why:

The legacy browser that does not support sizes or srcset is likely to come with either the 1x desktop screen or the 320px-wide 2x screens of iPhone 4 and iPhone 5.

The first 2x screen was released with iPhone 4 on June 24, 2010 (source: Wikipedia).
The iOS Safari first supported sizes and srcset with its version 9, released on September 16, 2015 (source: Can I Use?). That was when iPhone 6 was released (source: Wikipedia).
The screen width of iPhone 4 and iPhone 5 is 320px (source: Wikipedia).

Consequently, the fallback image file should cater to iPhone 4 and iPhone 5’s 320px wide screens, which require an image width of 640px at most.

If the maximum image width is less than 640px, you may want to use a 640px-wide version as a fallback. Otherwise, the maximum image width is sufficient.

How `sizes` and `srcset` work

If you need to brush up your understanding of how sizes and srcset attributes work in tandem, I recommend Portis (2018) and Google Developers (undated), both of which clearly explain how browsers choose which image file to use based on the information given by the sizes and srcset attributes.

Step 4: RespImageLint

The fourth step is to obtain the optimal values for sizes and srcset attributes with the help of RespImageLint, a bookmarklet developed by Martin Auswöger.

Coyier (2020) explains what RespImageLint does succinctly:

Martin Auswöger’s RespImageLint ... programmatically resizes the page a bunch and writes out a sizes attribute that describes the actual, observed width of the image over a wide range of viewport sizes. It’s computers, doing math, so it’s right. So, if you want a super-accurate sizes attribute, I’d recommend just putting a wrong one on at first, running this tool, and copying out the correct one.

Plus, RespImageLint gives us the recommended value for srcset.

Given these suggested values, we can now revise the HTML code written earlier in Step 3.

Step 5: Revise HTML code

In our example, RespImageLint suggests the following:

<img
  sizes="
    (max-width: 600px) calc(100vw - 70px), 
    (max-width: 766px) calc(100vw - 141.25px), 
    624px
  "
  srcset="
    image624.png   624w,
    image990.png   990w,
    image1248.png 1248w
  "
  src="image624.png"
/>

See the value of sizes. To get it right on your own, you have to go through the entire CSS style sheets back and forth. It’s best to rely on the automation provided by RespImageLint.

For srcset, RespImageLint suggests the image widths of not only 624px and 1248px but also 990px. This additional image targets 2x mobile screens in the range of widths between...(let me do the math for you)...382px and 565px. Without this image file, these mobile devices would have to download the 1248px image whose file size is way bigger than necessary.

Step 6: Image file conversion (Part II)

The last thing we need to do is to convert the original image file into those suggested by RespImageLint and match the file paths for the converted images with the ones specified in the HTML code written in Step 5.

Now you are done for responsive images!

But there are a few other things to do for images. For a reminder, see the list in Coyier (2021).

In particular, the above HTML code for <img> misses the alt attribute. I once spent the whole day to figure out how to write the alt text properly. See my blog post, Kudamatsu (2021), for what I have learned.

Changelog

Oct 1, 2023 (v1.1.0): Add a paragraph on resizing an image file with sips when the image's width is shorter than its height.

References

Archibald, Jake (2021) “Halve the size of images by optimising for high density displays”, jakearchibald.com, Jun 11, 2021.

Coyier, Chris (2020) “A Guide to the Responsive Images Syntax in HTML”, CSS-Tricks, May 26, 2020.

Coyier, Chris (2021) “Images are hard.”, CSS-Tricks, May 26, 2020.

Dachis, Adam (2012) “Batch Resize Images Quickly in the OS X Terminal”, Lifehacker, Nov 21, 2012.

Google Developers (undated) “Learn Images! — Descriptive syntaxes”, web.dev, undated.

Hempenius, Katie (2018) “Serve responsive images”, web.dev, Nov 5, 2018.

Kudamatsu, Masa (2021) “Mastering the art of alt text for images”, Dev Community, May 19, 2021.

O'Brien, Nolan (2019) “Capping image fidelity on ultra-high resolution devices”, Twitter Engineering, May 9, 2019.

Osmani, Addy (2021) “The Humble <img>` Element And Core Web Vitals”, Smashing Magazine, Apr 29, 2021.

Portis, Eric (2018) “w descriptors and sizes: Under the hood”, Observable, Mar 28, 2018.

Day 26: Integrating Google Maps search with a React app

Masa Kudamatsu — Sun, 02 Jul 2023 01:54:48 +0000

TL;DR

To create a user experience like this:

your React app needs to have a component coded as follows (warning: it is very long):

import {useContext, useRef, useState} from 'react';

// for using Google Maps's place ID set by another React component in the app (Section 2.2)
import {PlaceIdContext} from './PlaceIdContext'; 

// for managing UI states (Section 4.1)
import {useStateObject} from './useStateObject'; 

// for handling error responses (Section 2.4)
import FocusLock from 'react-focus-lock';

export const SearchedPlace = ({mapObject}) => {
  // Manage UI changes (Sections 2.2 and 4.1)
  const [state, setState] = useStateObject({ 
    status: 'closed',
    placeData: null,
  });
  const {status, placeData} = state;

  // Receive Google Maps's place ID from another React component in the app (Section 2.2)
  const [placeId, setPlaceId] = useContext(PlaceIdContext);

  // Prepare for dropping a marker to the searched place location (Section 3.3)
  const marker = useRef();

  // Make an API call after the component gets rendered (Section 2.2)
  useEffect(() => {
    if (!placeId) return; 
    setState({status: 'loading'});

    // Remove the marker from Google Maps for the previously searched place (Section 3.3)
    if (marker.current) { 
      marker.current.setMap(null);
    }          

    // Fetch place detail from Google Maps server (Section 2.1)
    const google = window.google;
    const service = new google.maps.places.PlacesService(mapObject);
    const request = {
      placeId: placeId,
      fields: [
        'formatted_address',
        'geometry',
        'name',
        'url',
      ],
    };
    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      // Handle successful responses (Section 2.3)
      if (placesServiceStatus === 'OK') {
        const searchedPlace = {
          address: place.formatted_address,
          coordinates: {
            lat: place.geometry.location.lat(),
            lng: place.geometry.location.lng(),
          },
          name: place.name,
          url: place.url,
        };
        // Customize the place marker with an SVG icon(Section 3.4)
        const searchedPlaceMarker = {
          filePath: '/searched-place-mark.svg',
          height: 37.876, 
          width: 39.644,
        }
        marker.current = new google.maps.Marker({
          icon: {
            url: searchedPlaceMarker.filePath,
            anchor: new google.maps.Point(  
              searchedPlaceMarker.width / 2,
              searchedPlaceMarker.height / 2,
            ),            
          },
          // For reopening the place detail popup by cliking the place mark (Section 4.4)
          optimized: false, 
          // Prepare to drop the marker to the searched place location (Section 3.1)
          position: searchedPlace.coordinates,
          title: searchedPlace.name,
        });
        // Allow the user to open the place detail popup by clicking the place mark (Section 4.4)
        marker.current.addListener('click', () => {
          setState({status: 'open'});
        });
        // Drop the marker to the searched place location (Section 3.1)
        marker.current.setMap(mapObject);
        // Snap the map to the area around the searched place (Section 3.2)
        mapObject.panTo(searchedPlace.coordinates);
        // Open the popup window for the detail of the searched place (Section 4.2)
        setState({
          status: 'open',
          placeData: searchedPlace
        });           
      // Handle error responses (Section 2.4)
      } else {
        console.error('Google Maps Place Details API call has failed.');
        setState({status: 'error'});
      }
    }
  }, [mapObject, placeId]);

  // For closing the place detail popup (Section 4.3)
  const closePlaceInfo = () => {
    setState({
      status: 'closed',
    });
  };
  // Close the popup by pressing the outside of it (Section 4.3)
  const dialogDiv = useRef(null); 
  useEffect(() => {
    const listener = event => {
      if (!dialogDiv.current || dialogDiv.current.contains(event.target)) {
        return;
      }
      closePlaceInfo();
    };
    document.addEventListener('pointerdown', listener);
    return () => {
      document.removeEventListener('pointerdown', listener);
    };
  }, [closePlaceInfo, dialogDiv]);
  // Close the popup by pressing the ESC key (Section 4.3)
  useEffect(() => {
    const closeByEsc = event => {
      if (event.key === 'Escape') {
        closePlaceInfo();
      }
    };
    if (status === 'open') {
      document.addEventListener('keydown', closeByEsc);
    } else {
      document.removeEventListener('keydown', closeByEsc);
    }
    return () => {
      document.removeEventListener('keydown', closeByEsc);
    };
  }, [closePlaceInfo, status]);

  // Render no HTML element by default (Section 2.2)
  if status === 'closed' {
    return null;
  // Render a loading message while making an API request (Section 2.2)
  } else if (status === 'loading') {
    return (
      <div>
        <p aria-live="polite" role="status">Getting more information about this place...</p>
      </div>
    )
  // Handle error responses (Section 2.4)
  } else if (status === 'error') {
    return (
      <FocusLock>
        <div role="alertdialog" aria-describedby="error-message" aria-labelledby="error-title">
          <h2 id="error-title">
            Unable to get place detail
          </h2>
          <p id="error-message">
            Google Maps server is currently down. <a
              href="https://status.cloud.google.com/maps-platform/products/i3CZYPyLB1zevsm2AV6M/history"
              rel="noreferrer"
              target="_blank"
            >
              Please check its status
            </a>, and try again once they fix the problem (usually within a few hours).
          </p>
          <button 
            data-autofocus
            onClick={() => setStatus('closed')} 
            type="button"
          >
            Got It
          </button>
        </div>
      </FocusLock> 
    )
  // Show the detail of the searched place in a popup window (Section 4.2)
  } else if (status === 'open') {
    return (
      <FocusLock>
        <div 
          aria-label={placeData.name}
          ref={dialogDiv} // For closing the popup by pressing the outside of it (Section 4.3)
          role="dialog" 
        >
          <h2>{placeData.name}</h2>
          <p>{placeData.address}</p>
          <button 
            data-autofocus 
            onClick={
              /* Click handler to save the searched place 
                 into the user's database in the server 
                 (to be specified in a future post of this blog series) 
              */
            }
            type="button"
          >
            Save
          </button>
          <a href={placeData.url} rel="noreferrer" target="_blank">More Info</a>
          {/* Close the popup by pressing the close button (Section 4.3) */}
          <button aria-label="Close the place detail" onClick={closePlaceInfo} type="button">
            {/* Insert the SVG code for close button icon */}
          </button>
        </div>
      </FocusLock>
    )
  }
}

where (1) the useStateObject custom hook is defined as

// ./useStateObject.js
// See Section 4.1
import {useReducer} from 'react';
const reducer = (state, action) => ({...state, ...action});
export const useStateObject = initialState => {
  const [state, setState] = useReducer(reducer, initialState);
  return [state, setState];
};

(2) the mapObject prop is passed from a parent component in which it is defined as

let mapObject;
mapObject = new google.maps.Map(document.getElementById("map"), {
  center: { lat: -34.397, lng: 150.644 }, // or any other location
  zoom: 8, // or any other zoom level
});

(3) PlaceIdContext is given by

// PlaceIdContext.js
// See Section 2.2
import {createContext, useState} from 'react';

export const PlaceIdContext = createContext();

export function PlaceIdProvider({...props}) {
  const [placeId, setPlaceId] = useState('');
  const value = [placeId, setPlaceId];
  return <PlaceIdContext.Provider value={value} {...props} />;
}

and (4) the placeId value is set with setPlaceId() in another component in charge of Google Maps autocomplete search (which triggers the re-rendering of the <SearchedPlace> component defined above).

1. Introduction

As far as I know, no one has written online how to integrate Google Maps search into a React app. This article fills this gap in the web dev online community.

The first half of Google Maps search, that is, displaying autocomplete suggestions in response to the user’s query, has already been discussed in Day 25 of this blog series.

The present article focuses the second half of it: what happens after the user selects one of the autocomplete search suggestions. It consists of three parts:

Call Google Maps API to retrieve the information of the place the user has selected (Section 2);
Drop a pin onto the map (Section 3);
Show the information of the searched place (Section 4).

If you are interested only in one of these three topics, skip to the relevant section of this article.

Why am I entitled to write this article? Because I’ve been developing a React app called My Ideal Map, which embeds Google Maps and allows the user to search for a place. The code written in this article is what I have discovered as a way to achieve the three above-mentioned aspects of user experience.

2. Making an API call to Google Maps server

Let’s first review a vanilla JS version of the code to fetch the data on a place from the Google Maps server (Section 2.1). Then, we adapt the code to React (Section 2.2). Finally, we discuss how to handle successful responses (Section 2.3) and error responses (Section 2.4).

2.1 Vanilla JavaScript version

We need the following code snippet to send a network request to the Googel Maps server for fetching the detail of a place whose Google Maps ID is provided as placeId:

const google = window.google;
const service = new google.maps.places.PlacesService(mapObject);
const request = {
  placeId: placeId,
  fields: [
    'formatted_address',
    'geometry',
    'name',
    'url',
  ],
};
service.getDetails(request, handleResponse);
function handleResponse(place, placesServiceStatus) {
  // to be completed in the rest of this article
}

which is adapted from the code shown in the Google Maps Platform documentation.

Let’s go through it line by line.

(1) Setting up

const google = window.google;

This line simply clarifies that we use a global object called google. By doing so, I follow the recommendation by Abramov (2017). If you don’t like it, you can do away with it.

const service = new google.maps.places.PlacesService(mapObject);

Here we set up the Places service of Google Maps API so that we can use its method called getDetails() to make an API call. Its argument, called mapObject here, refers to the object instantiated to embed Google Maps in our web app with the code like this:

mapObject = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 }, // or any other location
    zoom: 8, // or any other zoom level
  });

(For how to adapt this code to React, see Section 2 of Kudamatsu (2021), one of the popular articles I have written).

Consequently, we need to pass the mapObject value from the React component that renders a map. This topic was discussed in Section 1 of Day 12 of this blog series, where the mapObject was shared with the button to track the user’s location with Geolocation API. So I skip explaining how.

(2) Specifying which information to fetch
In the next set of lines:

const request = {
  placeId: placeId,
  fields: [
    'formatted_address',
    'geometry',
    'name',
    'url',
  ],
};

I first specify placeId, the Google Maps’s identifier for the place selected by the user. This value needs to be passed from a React component that renders autocomplete search (to be discussed in Section 2.2 below).

Then, for the fields property, I specify which information on the place to be fetched. Here I go for

The place’s name (name),
Its longitude and latitude (geometry) to drop a pin on the map,
Its street address (formatted_address) to make sure it is not a place of the same name in a different city, and
Its URL on Google Maps app (url) to allow the user to see more information on the place if they wish.

There are many other pieces of information on places up for grab from the Google Maps server. For the alphabetical list, see the Google Maps Platform documentation. Beware that some fields (categorised as “Contact Data” or “Atmosphere Data” incur additional charges (US$3 or $5 per 1,000 requests, respectively) to retrieve.

(3) Making an API call
The following line of code will send a request to the Google Maps server:

service.getDetails(request, handleResponse);

where the first argument, request, refers to the object we have just defined.

The second argument, handleResponse, refers to a callback function that will be executed once the response is received from the Google Maps server.

The callback function can be defined before this line of code. For code readability, however, I prefer defining it immediately after, by using the coding technique known as hoisting:

service.getDetails(request, handleResponse);
function handleResponse(place, placesServiceStatus) {
  // to be completed
}

where the two arguments, place and placesServiceStatus, refer to the JSON object for the detailed information of the place and the string value that indicates whether the request is made with success or with an error, respectively.

2.2 Adapting to React

Now we know how to make an API call to the Google Maps server. The challenge is how to execute it with React.

(1) Handling Place ID with React Context
One challenge is how to pass the value for placeId from another React component.

The placeId value is initially an empty string when the app is launched. Whenever the user chooses one of the autocomplete search suggestions in response to their query, its value changes to Google Maps’s place ID for the place chosen by the user.

To avoid prop drilling (see Dodds (2018) for what it is about), I use React Context to keep track of the placeId value.

First, create a context provider component:

// PlaceIdContext.js
import {createContext, useState} from 'react';

export const PlaceIdContext = createContext();

export function PlaceIdProvider({...props}) {
  const [placeId, setPlaceId] = useState('');
  const value = [placeId, setPlaceId];
  return <PlaceIdContext.Provider value={value} {...props} />;
}

which follows the practice recommended by Dodds (2021).

Then, wrap the entire app with <PlaceIdProvider> so that any React component in the app can consume placeId and/or setPlaceId via the useContext hook in the following way:

import {useContext} from 'react';
import {PlaceIdContext} from './PlaceIdContext';

export const AnyReactComponent = () => {
  const [placeId, setPlaceId] = useContext(PlaceIdContext);
}

(2) SearchBox component
Another challenge is how to trigger the running of the code for fetching data from the Google Maps server when the user clicks one of the autocomplete search suggestions.

An autocomplete search experience in the app is provided by a React component called SearchBox, as described in Day 25 of this blog series. Section 5.3 of that article explains how each of the autocomplete suggestions was rendered as an <li> element:

<li
  key={item.id}
  {...getItemProps({
    item,
    index
  })}
>

where item.id refers the place ID that we have been talking about: the identifer to be used to retrieve more information on the place from the Google Maps server. And the ...getItemProps({item, index}), a prop getter method from the Downshift library, adds all the attributes necessary for accessibility to the <li> element.

Now we add a click event handler to the <li> element so that the place ID will be used as a new value of the placeId state:

<li
  key={item.id}
  {...getItemProps({
    item,
    index,
    onClick: event => {    // ADDED
      setPlaceId(item.id); // ADDED
    }                      // ADDED
  })}
>

where setPlaceId() is imported via the useContext hook as described above.

This way, whenever the user clicks one of the autocomplete search suggestions, the placeId value gets updated, triggering the re-rendering of a component that uses placeId, that is, the component that makes a request to the Google Maps server. Which is what we are now going to code.

(3) Make an API call with useEffect hook
The final challenge is how to send a network request to the Google Maps server once the component gets re-rendered. The short answer is the useEffect hook (see React docs) with placeId as its dependency.

Let’s create a new React component called SearchedPlace which is in charge of rendering the place the user has selected among autocomplete search results:

import {useState} from 'react';
export const SearchedPlace = ({mapObject}) => {
  const [status, setStatus] = useState('closed');
  if status === 'closed' {
    return null;
  }
}

Its UI state is by default 'closed', in which case no HTML element is rendered. Its prop mapObject refers to the incidence of an embedded Google Maps as described in Section 2.1 above.

Now let’s add the code to make an API call:

import {useContext, useState} from 'react'; // REVISED
import {PlaceIdContext} from './PlaceIdContext'; // ADDED

export const SearchedPlace = ({mapObject}) => {
  const [status, setStatus] = useState('closed');

  // ADDED FROM HERE
  const [placeId, setPlaceId] = useContext(PlaceIdContext);
  useEffect(() => {
    const google = window.google;
    const service = new google.maps.places.PlacesService(mapObject);
    const request = {
      placeId: placeId,
      fields: [
        'formatted_address',
        'geometry',
        'name',
        'url',
      ],
    };
    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      // To be completed in the rest of this article
    }
  }, [mapObject, placeId]);
  // ADDED UNTIL HERE

  if status === 'closed' {
    return null;
  }
}

We need to wrap the entire code for making an API call inside the useEffect hook, which runs after the component gets rendered. This is because the google object does not exist until the component gets rendered.

However, the above code returns an error when placeId is an empty string. In such a case, we should skip running the code:

  ...
  useEffect(() => {
    if (!placeId) return; // ADDED
    const google = window.google;
    ...

(4) Loading message
Also, the network connection can be slow. To tell the user that the app is in the process of retrieving information from the Google Maps server, let’s update the UI once the useEffect hook starts running:

import {useContext, useState} from 'react'; 
import {PlaceIdContext} from './PlaceIdContext'; 

export const SearchedPlace = ({mapObject}) => {
  const [status, setStatus] = useState('closed');
  const [placeId, setPlaceId] = useContext(PlaceIdContext);
  useEffect(() => {
    if (!placeId) return;

    setStatus('loading'); // ADDED

    const google = window.google;
    const service = new google.maps.places.PlacesService(mapObject);

    // This part of the code is omitted for brevity

  }, [mapObject, placeId]);

  if status === 'closed' {
    return null;
  // ADDED FROM HERE
  } else if (status === 'loading') {
    return (
      <div>
        <p aria-live="polite" role="status">Getting more information about this place...</p>
      </div>
    )
  // ADDED UNTIL HERE
  }
}

I cannot find the definitive information on how to make loading messages accessible. But Bischoff (2016) suggests adding aria-live="polite" (and optionally role="status") to the element that contains the loading message text. I’ve tested this solution with VoiceOver, Mac OS’s screen reader. The loading message does get announced if it takes time to load, and the announcement gets interrupted as soon as the searched place information popup becomes visible.

However, Golcic (2020) argues (1) role="status" lacks cross-browser consistency in its implementation and (2) the element with aria-live has to be in the DOM on page load, rather than being added by JavaScript.

Let me know what you think if you are an accessibility expert.

By the way, the wrapping <div> is redundant, but it’s likely to be useful to style the box that surrounds the loading message text.

Now let’s move on to handle responses from the Google Maps server.

2.3 Handling successful responses

The Google Maps server returns two variables if the network request is successful. These two variables can be named in any way, but let’s call them placesServiceStatus and place.

(1) placesServiceStatus variable
This variable equals to OK if the network request has been successful. (For other values, see the Google Maps Platform documentation.)

To handle successful and error cases separately, therefore, we can code the callback function for the getDetails() method as follows:

    ...
    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      // ADDED FROM HERE
      if (placesServiceStatus === 'OK') {
        // to be completed
      } else {
        console.error('Google Maps Place Details API call has failed.');
      }
      // ADDED UNTIL HERE
    }
    ...

(2) place JSON object
In case of the successful request, the Google Maps server also returns the place JSON object, which in our case is something like this:

{
  "formatted_address" : "3-16 Sagatenryūji Susukinobabachō, Ukyo Ward, Kyoto, 616-8385, Japan",
  "geometry" : {
    "location" : {
      "lat" : 35.013867,
      "lng" : 135.6762773
    },
    "viewport" : {
      "northeast" : {
          "lat" : 35.0151522302915,
          "lng" : 135.6777188302915
      },
      "southwest" : {
          "lat" : 35.0124542697085,
          "lng" : 135.6750208697085
      }
    }
  },
  "name" : "Fukuda Art Museum",
  "url" : "https://maps.google.com/?cid=540503174389752899"
},

Note that the top-level properties correspond to the fields that we have specified in the getDetails() method:

...
const request = {
  placeId: placeId,
  fields: [
    'formatted_address',
    'geometry',
    'name',
    'url',
  ],
};
service.getDetails(request, handleResponse);
...

By specifying the callback function further, we can process this response to be used for dropping a pin on the map (see Section 3 below) and displaying the place information (see Section 4 below):

  ...
    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      if (placesServiceStatus === 'OK') {
        // ADDED FROM HERE
        const searchedPlace = {
          address: place.formatted_address,
          coordinates: {
            lat: place.geometry.location.lat(),
            lng: place.geometry.location.lng(),
          },
          name: place.name,
          url: place.url,
        };
        // ADDED UNTIL HERE
      } else {
        console.error('Google Maps Place Details API call has failed.');
      }
    }
  ...

2.4 Handling error responses

In the unlikely event of the Google Maps server returning an error response, we need to render an error message so that the user can learn what is going on.

First, let’s update the status variable to "error" if placesServiceStatus is not 'OK':

  ...
    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      if (placesServiceStatus === 'OK') {
        const searchedPlace = {
          address: place.formatted_address,
          coordinates: {
            lat: place.geometry.location.lat(),
            lng: place.geometry.location.lng(),
          },
          name: place.name,
          url: place.url,
        };
      } else {
        console.error('Google Maps Place Details API call has failed.');
        setStatus('error'); // ADDED
      }
    }
  ...

Then render an alertdialog div that shows an error message:

  ...
  if status === 'closed' {
    return null;
  } else if (status === 'loading') {
    return (
      <div>
        <p aria-live="polite" role="status">Getting more information about this place...</p>
      </div>
    )
  // ADDED FROM HERE
  } else if (status === 'error') {
    return (
      <div role="alertdialog" aria-describedby="error-message" aria-labelledby="error-title">
        <h2 id="error-title">
          Unable to get place detail
        </h2>
        <p id="error-message">
          Google Maps server is currently down. <a
            href="https://status.cloud.google.com/maps-platform/products/i3CZYPyLB1zevsm2AV6M/history"
            rel="noreferrer"
            target="_blank"
          >
            Please check its status
          </a>, and try again once they fix the problem (usually within a few hours).
        </p>
        <button 
          onClick={() => setStatus('closed')} 
          type="button"
        >
          Got It
        </button>
      </div>
    )
  // ADDED UNTIL HERE
  }
  ...

However, the above code is not enough for an HTML element with role="alertdialog" to announce its text content via the aria-labelledby and aria-describedby attributes. When it is opened, the alertdialog element needs to have its child interactive element auto-focused.

The above code is also insufficient because the error dialog needs to be modal, that is, the user must not be able to move the focus to other interactive elements outside the dialog.

To achieve this set of focus management for modal dialogs, my preferred solution is to use the react-focus-lock library:

import FocusLock from 'react-focus-lock'; // ADDED

...

  ...
  } else if (status === 'error') {
    return (
      <FocusLock> {/* ADDED */}
        <div role="alertdialog" aria-describedby="error-message" aria-labelledby="error-title">
          <h2 id="error-title">
            Unable to get place detail
          </h2>
          <p id="error-message">
            Google Maps server is currently down. <a
              href="https://status.cloud.google.com/maps-platform/products/i3CZYPyLB1zevsm2AV6M/history"
              rel="noreferrer"
              target="_blank"
            >
              Please check its status
            </a>, and try again once they fix the problem (usually within a few hours).
          </p>
          <button 
            data-autofocus // ADDED
            onClick={() => setStatus('closed')} 
            type="button"
          >
            Got It
          </button>
        </div>
      </FocusLock> {/* ADDED */}
    )
  // ADDED UNTIL HERE
  }
  ...

The entire alertdialog element is wrapped with the <FocusLock> component, to trap the focus within it. Plus, the data-autofocus attribute is added to the button element so that, thanks to the react-focus-lock library, the button will be auto-focused when the alertdialog element is rendered. Very simple, isn’t it? (The inert attribute is the future way to trap the focus (see Friedman 2022), but its browser support is slightly below 90% of global page views in June 2023 according to Can I Use?. So I would rather wait for a bit.)

Final note: the error message itself can surely be improved. In particular, it can change its text depending on the placesServiceStatus value. This is a topic that deserves one single article which I will write in the future.

3. Dropping a place mark on the map

Now we want to drop a marker on the embedded Google Maps to indicate the location of the place selected by the user among autocomplete search suggestions.

For this purpose, we need the following two pieces of data fetched from the Google Maps server with the code described in the previous section (where unnecessary data are temporarily commented out):

    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      if (placesServiceStatus === 'OK') {
        const searchedPlace = {
          // address: place.formatted_address,
          coordinates: {
            lat: place.geometry.location.lat(),
            lng: place.geometry.location.lng(),
          },
          name: place.name,
          // url: place.url,
        };
      } else {
        console.error('Google Maps Place Details API call has failed.');
        setStatus('error');
      }
    }

We therefore refer to the place’s name as searchedPlace.name and its location as searchedPlace.coordinates in this section. First we set the location to which the place mark is dropped (Section 3.1). Then we snap the map to the area round it (Section 3.2). Third, we handle the removal of the mark on the previously searched place (Section 3.3), which turns out to be a bit tricky with React. Finally, we customize the place mark with an SVG image (Section 3.4).

3.1 Specify the location

To drop a marker on embedded Google Maps, we use the following code snippet (see Google Maps Platform documentation for detail):

const marker = new google.maps.Marker({
  position: searchedPlace.coordinates,
  title: "searchedPlace.name,"
});
marker.setMap(mapObject);

where position sets the latitude and longitude of the place marker with an object whose properties are lat and lng, and title sets the text to pop up as a tooltip when the user hovers over the place mark.

Once the marker object is created, then we can execute its method setMap(mapObject) to render the place mark on the map, where mapObject refers to the instance of the embedded Google Maps (see Section 2.1 above).

3.2 Snap the map to the searched place

In addition to dropping a place mark onto the searched place, we need to snap the map to that location; otherwise the user would not be able to see the dropped marker.

To do so, we use the panTo() method of mapObject:

const marker = new google.maps.Marker({
  position: searchedPlace.coordinates,
  title: "searchedPlace.name,"
});
marker.setMap(mapObject);
mapObject.panTo(searchedPlace.coordinates); // ADDED

With this code, the map will show the searched place at the center of the screen.

There is another method called setCenter(), which does the same job. But panTo() animates the movement of the map more smoothly than setCenter() does (danhardman 2014).

3.3 Remove the marker for the previously searched place

If the user searches for a place only once, the above code works just fine. In reality, the app should allow the user to repeat their search. The code written so far does not erase the marker for the previously searched places.

With React, the removal of place markers requires the useRef hook, as explained in extensive detail in Section 3.2 of Day 12 of this blog post series.

The idea is that, instead of creating a constant variable marker inside the useEffect hook, generate a marker variable outside the useEffect hook with useRef. Then assign the instance of a marker object to marker.current each time the useEffect hook is run. If marker.current is already assigned, remove it from the map with marker.current.setMap(null):

import {useContext, useRef, useState} from 'react'; // REVISED
import {PlaceIdContext} from './PlaceIdContext'; 

export const SearchedPlace = ({mapObject}) => {
  const [status, setStatus] = useState('closed');
  const [placeId, setPlaceId] = useContext(PlaceIdContext);

  const marker = useRef(); // ADDED 

  useEffect(() => {
    if (!placeId) return;
    setStatus('loading');

    if (marker.current) {           // ADDED 
      marker.current.setMap(null);  // ADDED 
    }                               // ADDED 

    const google = window.google;
    const service = new google.maps.places.PlacesService(mapObject);
    const request = {
      placeId: placeId,
      fields: [
        'formatted_address',
        'geometry',
        'name',
        'url',
      ],
    };
    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      if (placesServiceStatus === 'OK') {
        const searchedPlace = {
          address: place.formatted_address,
          coordinates: {
            lat: place.geometry.location.lat(),
            lng: place.geometry.location.lng(),
          },
          name: place.name,
          url: place.url,
        };
        // REVISED FROM HERE
        marker.current = new google.maps.Marker({
          position: searchedPlace.coordinates,
          title: "searchedPlace.name,"
        });
        marker.current.setMap(mapObject);
        // REVISED UNTIL HERE
        mapObject.panTo(searchedPlace.coordinates);

      } else {
        console.error('Google Maps Place Details API call has failed.');
        setStatus('error');
      }
    }
  }, [mapObject, placeId]);

  // the rest of the code omitted for brevity

}

The reason behind this way of coding is that each time the SearchedPlace component gets re-rendered, the marker variable would otherwise be re-defined, preventing us from accessing the previous marker object to remove it from the map. The useRef will retain the value even when the component gets re-rendered.

3.4 Customize the marker

Finally, we customize the appearance of the place maker by using an SVG image. To do so, add icon property to the marker object, which needs to refer to an object with url property:

marker.current = new google.maps.Marker({
  // ADDED FROM HERE
  icon: {
    url: '/searched-place-mark.svg',
  },
  // ADDED UNTIL HERE
  position: searchedPlace.coordinates,
  title: "searchedPlace.name,"
});
marker.current.setMap(mapObject);

where we assume that the SVG image file, searched-place-mark.svg, is saved in the root directory of the website.

This is not enough, however. By default, Google Maps anchors an SVG image at its top-left corner. This means that, when the user zooms the map in and out, the place mark appears to move around over the map.

To fix this behavior, the SVG image needs to be anchored at its center. The SVG image contains its size information in its source code: the height and width attributes of the <svg> element. So we can copy and paste the height and width attribute values:

const searchedPlaceMarker = {
  height: 37.876,
  width: 39.644,
}

Then use these values to anchor the SVG image at its center:

icon: {
  url: '/searched-place-mark.svg',
  // ADDED FROM HERE
  anchor: new google.maps.Point(
    searchedPlaceMarker.width / 2,
    searchedPlaceMarker.height / 2,
  ),                                    
  // ADDED UNTIL HERE
},

where new google.maps.Point() is Google Maps's API function to specify a coordinate.

For more options for the icon property, see Google Maps Platform documentation.

The above code works, but to make the code more readable, let’s define the file path as the filePath property of the searchedPlaceMarker object:

const searchedPlaceMarker = {
  filePath: '/searched-place-mark.svg',   // ADDED
  height: 37.876, 
  width: 39.644,
}
marker.current = new google.maps.Marker({
  icon: {
    url: searchedPlaceMarker.filePath,  // REVISED
    anchor: new google.maps.Point(  
      searchedPlaceMarker.width / 2,
      searchedPlaceMarker.height / 2,
    ),            
  },
  position: searchedPlace.coordinates,
  title: "searchedPlace.name,"
});
marker.current.setMap(mapObject);
mapObject.panTo(searchedPlace.coordinates);

This way, in case we need to change the file path or replace the SVG image with another, we just need to revise the code for the searchedPlaceMarker object, with the implementation code intact.

4. Showing the place detail

Now we want to show the information of the place the user has selected among Google Maps autocomplete search suggestions.

We first discuss how to manage React states to update the UI (Section 4.1). Then we render the information of the searched place in a popup window (Section 4.2). Third, we allow the user to close the popup (Section 4.3). Finally, we also allow the user to reopen the popup by pressing the place mark on the embedded Google Maps (Section 4.4).

4.1 React state for place data

Since it is a change in UI to show the information of the place searched by the user, we need to re-render the React component to reflect the UI change. To do so, we need to update a React state for this component.

But re-rendering will lose the data fetched from the Google Maps server. One way to go about it is to add another state to hold the data:

...
export const SearchedPlace = ({mapObject}) => {
  ...
  const [status, setStatus] = useState('closed');
  const [placeData, setPlaceData] = useState(null); // ADDED
  ...

But whenever the placeData gets updated, we also want to update status so the place information will get revealed. So it’s best to group them together as an object:

...
export const SearchedPlace = ({mapObject}) => {
  ...
  const [state, setState] = useState({
    status: 'closed',
    placeData: null,
  });
  const {status, placeData} = state;
  ...

The second line destructures the state object so that our code written so far will not break due to the use of status. (This is a technique I learned from Epic React’s “React Hooks” module.)

However, with the useState hook, we always need to specify both property values whenever we update the state variable, like this:

setState({
  status: 'loading',
  placeData: null,
})

which requires an extra redundant line of code. Plus, in case I mistakenly write the code as follows

setState({
  status: 'loading',
})

the placeData property is gone, throwing an error where placeData is used.

My workaround is to create a custom hook that I call useStateObject, with the help of the useReducer hook (the generalized version of the useState hook):

// ./useStateObject.js
import {useReducer} from 'react';
const reducer = (state, action) => ({...state, ...action});
export const useStateObject = initialState => {
  const [state, setState] = useReducer(reducer, initialState);
  return [state, setState];
};

With this custom hook, if we execute

setState({status: 'loading'});

then the placeData property remains intact. (This is a technique I learned from Epic React’s “Advanced React Hooks” module.)

So the code written so far in the previous sections is refactored as follows:

import {useContext, useState} from 'react'; 
import {PlaceIdContext} from './PlaceIdContext'; 
import {useStateObject} from './useStateObject'; // ADDED

export const SearchedPlace = ({mapObject}) => {
  const [placeId, setPlaceId] = useContext(PlaceIdContext);
  // REVISED FROM HERE
  const [state, setState] = useStateObject({
    status: 'closed',                       
    placeData: null,                        
  });                                        
  const {status, placeData} = state;         
  // REVISED UNTIL HERE
  useEffect(() => {
    if (!placeId) return;
    setState({status: 'loading'}); // REVISED
    const google = window.google;
    const service = new google.maps.places.PlacesService(mapObject);
    const request = {
      placeId: placeId,
      fields: [
        'formatted_address',
        'geometry',
        'name',
        'url',
      ],
    };
    service.getDetails(request, handleResponse);
    function handleResponse(place, placesServiceStatus) {
      if (placesServiceStatus === 'OK') {

        // Omitted for brevity

      } else {
        console.error('Google Maps Place Details API call has failed.');
        setState({status: 'error'}); // REVISED
      }
    }
  }, [mapObject, placeId]);

  if status === 'closed' {
    return null;
  } else if (status === 'loading') {
    return (
      <div>
        <p aria-live="polite" role="status">Getting more information about this place...</p>
      </div>
    )
  } else if (status === 'error') {
    return (
      {/* Omitted for brevity */}
    )
  }
}

4.2 Render the place data in a popup window

Then, after fetching the place data from the Google Maps server and dropping a place mark onto its location, we update placeData with the fetched data:

service.getDetails(request, handleResponse);
function handleResponse(place, placesServiceStatus) {
  if (placesServiceStatus === 'OK') {
    const searchedPlace = {
      address: place.formatted_address,
      coordinates: {
        lat: place.geometry.location.lat(),
        lng: place.geometry.location.lng(),
      },
      name: place.name,
      url: place.url,
    };

    ... // omitted for brevity

    marker.current.setMap(mapObject);
    mapObject.panTo(searchedPlace.coordinates);
    // ADDED FROM HERE
    setState({                
      status: 'open',         
      placeData: searchedPlace
    });
    // ADDED UNTIL HERE
  } else {
    console.error('Google Maps Place Details API call has failed.');
    setState({status: 'error'});
  }
}

where I also update status to the string value of 'open', to switch the HTML element to render from the loading message to the place information popup.

Now the searchedPlace component gets re-rendered with a new value of placeData, which is used to render HTML:

...
  if status === 'closed' {
    return null;
  } else if (status === 'loading') {
    return (
      <div>
        <p aria-live="polite" role="status">Getting more information about this place...</p>
      </div>
    )
  } else if (status === 'error') {
    return (
      <FocusLock>
        <div role="alertdialog" aria-describedby="error-message" aria-labelledby="error-title">
          <h2 id="error-title">
            Unable to get place detail
          </h2>
          <p id="error-message">
            {/* Error message text omitted for brevity */}
          </p>
          <button 
            data-autofocus
            onClick={() => setStatus('closed')} 
            type="button"
          >
            Got It
          </button>
        </div>
      </FocusLock> 
    )
  {/* ADDED FROM HERE */}
  } else if (status === 'open') {
    return (
      <FocusLock>
        <div 
          aria-label={placeData.name}
          role="dialog" 
        >
          <h2>{placeData.name}</h2>
          <p>{placeData.address}</p>
          <button 
            data-autofocus 
            onClick={
              /* Click handler to save the searched place 
                 into the user's database in the server 
                 (to be specified in a future post of this blog series) 
              */
            }
            type="button"
          >
            Save
          </button>
          <a href={placeData.url} rel="noreferrer" target="_blank">More Info</a>
        </div>
      </FocusLock>
    )
  {/* ADDED UNTIL HERE */}
  }

Like what we have done with the error message dialog in Section 2.4 above, we wrap the entire dialog with the <FocusLock> component from the react-focus-lock library. This way the keyboard user cannot move the focus outside the popup by pressing the Tab key until they close the popup (which will be implemented below in Section 4.3). I believe that this is what the keyboard user expects when a popup shows up.

Also, again like what we have done with the error message dialog, the data-autofocus attribute, together with the <FocusLock> component, specifies the HTML element to be auto-focused when the popup is rendered. I add this attribute to the <button> element which will act as a button to save the searched place into the user’s database in the server (to be discussed in the future post of this blog series)

With <div role="dialog"> alongside the focus moving into its child element, the screen reader will announce the accessible name of the <div> element, which is the place name specified with aria-label. You may wonder why I don’t use aria-labelledby to refer to the <h2> element instead. I tried this approach, but MacOS screen reader, VoiceOver, does not announce the place name. According to Chapman (2022), this happens if the element referred to by the aria-labelledby attribute is not yet rendered when the <div role="dialog"> gets rendered. A work around, also suggested by Chapman (2022), is to use aria-label.

In addition, I add the link to Google Maps’s own page on the place that will open in a new tab, with target="_blank". Usually, forcing the user to open a link in a new tab is not a good UX practice (Coyier 2014, Roselli 2020). However, in this particular case, we do not want to kill the app’s active session by taking the user to the linked page on the same browser tab.

But whenever we use target="_blank", we should also use ref="noreferrer" so that the server of a linked page will not be able to see the current page URL which may contain privacy information such as the user’s name (MDN Contributors 2023).

4.3 Close the place detail popup

The user may want to close the place detail popup and to explore the area around it on the embedded Google Maps: maybe there are some places that the user has saved before.

My Ideal Map provides three ways to close the place detail popup:
(1) Press the close button at the top-right corner of the popup;
(2) Tap the area outside the popup; and
(3) Press the Esc key in the keyboard.

To implement these user experiences, let’s first define the function to close the popup.

const closePlaceInfo = () => {
  setState({
    status: 'closed',
  });
};

By setting the status property of the state object to be "closed", the SearchedPlace component gets rerendered to return null in the following part of the code:

...
  if status === 'closed' {
    return null;
  } else if (status === 'loading') {
...

So it removes the HTML elements that consititute the popup.

(1) Close button
Now we add a button to run this function to the place detail popup:

  ...
  } else if (status === 'open') {
    return (
      <div 
        aria-label={placeData.name}
        role="dialog" 
      >
        <h2>{placeData.name}</h2>
        <p>{placeData.address}</p>
        <a href={placeData.url} rel="noreferrer" target="_blank">More Info</a>
        <button aria-label="Close the place detail" onClick={closePlaceInfo} type="button">
          {/* Insert the SVG code for close button icon */}
        </button>
      </div>
    )
  }
  ...

For more detail on the button to close a popup, see Day 18 of this blog series.

(2) Outside the popup
To close the popup by pressing anywhere outside of it, I adapt the approach proposed by Akymenko (2019).

We first need to refer to the popup <div> with the useRef hook:

export const SearchedPlace = ({mapObject}) => {
  ...

  const dialogDiv = useRef(null); // ADDED

  if status === 'closed' {
    return null;
  } else if (status === 'loading') {
    {/* Omitted for brevity */}
  } else if (status === 'error') {
    {/* Omitted for brevity */}
  } else if (status === 'open') {
    return (
      <div 
        aria-label={placeData.name}
        ref={dialogDiv} // ADDED
        role="dialog" 
      >
        <h2>{placeData.name}</h2>
        <p>{placeData.address}</p>
        <a href={placeData.url} rel="noreferrer" target="_blank">More Info</a>
        <button aria-label="Close the place detail" onClick={closePlaceInfo} type="button">
          {/* Insert the SVG code for close button icon */}
        </button>
      </div>
    )
  }  
}

Then run an additional useEffect hook to attach the pointerdown event handler to the document object:

  const dialogDiv = useRef(null);
  // ADDED FROM HERE
  useEffect(() => {
    const listener = event => {
      if (!dialogDiv.current || dialogDiv.current.contains(event.target)) {
        return;
      }
      closePlaceInfo();
    };
    document.addEventListener('pointerdown', listener);
    return () => {
      document.removeEventListener('pointerdown', listener);
    };
  }, [closePlaceInfo, dialogDiv]);
  // ADDED UNTIL HERE

  if status === 'closed' {
    return null;
  } else if (status === 'loading') {
  ...

The crucial part in the above code is

dialogDiv.current.contains(event.target)

This returns true if the event.target (the HTLM element that receives the user’s interaction) refers to the dialogDiv itself or any of its child elements, that is, when the user clicks somewhere inside the popup. Otherwise, it returns false and thus the useEffect hook continues to run and execute closePlaceInfo() to close the popup.

And this event handler is attached to the pointerdown event of the document object, which means both the desktop user clicks anywhere in the app and the mobile user taps anywhere in the app.

To remove this event handler whenever the SearchedPlace component gets dismounted, we return the function to remove the event listener — the standard practice to use the useEffect hook (see React documentation).

(3) The ESC key
To close the popup by pressing the Esc key in the keyboard, we actually use the useEffect hook in a similar fashion:

  useEffect(() => {
    const closeByEsc = event => {
      if (event.key === 'Escape') {
        closePlaceInfo();
      }
    };
    if (status === 'open') {
      document.addEventListener('keydown', closeByEsc);
    } else {
      document.removeEventListener('keydown', closeByEsc);
    }
    return () => {
      document.removeEventListener('keydown', closeByEsc);
    };
  }, [closePlaceInfo, status]);

The event handler, closeByEsc, checks if the user presses the Esc key (i.e., if event.key === 'Escape' is true) and, if so, executes the closePlaceInfo function to close the popup. And this event handler will be attached to the document object if status==='open' is true, that is, when the popup is opened. It will be removed if status takes another value, that is, when the popup is closed. By having status as its dependency, this useEffect hook runs every time the status gets updated.

Since this event only concerns the keyboard user, we use keydown event, rather than pointerdown event.

4.4 Reopen the popup by pressing the place mark

The place detail popup can now be closed by the user. In case the user wants to see it again, we let them do so by clicking the place mark on the embedded Google Maps.

To add a click handler to the place mark, we revise the handleResponse callback function as follows:

service.getDetails(request, handleResponse);
function handleResponse(place, placesServiceStatus) {
  if (placesServiceStatus === 'OK') {
    const searchedPlace = {
      // Omitted for brevity
    };
    const searchedPlaceMarker = {
      // Omitted for brevity
    }
    marker.current = new google.maps.Marker({
      icon: {
        url: searchedPlaceMarker.filePath,
        anchor: new google.maps.Point(  
          searchedPlaceMarker.width / 2,
          searchedPlaceMarker.height / 2,
        ),            
      },
      optimized: false, // ADDED
      position: searchedPlace.coordinates,
      title: "searchedPlace.name,"
    });

    // ADDED FROM HERE
    marker.current.addListener('click', () => {
      setState({status: 'open'});
    });
    // ADDED UNTIL HERE    

    marker.current.setMap(mapObject);
    mapObject.panTo(searchedPlace.coordinates);
    setState({          
      status: 'open',    
      placeData: searchedPlace
    });
  } else {
    // Omitted for brevity
  }
}

The marker object has a method addListener() which attaches an event listener to the place mark.

By having an event listener attached, the place mark on embedded Google Maps becomes accessible: it is rendered as a <button> element focusable with the Tab key with the title property value used as its accessible name. For this purpose, however, there is one extra thing to do, according to the Google Maps Platform documentation: add optimized: false to the set of options to create a marker in the first place. By default, this option is true, which means a group of markers may be rendered as a single marker for performance (see Google Maps Platform documentation). We need to avoid this from happening.

Now style the popup as you wish. In my case, I style it like a cloud floating above city streets (see Day 19 of this blog series).

5. Final words

That’s all! What a long article needed to explain how to show a searched place on the Google Maps embedded in a React app...

No demo available...

I apologize for the lack of a demo of the code described in this article. This is because Google Maps charges me every time the user loads a map and fetches the data on places via the web app that embeds Google Maps.

References

Abramov, Dan (2017) “As mentioned in the user guide, you need to explicitly read any global variables from window...”, Stack Overflow, May 1, 2017.

Akymenko, Maks (2019) “Hamburger Menu with a Side of React Hooks and Styled Components”, CSS-Tricks, Sep 10, 2019.

Bischoff, Ashley (2016) “aria-live triggers screen readers when an element with aria-live (or text within an element with aria-live) is added or removed from the DOM...”, Stack Overflow, Jul 26, 2016.

Chapman, George (2022) “There's nothing wrong with the way you're using aria-labelledby, however it may be that the content of your modal (#modal-desc) is being added after the modal container (#modal)...”, Stack Overflow, Mar 28, 2022.

Coyier, Chris (2014) “When to use target=”_blank””, CSS-Tricks, Jan 15, 2014.

danhardman (2014) “According to the reference: panTo: Changes the center of the map to the given LatLng...”, Stack Overflow, Oct 31, 2014.

Dodds, Kent C. (2018) “Prop Drilling”, kentcdodds.com, May 21, 2018.

Dodds, Kent C. (2021) “How to use React Context effectively”, kentcdodds.com, Jun 5, 2021.

Friedman, Vitaly (2022) “A Complete Guide To Accessible Front-End Components”, Smashing Magazine, May 25, 2022.

Golcic, Hrvoje (2020) “Accessible way of notifying a screen reader about loading the dynamic Web page update (AJAX)”, Stack Exchange, Feb 28, 2020.

Kudamatsu, Masa (2021) “4 gotchas when setting up Google Maps API with Next.js and ESLint”, Dev Community, Feb 12, 2021.

MDN Contributors (2023) “Referer header: privacy and security concerns”, MDN Web Docs, Mar 2, 2023 (last updated).

Roselli, Adrian (2020) “Link Targets and 3.2.5”, adrianroselli.com, Feb 7, 2020.

Day 25: Adding Google Maps autocomplete search to a React app

Masa Kudamatsu — Fri, 24 Feb 2023 00:55:23 +0000

TL;DR

To create an user experience with Google Maps place search like this:
your React app needs the code as follows:

// Each comment refers to the section of this article 
// which explains the code block that follows.

import {useMemo, useState} from 'react';
import {useCombobox} from 'downshift';

export const SearchBox = () => {
  // Section 5.1: to update UI as search suggestion list or Google Maps server status changes
  const [searchResult, setSearchResult] = useState({
    autocompleteSuggestions: [],
    status: '',
  });
  // Section 2.2: to make an API call to Google Maps server
  const google = window.google;
  const service = new google.maps.places.AutocompleteService();
  // Section 3: to save money for using Google Maps autocomplete search
  const sessionToken = useMemo(
    () => new google.maps.places.AutocompleteSessionToken(),
    [google.maps.places.AutocompleteSessionToken],
  );
  // Section 5.4: to make autocomplete search accessible
  const {
    getInputProps,
    getItemProps,
    getMenuProps,
  } = useCombobox({
    items: searchResult.autocompleteSuggestions,
    onInputValueChange: ({inputValue}) => {
      // Section 6.1: remove search suggestions when the search term is deleted in search box
      if (inputValue === '') {
        setSearchResult({
          autocompleteSuggestions: [],
          status: '',                 
        });
        return;
      }
      // Section 4.1: make an API call to Google Maps server
      service.getPlacePredictions({
        input: inputValue,         
        sessionToken: sessionToken,
        }, handlePredictions       
      );   
      // Section 4.2: process the response from Google Maps server
      function handlePredictions(predictions, status) {
        if (status === "OK") {
          const autocompleteSuggestions = predictions.map((prediction) => {
            return {
              id: prediction.place_id,
              name: {
                string: prediction.structured_formatting.main_text,
                // Section 7.3: to highlight the search term in suggested place names
                length: prediction.structured_formatting.main_text_matched_substrings[0]['length'],
                offset: prediction.structured_formatting.main_text_matched_substrings[0]['offset'],
              },
              address: {
                string: prediction.structured_formatting.secondary_text,
                // Section 7.3: to highlight the search term in suggested place address
                length: prediction.structured_formatting.secondary_text_matched_substrings[0]['length'],
                offset: prediction.structured_formatting.secondary_text_matched_substrings[0]['offset'],
              },
            };
          });
          // Section 5.2: update UI with new search suggestions
          setSearchResult({
            autocompleteSuggestions: autocompleteSuggestions,
            status: 'OK',
          })
        } else {
          // Section 5.2: update UI with an error message
          setSearchResult({
            autocompleteSuggestions: [],
            status: status,             
          });
        }
      }
    }
  })
  // Section 5.4: render UI in an accessible way
  return (
    <>
      <input 
        type="search"
        {...getInputProps()}
      >
      <ul
        {...getMenuProps()}
      >
        { // Section 5.3: show search suggestions
          searchResult.autocompleteSuggestions.length > 0
          ? searchResult.autocompleteSuggestions.map((item, index) => {
              return (
                <li
                  key={item.id}
                  {...getItemProps({
                    item,
                    index
                  })}
                >
                  {/* Section 7.3: highlight the search term in search suggestions */}
                  <p dangerouslySetInnerHTML={{__html: boldUserText(item.name)}}>
                  <p dangerouslySetInnerHTML={{__html: boldUserText(item.address)}}>
                </li>
              );
            })
          : null
        }
      </ul>
      {/* Section 6.2: show error messages */} 
      <SearchErrorMessage status={searchResult.status} />
    </>
  ) 
};

where the boldUserText function and the SearchErrorMessage component is given as follows:

// Section 7.3: to highlight the search term in search suggestions
function boldUserText({ length, offset, string }) {
  if (length === 0 && offset === 0) {
    return string;
  }
  const userText = string.substring(offset, offset + length);
  const stringBefore = string.substring(0, offset);
  const stringAfter = string.substring(offset + length);
  return `${stringBefore}<b>${userText}</b>${stringAfter}`;
}

export const SearchErrorMessage = ({status}) => {
  // Section 6.2: switch error messages in response to Google Maps server status
  return status === '' || status === 'OK' ? null : (
    <div role="alert">
      {
        status === 'ZERO_RESULTS' || status === 'INVALID_REQUEST' || status === 'NOT_FOUND' ? (
          <p>
            No place is found on the map. Try another search term.
          </p>
        {/* Section 6.3: show an error message when server access is rejected */}
        ) : status === 'OVER_QUERY_LIMIT' || status === 'REQUEST_DENIED' ? (
          <p>
            My Ideal Map is currently unable to use Google Maps search. Please contact us so we can fix the problem.
          </p>
        {/* Section 6.4: show an error message when Google Maps server is not responding */}
        ) : (
          <p>
            Google Maps server is down. <a href="https://status.cloud.google.com/maps-platform/products/i3CZYPyLB1zevsm2AV6M/history" target="_blank" rel="noreferrer">Please check its status</a>, and try again once they fix the problem (usually within a few hours).
          </p>
        )
      }
    </div>
  )
}

Then style the <ul> and <li> elements with CSS as you wish.

1. Introduction

My Ideal Map, a web app I’m building with React, allows the user to save the places of their own interest on Google Maps with rich text note. For this purpose, the app needs to incorporate the search feature of Google Maps so that the user can first find each place of their interest before saving it.

The Places Library of Google Maps JavaScript API allows you to embed Google Maps search into your own web app.

As far as I know, there are only two articles on the web that explain how to incorporate the Places Library into React apps. Both Kassym (2020) and Imoh (2022) use the Autocomplete widget, which comes with the predefined user interface.

For more flexibility in UI design, however, we need to use the AutocompleteService class, which only fetches the JSON data of autocomplete search suggestions from the Google Maps server.

After quite a bit of trial and error, I have managed to incorporate Google Maps search into a React app with my own user interface (as shown in the GIF image above). Here’s how.

2. Setting up

2.1 Enabling the Place Library

The Place Library is not available to use by default. We need to enable it on Google Cloud Console.

How to do so is clearly explained in Google Maps Platform documentation.

Once enabled, the Place Library needs to be added to the list of APIs that your Google Maps API key can be used for.

How to do so is also clearly explained in Google Maps Platform documentation.

2.2 Loading the Places library

To embed Google Maps in a React app, we need the following code:

import {useEffect, useRef} from 'react';
import {Loader} from '@googlemaps/js-api-loader';
export function HomePage() {
  const googlemap = useRef(null);
  useEffect(() => {
    const loader = new Loader({
      apiKey: process.env.NEXT_PUBLIC_API_KEY,
      version: 'weekly',
    });
    let map;
    loader.load().then(() => {
      map = new google.maps.Map(googlemap.current, {
        center: {lat: -34.397, lng: 150.644}, // or anywhere you want to show on the map by defaul
        zoom: 8, // or any other zoom level
      });
    });
  });
  return (
    <div id="map" ref={googlemap} />
  );
}

where I use Next.js’s environment variable NEXT_PUBLIC_API_KEY to keep the API key secret (see my article, Kudamatsu (2021), for more detail).

To use the Places Library, we need to change the options for the Loader class as follows:

const loader = new Loader({
  apiKey: process.env.NEXT_PUBLIC_API_KEY,
  version: 'weekly',
  libraries: ['places'], // ADDED
});

Surprisingly, you cannot find this code snippet in Google Maps Platform documentation on the Places Library. I only found it in the GitHub repo for googlemaps/js-api-loader.

2.3 Instantiate AutocompleteService class

Now the Places Library is available as google.maps.places. For flexible UI design on autocomplete search, we need to use its AutocompleteService class:

const google = window.google;
const service = new google.maps.places.AutocompleteService();

where the first line of code is to silence ESLint, which will otherwise complain that google is used without being defined (see Abramov 2017) for detail). The second line of code comes from Google Maps Platform documentation.

3. Session tokens

3.1 How Google charges us for using autocomplete search

The autocomplete search of Google Maps is NOT free of charge. By default, each time the user enters a character to retrieve autocomplete suggestions, it costs 0.00283 US dollars (source: Google Maps Platform documentation). In addition, when the user clicks one of the autocomplete suggestions, it costs 0.017 US dollars (source: Google Maps Platform documentation).

But there is a cheaper price plan. If the request to the Google Maps server is sent with a session token, then, it will only cost 0.017 US dollars for the the whole process of autocomplete search: entering search words and choosing an autocomplete suggestion (source: Google Maps Platform documentation). If the user ends up not choosing any of autocomplete suggestions, it will also cost 0.017 US dollars (source: Google Maps Platform documentation).

To benefit from this price plan, a single session token needs to be sent to the server during the whole process of autocomplete search. And a new session token must be used for a new search; otherwise the default price plan (charged per character to enter) will be applied (source: Google Maps Platform documentation).

Consequently, we first need to generate a session token before sending the user's search text to the Google Maps server.

3.2 Generating session tokens for React apps

To generate a session token, Google Maps Platform documentation teaches us to code like this:

const sessionToken = new google.maps.places.AutocompleteSessionToken();

However, this line of code doesn’t really work with React apps. The search term needs to be managed as a React state so that the search box gets re-rendered each time the user enters a character in it. Consequently, whenever the user changes the search text, the whole code of the search box component gets executed, with a new session token generated and sent to the Google Maps server. This kills the whole idea of using a session token to save money.

To make sure the same session token will be sent to the server until the user finishes a search process, we need to use useMemo():

const sessionToken = useMemo(
  () => new google.maps.places.AutocompleteSessionToken(),
  [google.maps.places.AutocompleteSessionToken],
);

This way, even if the React component gets rerendered due to changes in the search term, the session token will remain the same.

On the other hand, when the search process is over, my React app dismounts the search box component. Consequently, when the user starts a new search process, a new search box component is rendered with a new session token issued by the above line of code. (If the search box needs to be shown all the time, a different solution is needed for which I don’t know what to do.)

4. Interacting with API

Now we’re ready to interact with the Google Maps server. First, we send the search term to the server (Section 4.1). Then, we process the response returned by the server (Section 4.2).

4.1 Making an API call

In a simple setting, a request for autocomplete search can be sent to the server with the following code (source: Google Maps Platform documentation):

service.getPlacePredictions(
  {
    input: 'pizza near Syd',
    sessionToken: sessionToken,
  },
  handlePredictions,
);

where

service is an instance of AutocompleteService class (see Section 2.3 above)
input specifies the search term entered by the user
sessionToken is the one generated with AutocompleteSessionToken() (see Section 3.2 above)
handlePredictions is a function to process autocomplete search results (to be defined below)

There are a set of optional parameters for the getPlacePredictions() method. Among them, location and radius can be set so that search suggestions will be biased towards a certain area such as the user’s city of residence (see Google Maps Platform documentation for detail).

I’m not sure whether I want this feature. If the user is planning a trip, biasing towards where they live is certainly not helpful. Allowing the user to change the location bias will just complicate the user experience of searching a place.

The AutocompleteService class has another function called getQueryPredictions(), which will retrieve not only autocomplete suggestions but also suggested search terms like “pizza in New York” when the user just enters “pizza in new” (source: Google Maps Platform docs).

For the purpose of My Ideal Map, this extra suggestion is unnecessary. The app is for those users who knows a place of their interest, not for those who rely on Google Maps to suggest where to visit.

4.2 Processing server responses

We now need to specify the handlePredictions function to process the autocomplete suggestion data returned from the Google Maps server.

Once we send a request by calling getPlacePredictions(), we will receive two sets of data, predictions and status. So the handlePredictions function should take these two variables as its arguments:

function handlePredictions(predictions, status) {}

The status variable indicates whether the API request is successful (see Google Maps Platform documentation). If successful, its value is "OK". So I code as follows:

function handlePredictions(predictions, status) {
  if (status === "OK") {
    // handle autocomplete suggestions
  } else {
    // handle error
  }
}

The predictions variable refers to an array of objects each of which contains an autocomplete suggestion. Here is an example of those objects (it’s one of my favorite museums in Kyoto):

{
  "description" : "Fukuda Art Museum, 3-16 Sagatenryuji Susukinobabacho, Ukyo Ward, Kyoto, Japan",
  "matched_substrings" : [
    {
        "length" : 8,
        "offset" : 0
    },
    {
        "length" : 33,
        "offset" : 19
    }
  ],
  "place_id" : "ChIJfwxa4v-pAWARQ-R4_cVAgAc",
  "reference" : "ChIJfwxa4v-pAWARQ-R4_cVAgAc",
  "structured_formatting" : {
    "main_text" : "Fukuda Art Museum",
    "main_text_matched_substrings" : [
        {
          "length" : 8,
          "offset" : 0
        }
    ],
    "secondary_text" : "3-16 Sagatenryuji Susukinobabacho, Ukyo Ward, Kyoto, Japan",
    "secondary_text_matched_substrings" : [
        {
          "length" : 33,
          "offset" : 0
        }
    ]
  },
  "terms" : [
    {
        "offset" : 0,
        "value" : "Fukuda Art Museum"
    },
    {
        "offset" : 19,
        "value" : "3-16 Sagatenryuji Susukinobabacho"
    },
    {
        "offset" : 54,
        "value" : "Ukyo Ward"
    },
    {
        "offset" : 65,
        "value" : "Kyoto"
    },
    {
        "offset" : 72,
        "value" : "Japan"
    }
  ],
  "types" : [ "museum", "point_of_interest", "establishment" ]
}

For the definition of each property, see Google Maps Platform documentation.

For the purpose of My Ideal Map, all I need is place_id and structured_formatting properties.

When the user selects one of the autocomplete suggestions, My Ideal Map makes another API call to the Google Maps server so that its location will be displayed on the map along with additional pieces of information on the place. To do so, we need place_id.

To select one of the autocomplete suggestions, the user needs to see the name of the place and its address (the address is crucial as there are the places with the same name in different cities). The structured_formatting property contains an object whose main_text and secondary_text properties provide the name and address, respectively, of the place.

Consequently, I transform the predictions array as follows:

function handlePredictions(predictions, status) {
  if (status === "OK") {
    // ADDED FROM HERE
    const autocompleteSuggestions = predictions.map((prediction) => {
      return {
        id: prediction.place_id,
        name: {
          string: prediction.structured_formatting.main_text,
        },
        address: {
          string: prediction.structured_formatting.secondary_text,
        },
      };
    });
    // ADDED UNTIL HERE
  } else {
    // handle error
  }
}

You might wonder why I use name.string and address.string, rather than name and address, to store the name and address of a place. Please be patient. I'll explain it in Section 7 below.

The autocompleteSuggestions array will then be used to render the list of suggested places in response to the user’s search text.

To do so, I use React’s state with the help of a library called Downshift.

5. Rendering autocomplete suggestions with React

5.1 Initializing the state

First, I create a state variable called searchResult with the useState hook of React:

const [searchResult, setSearchResult] = useState({
  autocompleteSuggestions: [],
  status: '',
});

This state variable is an object with two properties. One of them, autocompleteSuggestions, is to store the array of suggestions returned by Google Maps API. The other property, status, will store the status variable returned from Google Maps API.

The status property is needed as part of the React state so that I can update the UI with an error message when the Google Maps server returns a value of status other than "OK".

And I manage these two states as one object, rather than two separate state variables, because they get updated at the same time (you’ll see this in action shortly).

5.2 Updating the state

With setSearchResult to update the React state, the handlePredictions function is revised as follows:

function handlePredictions(predictions, status) {
  if (status === "OK") {
    const autocompleteSuggestions = predictions.map((prediction) => {
      return {
        id: prediction.place_id,
        name: {
          string: prediction.structured_formatting.main_text,
        },
        address: {
          string: prediction.structured_formatting.secondary_text,
        },
      };
    });
    // ADDED FROM HERE
    setSearchResult({
      autocompleteSuggestions: autocompleteSuggestions,
      status: 'OK',
    })
    // ADDED UNTIL HERE
  } else {
    // ADDED FROM HERE
    setSearchResult({
      autocompleteSuggestions: [],
      status: status,
    })
    // ADDED UNTIL HERE
  }
}

When search is successful (status==="OK"), the React state gets updated with the autocompleteSuggestions array and the string of "OK". Otherwise, it is updated with an empty array and the status variable. You’ll shortly see why this way of updating the React state is convenient.

5.3 Rendering autocomplete suggestions

With the array of autocomplete suggestions, saved as searchResult.autocompleteSuggestions, <li> elements can be rendered with React as follows:

searchResult.autocompleteSuggestions.length > 0
  ? searchResult.autocompleteSuggestions.map((item) => {
      return (
        <li key={item.id}>
          <p>{item.name.string}</p>
          <p>{item.address.string}</p>
        </li>
      );
    })
  : null

First, I check whether the array is empty by looking at its length property. If it’s 0 (which is the default value, that is, before the user types any character in the search box), I don’t render any <li> element. (This is why, in the previous subsection, I set searchResult.autocompleteSuggestions to be an empty array when status is not "OK": in such a case, we don’t want to render <li> elements).

Second, I use the place ID for the key prop, which is necessary for React to remember each <li> element across re-rendering (see Dodds 2017 for demo).

Third, I insert each of the place name and its address into the <p> element. These are not paragraphs, but I don’t see any other HTML elements more appropriate. The <address> element is for the contact information, not for addresses in general (see Section 4.3.10 of HTML Living Standard).

There remain two things still missing in the code built so far. First, we need to make an API call to the Google Maps server whenever the user changes the search term in the search box. Second, the whole user experience of autocomplete search needs to be accessible.

For implementing these two, I use a library called Downshift, which makes life a lot easier than coding from scratch (see Day 24 of this blog series for detail).

5.4 Using Downshift

First, import the useCombobox hook from the downshift NPM module:

import {useCombobox} from 'downshift';

Then, specify the array of autocomplete suggestions as the items option:

useCombobox({
  items: searchResult.autocompleteSuggestions,
})

The useCombobox hook returns what they call prop getters:

const {
  getInputProps,
  getItemProps,
  getMenuProps,
} = useCombobox({
  items: searchResult.autocompleteSuggestions,
})

We use these prop getters to (1) add ARIA attributes to <input>, <ul>, and <li> elements and (2) make these elements work in tandem to provide accessibility:

return (
  <>
    <input 
      type="search"
      {...getInputProps()}
    >
    <ul
      {...getMenuProps()}
    >
      {searchResult.autocompleteSuggestions.length > 0
        ? searchResult.autocompleteSuggestions.map((item, index) => {
            return (
              <li
                key={item.id}
                {...getItemProps({
                  item,
                  index
                })}
              >
                <p>{item.name.string}</p>
                <p>{item.address.string}</p>
              </li>
            );
          })
        : null
      }
    </ul>   
  </>
)

These prop getters return an object of HTML attributes, which is why we use the notations like {...getInputProps()}.

The getItemProps() requires as arguments both the array item (item) and its index (index). This is why we add index as the argument for a function specified in the .map() array method.

There are a few more things to code for using the useCombobox hook of Downshift, but I just refer you to Day 24 of this blog series (see Section 3).

Now it’s time to code for making an API call to the Google Maps server whenever the user types something in the search box. All we need to do is to specify as the useCombobox hook’s onInputValueChange option the series of functions to execute for making an API call (see Sections 4.1, 4.2 and 5.2 above):

const {
  getInputProps,
  getItemProps,
  getMenuProps,
} = useCombobox({
  items: searchResult.autocompleteSuggestions,
  // ADDED FROM HERE
  onInputValueChange: ({inputValue}) => {
    // Section 4.1
    service.getPlacePredictions({
      input: inputValue,         
      sessionToken: sessionToken,
      }, handlePredictions       
    );                     
    // Section 4.2      
    function handlePredictions(predictions, status) {
      if (status === "OK") {
        const autocompleteSuggestions = predictions.map((prediction) => {
          return {
            id: prediction.place_id,
            name: {
              string: prediction.structured_formatting.main_text,
            },
            address: {
              string: prediction.structured_formatting.secondary_text,
            },
          };
        });
        // Section 5.2
        setSearchResult({
          autocompleteSuggestions: autocompleteSuggestions,
          status: 'OK',
        })
      } else {
        // Section 5.2
        setSearchResult({
          autocompleteSuggestions: [],
          status: status,             
        });
      }
    }
  }
  // ADDED UNTIL HERE
})

Downshift assigns to the inputValue variable the text the user has entered into the search box. It is then used as the input parameter for the getPlacePredictions function so that the Google Maps server retrieves autocomplete suggestions in response to the user input.

In the code above, I use hoisting for handlePredictions. When a function is defined with the function keyword, it can be used before it is defined (MDN Contributors 2023). As far as I know, this way of coding is common in Python, but not in JavaScript. However, in this particular case where the getPlacePredictions function specifies a callback function as its argument, I believe it improves code readability: the functions are executed in the order of being written in the code.

5.5 Putting all the code together so far

With the code written so far, whenever the user types a character in the search box, the app renders the list of autocomplete suggestions. We still need to handle edge cases and to improve the user interface. But let's take stock by putting all the code together so far, with references to the relevant sections as comments:

import {useMemo, useState} from 'react';
import {useCombobox} from 'downshift';

export const SearchBox = () => {
  // Section 5.1
  const [searchResult, setSearchResult] = useState({
    autocompleteSuggestions: [],
    status: '',
  });
  // Section 2.2
  const google = window.google;
  const service = new google.maps.places.AutocompleteService();
  // Section 3
  const sessionToken = useMemo(
    () => new google.maps.places.AutocompleteSessionToken(),
    [google.maps.places.AutocompleteSessionToken],
  );
  // Section 5.4
  const {
    getInputProps,
    getItemProps,
    getMenuProps,
  } = useCombobox({
    items: searchResult.autocompleteSuggestions,
    onInputValueChange: ({inputValue}) => {
      // Section 4.1
      service.getPlacePredictions({
        input: inputValue,         
        sessionToken: sessionToken,
        }, handlePredictions       
      );   
      // Section 4.2
      function handlePredictions(predictions, status) {
        if (status === "OK") {
          const autocompleteSuggestions = predictions.map((prediction) => {
            return {
              id: prediction.place_id,
              name: {
                string: prediction.structured_formatting.main_text,
              },
              address: {
                string: prediction.structured_formatting.secondary_text,
              },
            };
          });
          // Section 5.2
          setSearchResult({
            autocompleteSuggestions: autocompleteSuggestions,
            status: 'OK',
          })
        } else {
          // Section 5.2
          setSearchResult({
            autocompleteSuggestions: [],
            status: status,             
          });
        }
      }
    }
  })
  // Section 5.4
  return (
    <>
      <input 
        type="search"
        {...getInputProps()}
      >
      <ul
        {...getMenuProps()}
      >
        { // Section 5.3 
          searchResult.autocompleteSuggestions.length > 0
          ? searchResult.autocompleteSuggestions.map((item, index) => {
              return (
                <li
                  key={item.id}
                  {...getItemProps({
                    item,
                    index
                  })}
                >
                  <p>{item.name.string}</p>
                  <p>{item.address.string}</p>
                </li>
              );
            })
          : null
        }
      </ul>
    </>
  ) 
};

With this code snippet, we can freely style the list of autocomplete suggestions like this:
A screenshot of My Ideal Map in development

where the search term is highlighted in bold with the additional set of code described in Section 7 below.

6. Handling edge cases

We need to handle four edge cases: (i) the user deletes the whole search term; (ii) no search result is returned; (iii) access to the Google Maps server is denied; (iv) the Google Maps server is down.

Let's look at each of these four edge cases.

6.1 Deleting the whole search term

The code snippet in Section 5.5 leaves the list of autocomplete suggestions visible when the user deletes the entire search term. This is because the React state isn’t reset when the search box field becomes empty.

To handle this case, we need to revise the useCombobox hook’s onInputValueChange prop, to reset the React state when inputValue is an empty string:

const {
  getInputProps,
  getItemProps,
  getMenuProps,
} = useCombobox({
  items: searchResult.autocompleteSuggestions,
  onInputValueChange: ({inputValue}) => {
    // ADDED FROM HERE
    if (inputValue === '') {
      setSearchResult({
        autocompleteSuggestions: [],
        status: '',                 
      });
      return;
    }
    // ADDED UNTIL HERE
    service.getPlacePredictions({
      input: inputValue,         
      sessionToken: sessionToken,
      }, handlePredictions       
    );   
    function handlePredictions(predictions, status) {
      // Omitted for brevity
    }
  }
});

6.2 No search result

The code snippet in Section 5.5 above does not give any message when there is no search result. The user is then unsure of whether there is no search result or the Google Maps server is not responding. That is not a great user experience.

First of all, what kind of message should I display in case of no search result?

Whitenton (2014) recommends:

Clearly explain that there are no matching results.
Offer starting points for moving forward.
Don't mock the user.

Food.com, mentioned by Whitenton (2014) as a good example, provides the following message for no search result:

Sorry, no results were found. ... Check your spelling. Try more general words. Try different words that mean the same thing.

That was back in 2014. Food.com today gives the following message for no search result:

OOPS! NO MATCHES. How about digging into some of our most popular stuff instead?

I guess I can go with a simple message like this:

No place is found on the map. Try another search term.

Now, how can we display this message in case of no search result?

When the Google Maps server returns no search result, the status variable takes the value of "ZERO_RESULTS" (see Google Maps Platform documentation).

Therefore, we can check the statement:

status === `ZERO_RESULTS`

and if it is true, render the following HTML element:

<div role="alert">
  <p>
    No place is found on the map. Try another search term.
  </p>
</div>

I use role="alert" so that the screen reader will read out the message when this <div> element is inserted into the DOM (see Whiting 2017 for how to use role="alert" properly).

To implement this behavior with React, I create a separate component named SearchErrorMessage which takes status as a prop:

export const SearchErrorMessage = ({status}) => {
  return status === '' || status === 'OK' ? null : (
    <div role="alert">
      {
        status === 'ZERO_RESULTS' ? (
          <p>
            No place is found on the map. Try another search term.
          </p>
        ) : null
      }
    </div>
  )
}

where it renders nothing when status is an empty string (the initial state) or "OK" (at least one search result is returned). Otherwise, it renders <div role="alert">, the inside of which the value of status is checked if it’s "ZERO_RESULTS". If so, the message for no search result is rendered as a <p> element. This way, we can include some link text in the message, if necessary.

When the status variable takes the string value of "INVALID_REQUEST" (this request is invalid) or "NOT_FOUND" (the place referenced was not found), what the user needs to do is to try another search term. So, even though it is not strictly about the "no search result" situation, I think we can use the same message.

So I add these cases to the above code:

export const SearchErrorMessage = ({status}) => {
  return status === '' || status === 'OK' ? null : (
    <div role="alert">
      {
        // REVISED FROM HERE
        status === 'ZERO_RESULTS' || status === 'INVALID_REQUEST' || status === 'NOT_FOUND' ? (
        // REVISED UNTIL HERE
          <p>
            No place is found on the map. Try another search term.
          </p>
        ) : null
      }
    </div>
  )
}

Then, import and use this component into the SearchBox component as follows:

return (
  <>
    <input 
      type="search"
      {...getInputProps()}
    >
    <ul
      {...getMenuProps()}
    >
      {/* Omitted for brevity */}
    </ul>
    <SearchErrorMessage status={searchResult.status} /> {/* ADDED */}
  </>
);

6.3 Server access is denied

If status is "OVER_QUERY_LIMIT" (The application has gone over its request quota) or "REQUEST_DENIED" (The application is not allowed to use the PlacesService), this is a situation where it is the fault of my app, My Ideal Map, rather than Google Maps.

So the appropriate message is to ask the user to contact me, something like this:

My Ideal Map is currently unable to use Google Maps search. Please contact us so we can fix the problem.

To show this message when appropriate, revise the SearchErrorMessage component as follows:

export const SearchErrorMessage = ({status}) => {
  return status === '' || status === 'OK' ? null : (
    <div role="alert">
      {
        status === 'ZERO_RESULTS' || status === 'INVALID_REQUEST' || status === 'NOT_FOUND' ? (
          <p>
            No place is found on the map. Try another search term.
          </p>
        {/* ADDED FROM HERE */}
        ) : status === 'OVER_QUERY_LIMIT' || status === 'REQUEST_DENIED' ? (
          <p>
            My Ideal Map is currently unable to use Google Maps search. Please contact us so we can fix the problem.
          </p>
        {/* ADDED UNTIL HERE */}
        ) : null
      }
    </div>
  )
}

I need to add a contact form to this message later in the process of making the app.

6.4 Google Maps server is down

The final edge case is when the Google Maps server is not responding to the API call. In this case, the status variable takes the string value of "UNKNOWN_ERROR".

Also, if someone hacks the Google Maps server, the status variable may take other values than the ones specified in the documentation.

So I revise the SearchErrorMessage component as follows:

export const SearchErrorMessage = ({status}) => {
  return status === '' || status === 'OK' ? null : (
    <div role="alert">
      {
        status === 'ZERO_RESULTS' || status === 'INVALID_REQUEST' || status === 'NOT_FOUND' ? (
          <p>
            No place is found on the map. Try another search term.
          </p>
        ) : status === 'OVER_QUERY_LIMIT' || status === 'REQUEST_DENIED' ? (
          <p>
            My Ideal Map is currently unable to use Google Maps search. Please contact us so we can fix the problem.
          </p>
        {/* REVISED FROM HERE */}
        ) : (
          <p>
            Google Maps server is down. <a href="https://status.cloud.google.com/maps-platform/products/i3CZYPyLB1zevsm2AV6M/history" target="_blank" rel="noreferrer">Please check its status</a>, and try again once they fix the problem (usually within a few hours).
          </p>
        )
        {/* REVISED UNTIL HERE */}
      }
    </div>
  )
}

where the link points to the Google Maps Platform page on incidents reported on Places API. Since it is inconvenient for the user to leave the app to visit an external website, clicking the link text will open the site in a new tab with target="_blank", which should always be coupled with rel="noreferrer" for security reasons (otherwise ESLint complains).

I do not check the statement status === "UNKNOWN_ERROR" in the above code because all the other cases are already handled in the code by the time the browser reaches these lines of code.

I can improve the exact phrase of the messages to appear in the four edge cases described above. I would be happy to hear you in a comment to this article if you have a better idea.

6.5 None of the suggestions is relevant

The last edge case is what I do not know how to handle.

The Google Maps server returns up to five search suggestions in response to the search term (see Google Maps Platform documentation). And there seems no way to increase the upper limit (see a StackOverflow discussion on this matter).

Consequently, none of the five suggestions may be what the user is searching for. The user is likely to expect to see more suggestions by scrolling down. But the Google Maps server doesn’t allow us to implement it in an app.

We could tell the user that we cannot show more than five suggestions, if the user doesn’t do anything for, say, three seconds after five search suggestions get displayed.

But that is an intrusive user experience. The user may find what they are looking for, but just get interrupted by a phone call or something. Showing a message in this case can confuse the user.

Any idea?

7. Styling autocomplete suggestion text

The code written so far will do a decent job to provide the user with the autocomplete search feature of Google Maps.

For an additional improvement of user experience, however, we can highlight the search term that appears in the autocomplete suggestions.

7.1 UI design considerations

Writing about UX design of search suggestions, Moran 2018 recommends visually differentiating those characters already typed by the user and those suggested by the app:

...each suggestion has two parts: the characters already typed by the user, and the characters suggested by the system to complete the query. It’s important to use different visual styles to show which characters fall into each category. You can use bolding, italics, color, or indenting to communicate the differences between these parts. Visual differentiation helps users understand why the suggestions are shown and scan the available options.

A thorny issue is which type of characters to highlight, the characters already typed by the user or those suggested by the system. The same article recommends the following:

If your suggested search feature only appends characters to the end of the user’s text to finish the query, then you should highlight the suggested characters. If, instead, your suggested search feature will suggest popular queries that contain the user’s text anywhere in the query, it’s best to highlight the user’s query.—Moran (2018)

Google Maps’s search falls into the second case: the user’s text is contained anywhere in a suggested place name.

So I want to highlight the user’s text.

7.2 What Google Maps API gives us

Google Maps API returns not only place names and addresses, but also

length: the number of characters of the user’s text included in a place name or address
offset: the number of characters in a place name or address that precede the user’s text

For example, imagine the user types arashiyama garden, which is 17 characters long (including a space).

One of the autocomplete suggestions will be Bread, Espresso & Arashiyama Garden (one of my favorite cafes in Kyoto). In this case, the user’s text starts after 18 characters (including spaces) of Bread, Espresso &.

So the length is 17, and the offset is 18.

In Section 4.2 above, I gave an example of the object of an autocomplete suggestion returned by Google Maps API. Let me give an excerpt of it:

"structured_formatting" : {
  "main_text" : "Fukuda Art Museum",
  "main_text_matched_substrings" : [
      {
        "length" : 8,
        "offset" : 0
      }
  ],
  "secondary_text" : "3-16 Sagatenryuji Susukinobabacho, Ukyo Ward, Kyoto, Japan",
  "secondary_text_matched_substrings" : [
      {
        "length" : 33,
        "offset" : 0
      }
  ]
},

The length and offset values are given in the main_text_matched_substrings and secondary_text_matched_substrings properties of the structured_formatting property for the place name and its address, respectively.

7.3 Implementation

To extract the length and offset values, let’s revise the handlePredictions function in Section 4.2 as follows:

function handlePredictions(predictions, status) {
  if (status === "OK") {
    const autocompleteSuggestions = predictions.map((prediction) => {
      return {
        id: prediction.place_id,
        name: {
          string: prediction.structured_formatting.main_text,
          // ADDED FROM HERE
          length: prediction.structured_formatting.main_text_matched_substrings[0]['length'],
          offset: prediction.structured_formatting.main_text_matched_substrings[0]['offset'],
          // ADDED UNTIL HERE
        },
        address: {
          string: prediction.structured_formatting.secondary_text,
          // ADDED FROM HERE
          length: prediction.structured_formatting.secondary_text_matched_substrings[0]['length'],
          offset: prediction.structured_formatting.secondary_text_matched_substrings[0]['offset'],
          // ADDED UNTIL HERE
        },
      };
    });
    setSearchResult({
      autocompleteSuggestions: autocompleteSuggestions,
      status: 'OK',
    })
  } else {
    setSearchResult({
      autocompleteSuggestions: [],
      status: status,             
    });
  }
}

Given that each autocomplete suggestion takes the form of an object with string, length, and offset properties, I create a custom function to bold the user’s text:

function boldUserText({ length, offset, string }) {
  if (length === 0 && offset === 0) {
    return string;
  }
  const userText = string.substring(offset, offset + length);
  const stringBefore = string.substring(0, offset);
  const stringAfter = string.substring(offset + length);
  return `${stringBefore}<b>${userText}</b>${stringAfter}`;
}

If both length and offset are 0, then there is no user’s text. So just return the original string. Otherwise, extract the user’s text, the text before, and the text after by using the .substring() string method of JavaScript along with the length and offset values. Finally, combine the three with the user’s text wrapped with the <b> tag. This is what boldUserText() returns.

The .substring() method works as follows. When it takes two arguments, a and b, it removes the first a characters, keeps the subsequent b characters, and drop the rest. When it takes only one argument, say, c, it removes the first c characters and keep the rest (see MDN Web Docs for detail).

I use <b> to bold user’s text. According to the HTML Living Standard:

The b element represents a span of text to which attention is being drawn for utilitarian purposes without conveying any extra importance and with no implication of an alternate voice or mood, such as key words in a document abstract, product names in a review, actionable words in interactive text-driven software, or an article lede.—HTML Living Standard, section 4.5.21

In our case, the bold text is meant to draw the user’s attention so that they will know which part of autocomplete suggestions includes the text they have entered in the search box. That’s exactly what the <b> element stands for.

It shouldn’t be <strong>, because:

The strong element represents strong importance, seriousness, or urgency for its contents.—HTML Living Standard, section 4.5.3

In our case, the bold text does not convey any extra significance.

Now, how should we use the boldUserText function to render HTML? Given that the returned value from this helper function is not string but JSX (i.e., containing HTML tags), we cannot code like this:

// DOES NOT WORK!
{
  searchResult.autocompleteSuggestions.length > 0
  ? searchResult.autocompleteSuggestions.map((item, index) => {
      return (
        <li
          key={item.id}
          {...getItemProps({
            item,
            index
          })}
        >
          <p>{boldUserText(item.name)}</p>
          <p>{boldUserText(item.address)}</p>
        </li>
      );
    })
  : null
}

Instead, we need to use the React's prop called dangerouslySetInnerHTML (see React docs):

{
  searchResult.autocompleteSuggestions.length > 0
    ? searchResult.autocompleteSuggestions.map((item, index) => {
      return (
        <li key={item.id} {...getItemProps({ item, index })}>
          <p dangerouslySetInnerHTML={{__html: boldUserText(item.name)}}>
          <p dangerouslySetInnerHTML={{__html: boldUserText(item.address)}}>
        </li>
      );
    });
}

Now each autocomplete suggestion highlights the search term that the user has entered in the search box!
The search term "fushim" is highlighted in bold (a screenshot of My Ideal Map in development)

As you see in the above screenshot, a few parts of the addresses are also highlighted even though they don’t contain the search term. This is Google Maps’s fault. The offset and length values do not necessarily reflect where the search term is included. It is a bug that I need to fix in the future, but not critical enough for a minimum viable product.

8. Why Demo is unavailable

I wish I could give you the link to the demo of the entire code described in this article. However, Google charges me for accessing to Google Maps API, as described in Section 3.1 above.

Sorry.

9. Next up

The next step is to show on the embedded Google Maps the place the user selects out of the autocomplete suggestions rendered in this article.

Here you go: Day 26 of this blog series

References

Dan Abramov (2017) “As mentioned in the user guide, you need to explicitly read any global variables from window...”, Stack Overflow, May 1, 2017.

Dodds, Kent C. (2017) “Use the key prop when Rendering a List with React”, The Beginner’s Guide to React V1, 2017.

Imoh, Chinedu. (2022) “Integrating Google Places Autocomplete API in a React App”, Progress Telerik Blogs, Jun 29, 2022.

Kassym, Gapur. (2020) “How to Use Google Place Autocomplete With React Without a Third-Party Library”, Better Programming, Feb 3, 2020.

Kudamatsu, Masa. (2021) “4 gotchas when setting up Google Maps API with Next.js and ESLint”, Web Dev Survey from Kyoto, Feb 12, 2021.

MDN Contributors. (2023) “Functions”, MDN Web Docs, Jan 31, 2023 (last updated).

Whitenton, Kathryn. (2014) “3 Guidelines for Search Engine "No Results" Pages”, Nielsen Norman Group, Jan 5, 2014.

Whiting, Jon. (2017) “To ARIA! The Cause of, and Solution to, All Our Accessibility Problems”, WebAIM, May 17, 2017.

Day 24: Making autocomplete search accessible for React apps with Downshift

Masa Kudamatsu — Tue, 07 Feb 2023 01:08:59 +0000

TL;DR

To equip your React app with accessible autocomplete search, use the useCombobox hook from the Downshift library. It makes web developers’ life a lot easier than coding from scratch. This article reviews the HTML code for accessible autocomplete search (Section 2) and then describes how we can use Downshift to generate it (Section 3).

The user experience this article aims to implement when the user (1) types "s", (2) presses the Down Arrow key five times, and (3) hits the Return key.

1. Introduction

My Ideal Map, a web app I’m building, relies on Google Maps’s autocomplete search: whenever the user types a character in the search box, the app suggests the list of place names that the user may be looking for.

And I want to implement the autocomplete search feature with accessibility in mind and by using React. Learning about how to make autocomplete search accessible, however, I find it daunting to code from scratch. So it is worth exploring the possibility of using an external library that is battle-tested enough to minimize the number of bugs.

Downshift, a library that I learned about while I was watching video tutorials from Epic React, fits the perfect bill. It does all the tedious jobs for accessibility behind the scene. Plus, it is easy to customize for my specific needs, with the customized code easy to maintain.

In this article, I explain how I use Downshift to equip my React app with accessible autocomplete search.

2. HTML for accessibility

Before getting into the detail of Downshift, let’s review what the HTML code should look like for accessible autocomplete search.

Browsing ARIA Authoring Practices Guide, I’ve figured out that the example entitled "Editable Combobox With List Autocomplete" is the closest to what we know as autocomplete search.

Here is what I have learned:

2.1 Default

Before the user enters text in a search box, the HTML code should be something like this:

<label for="cb1-input">
  Search a place on the map
</label>
<input
  aria-autocomplete="list"
  aria-controls="cb1-listbox"
  aria-expanded="false"
  id="cb1-input"
  role="combobox"
  type="search"
/>
<ul
  id="cb1-listbox"
  role="listbox"
  aria-label="Autocomplete suggestions"
>
</ul>

It is the standard practice to link up the <label> element’s for attribute with the <input> element’s id attribute (so the screen reader user can tell what the <input> element is for). And with the type="search" attribute, iOS and Android change the mobile keyboard’s Return key label into “go” and the magnifying glass icon, respectively (see Alex Holacheck’s little demo).

Specific to autocomplete search is the combination of role="combobox" and aria-autocomplete="list". These two attributes together tell the screen reader user that this search box (i.e., <input type="search"/>) will pop up the list of autocomplete suggestions once the user enters text in it.

But the screen reader user needs to know where the popup list is. The aria-controls attribute does this job, by referring to the id attribute of the popup list, typically the <ul> element as shown in this example.

The aria-expanded="false" tells the screen reader user that the popup list is currently hidden.

The <ul> element has the role="listbox" attribute, which tells the screen reader user that it serves as the popup list of autocomplete suggestions.

The ARIA Authoring Practices Guide isn’t explicit about whether the listbox element should be in the DOM by default or not. However, the Downshift’s documentation briefly mentions that it should for accessibility reasons. So I follow this advice.

2.2 Once search text is entered

Once the user enters text in the search box, the HTML code should change into somethinig like this:

<label for="cb1-input">
  Search a place on the map
</label>
<input 
  id="cb1-input"
  type="search"
  role="combobox"
  aria-autocomplete="list"
  aria-controls="cb1-listbox"
  aria-expanded="true"        // CHANGED! 
/> 
<ul
  id="cb1-listbox"
  role="listbox"
  aria-label="Autocomplete suggestions"
>
  { /* ADDED FROM HERE */}
  <li id="lb1" role="option">Suggestion 1</li>
  <li id="lb2" role="option">Suggestion 2</li>
  <li id="lb3" role="option">Suggestion 3</li>
  <li id="lb4" role="option">Suggestion 4</li>
  <li id="lb5" role="option">Suggestion 5</li>
  { /* ADDED UNTIL HERE */}
</ul>

The <input> element’s aria-expanded attribute turns into true, as the popup list of autocomplete suggestions is now shown.

The role="option" in each <li> element tells the screen reader user that it represents one of the autocomplete suggestions.

2.3 When the keyboard user selects an autocomplete suggestion

Now, suppose the keyboard user (which of course includes the screen reader user) selects “Suggestion 1” with the Down Arrow key. This should transform the HTML code into something like this:

<label for="cb1-input">
  Search a place on the map
</label>
<input
  id="cb1-input"
  type="search"
  role="combobox"
  aria-autocomplete="list"
  aria-controls="cb1-listbox"
  aria-expanded="true"
  aria-activedescendant="lb1"      // CHANGED!
/>
  <ul
    id="cb1-listbox"
    role="listbox"
    aria-label="Autocomplete suggestions"
  >
    <li id="lb1" role="option"
      aria-selected="true"         // CHANGED!
    >
      Suggestion 1
    </li>
    <li id="lb2" role="option">
      Suggestion 2
    </li>
    <li id="lb3" role="option">
      Suggestion 3
    </li>
    <li id="lb4" role="option">
      Suggestion 4
    </li>
    <li id="lb5" role="option">
      Suggestion 5
    </li>
  </ul>
</div>

The <input type="search"> now has an additional attribute aria-activedescendant, which refers to the id attribute of the selected <li> element.

The selected <li> element has an additional attribute aria-selected="true", to indicate that it is selected by the user.

By hitting the Return key, then, the selected item is chosen by the user.

2.4 Implementing with React

How can we implement with React the above-described changes of HTML code for autocomplete search? Doing it from scratch appears to be a daunting task.

Luckily, I’ve found a rescue: Downshift, a library written by Kent C Dodds and others for React apps.

3. Downshift

Downshift, by default, is designed to create the user experience where clicking the text field will reveal autocomplete suggestions. This behavior is ideal for the user to choose a country of residence from the predefined list, for example.

But it is slightly different from what I want to implement with the place search of Google Maps API. I want typing the first character of search text to reveal autocomplete suggestions.

So I need to tweak a bit the code snippet provided in Downshift’s documentation. Here’s how.

3.1 Setting up

Let’s first install the library with NPM: type the following in Terminal:

npm install downshift

For this article, I have installed Downshift v7.2.0. Its future versions may change what follows below.

Then, at the beginning of a React component file for the search box (let’s call it SearchBox), import the useCombobox hook:

import {useCombobox} from 'downshift';

export const SearchBox = () => {
};

3.2 Managing autocomplete suggestions as React state

Whenever the list of autocomplete suggestions changes, the UI also needs to change. This means that the array of autocomplete suggestions is best to be managed as a React state the change of which triggers the rerendering of a component and thus the updating of user interface:

import {useState} from 'react'; // ADDED
import {useCombobox} from 'downshift';

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]); // ADDED
}

3.3 `<input>` element markup

To implement the default HTML code for the <input> element as described in Section 2.1 above, we use the getInputProps method from the useCombobox hook:

import {useState} from 'react';
import {useCombobox} from 'downshift';

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]); 
  // ADDED FROM HERE
  const {getInputProps} = useCombobox({
    items: autocompleteSuggestions
  });
  return (
    <input {
      ...getInputProps()
    }>  
  );
  // ADDED UNTIL HERE
};

where the items option, required for the useCombobox hook to work, refers to the array of autocomplete suggestions. The getInputProps returns an object whose properties are the HTML attributes for the <input> element. Consequently, the above code renders the input element as follows:

<input
  aria-activedescendant=""
  aria-autocomplete="list"
  aria-controls="downshift-1-menu"
  aria-expanded="false"
  aria-labelledby="downshift-1-label"
  autocomplete="off"
  id="downshift-1-input"
  role="combobox"
  value=""
>

My React app requires a few more attributes to the search box. I can specify them as the options for getInputProps() as follows:

getInputProps({
  inputMode: "search",
  placeholder: "Enter place name or address",
  type: "search"
})

As described in Section 2.1 above, the type="search" attribute makes the iOS/Android mobile keyboard appropriate for a search box. The inputMode prop (see Oliff 2019 for detail) is a fallback when the mobile keyboard does not change as expected (which happened to me with Styled Components for some reason). And the placeholder attribute is handy to suggest what to enter.

Also, I want to add two more attributes to the <input> element. First, I want the search box to be auto-focused when it is opened. With React, the autoFocus prop does the job (see Johnson 2019; see also Day 20 of this blog series):

getInputProps({
  autoFocus: "true", // ADDED
  inputMode: "search",
  placeholder: "Enter place name or address",
  type: "search"
})

However, this will turn the aria-expanded attribute into true, because Downshift, by default, makes it change depending on whether the <input> element is focused or not.

Instead I want the aria-expanded to be true when the user enters any character into the search box, which in turn fills the array of autocompleteSuggestions from Google Maps API calls. So I want to check whether autocompleteSuggestions has any item in its array:

getInputProps({
  "aria-expanded": autocompleteSuggestions.length > 0, // ADDED
  autoFocus: "true", 
  inputMode: "search",
  placeholder: "Enter place name or address",
  type: "search"
})

This way, Downshift allows us to override the default attribute values that it adds.

The other attribute I want to add is aria-label. I have designed the search box with the magnifying glass icon in it, which plays a role of the label to sighted users (see Day 17 of this blog series). For the screen reader user, then, it is enough to label the search box with the aria-label attribute:

getInputProps({
  "aria-expanded": autocompleteSuggestions.length > 0,
  "aria-label": "Search for a place on the map", // ADDED
  autoFocus: "true", 
  inputMode: "search",
  placeholder: "Enter place name or address",
  type: "search"
})

However, Downshift, by default, assumes that there is a <label> element and uses aria-labelledby to refer to the id attribute of the <label> element. I don’t need it. So I override it with null:

getInputProps({
  "aria-expanded": autocompleteSuggestions.length > 0,
  "aria-label": "Search for a place on the map",
  "aria-labelledby": null, // ADDED
  autoFocus: "true", 
  inputMode: "search",
  placeholder: "Enter place name or address",
  type: "search"
})

What is great about Downshift is the ease with which we can customize its implementation. Plus, looking at the code clearly tells us what is customized.

Let’s move on to the <ul> element.

3.4 `<ul>` element markup

To make the <ul> element accessible as the list of autocomplete suggestions, we use getMenuProps() out of the useCombobox hook:

import {useState} from 'react';
import {useCombobox} from 'downshift';

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]); 
  const {
    getInputProps, 
    getMenuProps   // ADDED
  } = useCombobox({
    items: autocompleteSuggestions
  });
  return (
    <>
      <input {
        ...getInputProps({
          "aria-expanded": autocompleteSuggestions.length > 0,
          "aria-label": "Search for a place on the map",
          "aria-labelledby": null,
          autoFocus: "true", 
          inputMode: "search",
          placeholder: "Enter place name or address",
          type: "search"
        })
      }>
      {/* ADDED FROM HERE */}
      <ul
        {...getMenuProps()}
      >
      </ul>
      {/* ADDED UNTIL HERE */}
    </>
  )
};

which renders the <ul> element as follows:

<ul 
  id="downshift-1-menu"
  role="listbox"
  aria-labelledby="downshift-1-label"
></ul>

Remember that the id attribute value, "downshift-1-menu", is used for the aria-controls attribute of the <input> element (see Section 3.3. above).

The aria-labelledby attribute is redundant for my purpose, as there is no <label> element. So I make it null and add aria-label instead:

getMenuProps({
  'aria-label': "Autocomplete suggestions",
  'aria-labelledby': null,
})

That’s all for the default HTML code.

3.5 Showing autocomplete suggestions

For the ease of exposition, let me first mock autocomplete search with a function called mockAutocompleteSearch:

// utils/mockAutocompleteSearch.js
export function mockAutocompleteSearch(searchText) {
  if (searchText === 's') {
    return ["San Francisco", "Sapporo", "Seoul", "Singapore", "Stockholm"];
  } else {
    return [];
  }
}

If the argument is the string of "s", it returns the list of fives cities whose name begins with "s" that I have been to in the past. It is a stupid function, but it is sufficient to explain how Downshift works with any autocomplete search function that maps from the user’s input to the array of suggestions.

To run this function whenever the user enters text into the search box, we use the onInputValueChange option for the useCombobox hook:

import {useState} from 'react';
import {useCombobox} from 'downshift';
import {mockAutocompleteSearch} from '../utils/mockAutocompleteSearch.js'; // ADDED

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]);
  const {    
    getInputProps, 
    getMenuProps
  } = useCombobox({
    items: autocompleteSuggestions,
    // ADDED FROM HERE
    onInputValueChange: ({inputValue}) => {
      if (inputValue === '') {
        setAutocompleteSuggestions([]);
        return;
      }
      setAutocompleteSuggestions(mockAutocompleteSearch(inputValue));
    }
    // ADDED UNTIL HERE
  });
  return (
    // Omitted for brevity
  )
};

The inputValue refers to the text the user enters into the search box. If it’s empty, we set the autocompleteSuggestions array to be empty. Otherwise, we set the array to contain autocomplete suggestions returned by mockAutocompleteSearch().

We can then use the condition

autocompleteSuggestions.length > 0

to decide whether to show the list of autocomplete suggestions:

import {useState} from 'react';
import {useCombobox} from 'downshift';
import {mockAutocompleteSearch} from '../utils/mockAutocompleteSearch.js';

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]); 
  const {    
    getInputProps, 
    getMenuProps
  } = useCombobox({
    items: autocompleteSuggestions,
    onInputValueChange: ({inputValue}) => {
      if (inputValue === '') {
        setAutocompleteSuggestions([]);
        return;
      }
      setAutocompleteSuggestions(mockAutocompleteSearch(inputValue));
    }
  });
  return (
    <>
      {/* The search box is omitted for brevity */}
      <ul
        {...getMenuProps({
          'aria-label': "Autocomplete suggestions",
          'aria-labelledby': null,
        })}
      >
        {/* ADDED FROM HERE */}
        {autocompleteSuggestions.length > 0
          ? autocompleteSuggestions.map((suggestion, index) => {
              return (
                <li
                  key={`suggestion-${index}`}
                >
                  {suggestion}
                </li>
              );
            }) 
          : null}
        {/* ADDED UNTIL HERE */}
      </ul>
    </>
  )
};

The use of the map() array method is the standard practice for using React to render the list out of an array (see React Docs on Lists and Keys).

3.6 `<li>` element markup

Now, to add the relevant ARIA attributes to the <li> elements, we use getItemProps() out of the useCombobox hook:

import {useState} from 'react';
import {useCombobox} from 'downshift';
import {mockAutocompleteSearch} from '../utils/mockAutocompleteSearch.js';

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]); 
  const {    
    getInputProps,
    getItemProps,  // ADDED 
    getMenuProps
  } = useCombobox({
    items: autocompleteSuggestions,
    onInputValueChange: ({inputValue}) => {
      if (inputValue === '') {
        setAutocompleteSuggestions([]);
        return;
      }
      setAutocompleteSuggestions(mockAutocompleteSearch(inputValue));
    }
  });
  return (
    <>
      {/* The search box is omitted for brevity */}
      <ul
        {...getMenuProps({
          'aria-label': "Autocomplete suggestions",
          'aria-labelledby': null,
        })}
      >
        {autocompleteSuggestions.length > 0
          ? autocompleteSuggestions.map((suggestion, index) => {
              return (
                <li
                  key={`suggestion-${index}`}
                  // ADDED FROM HERE
                  {...getItemProps({
                    suggestion,
                    index
                  })}
                  // ADDED UNTIL HERE
                >
                  {suggestion}
                </li>
              );
            }) 
          : null}
      </ul>
    </>
  )
};

which will render <li> elements as follows:

<li 
  role="option"
  aria-selected="false"
  id="downshift-1-item-0"
  suggestion="San Francisco"
>
  San Francisco
</li>
<li 
  role="option"
  aria-selected="false"
  id="downshift-1-item-1"
  suggestion="Sapporo"
>
  Sapporo
</li>
<li 
  role="option"
  aria-selected="false"
  id="downshift-1-item-2"
  suggestion="Seoul"
>
  Seoul
</li>
<li
  role="option" 
  aria-selected="false"
  id="downshift-1-item-3"
  suggestion="Singapore"
>
  Singapore
</li>
<li
  role="option" 
  aria-selected="false"
  id="downshift-1-item-3"
  suggestion="Stockholm"
>
  Stockholm
</li>

I don’t know why Downshift adds the suggestion attribute...

3.7 When the user chooses one of the suggestions

The final step to comply with the ARIA Authorizing Practices Guide is to deal with the selection of an autocomplete suggestion.

Actually, with the code written so far, Downshift implements the changes of ARIA attributes in response to the keyboard user’s choice of an autocomplete suggestion. Pressing the Down Arrow key to select the first suggestion converts the HTML code into the following:

<input 
  aria-activedescendant="downshift-1-item-0" // CHANGED!
  aria-autocomplete="list"
  aria-controls="downshift-1-menu" 
  aria-expanded="true" 
  autocomplete="off" 
  id="downshift-1-input" 
  role="combobox" 
  aria-label="Search for a place on the map" 
  inputmode="search" 
  placeholder="Enter place name or address" 
  type="search" 
  value="s">
<ul 
  id="downshift-1-menu"
  role="listbox"
  aria-label="Autocomplete suggestions"
>
  <li 
    role="option" 
    aria-selected="true"    // CHANGED!
    id="downshift-1-item-0" 
    suggestion="San Francisco">
    San Francisco
  </li>
  <li 
    role="option"
    aria-selected="false"
    id="downshift-1-item-1"
    suggestion="Sapporo"
  >
    Sapporo
  </li>
  <li 
    role="option"
    aria-selected="false"
    id="downshift-1-item-2"
    suggestion="Seoul"
  >
    Seoul
  </li>
  <li
    role="option" 
    aria-selected="false"
    id="downshift-1-item-3"
    suggestion="Singapore"
  >
    Singapore
  </li>
  <li
    role="option" 
    aria-selected="false"
    id="downshift-1-item-3"
    suggestion="Stockholm"
  >
    Stockholm
  </li>
</ul>

Notice the aria-activedescendant attribute of the <input> element now points to the id attribute of the first <li> element, which in turn toggles its aria-selected attribute into "true".

However, sighted users won’t see anything as I haven’t styled any of the <li> elements in response to the keyboard user’s selection.

To do so, we use highlightedIndex out of the useCombobox hook:

import {useState} from 'react';
import {useCombobox} from 'downshift';
import {mockAutocompleteSearch} from '../utils/mockAutocompleteSearch.js';

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]); 
  const {    
    getInputProps,
    getItemProps,
    getMenuProps,
    highlightedIndex, // ADDED
  } = useCombobox({
    items: autocompleteSuggestions,
    onInputValueChange: ({inputValue}) => {
      // omitted for brevity
    },
  });
  return (
    <>
      {/* The search box is omitted for brevity */}
      <ul
        {...getMenuProps({
          'aria-label': "Autocomplete suggestions",
          'aria-labelledby': null,
        })}
      >
        {autocompleteSuggestions.length > 0
          ? autocompleteSuggestions.map((suggestion, index) => {
              return (
                <li
                  data-highlighted={index === highlightedIndex} // ADDED
                  key={`suggestion-${index}`}
                  {...getItemProps({
                    suggestion,
                    index
                  })}
                >
                  {suggestion}
                </li>
              );
            }) 
          : null}
      </ul>
    </>
  )
};

To check whether or not the keyboard user selects a particular <li> element with its position given by index, we can use the statement index === highlightedIndex, which is true when selected.

To style the selected <li> element, I use the data-highlighted attribute whose value corresponds to the evaluation of index === highlightedIndex. Then, in a CSS stylesheet, style it something like this:

li[data-highlighted="true"] {
  background-color: var(--highlighted);
}

where the color is defined somewhere else as a CSS variable called --highlighted.

This way, we can indicate which autocomplete suggestion is currently selected, like this:

3.8 When the user selects a suggestion by click

Finally, when the user selects one of the autocomplete suggestions by clicking it, we need to run a script to show the location of it on the map. This is simple: we can just add an onClick prop as an additional argument for getItemProps():

import {useState} from 'react';
import {useCombobox} from 'downshift';
import {mockAutocompleteSearch} from '../utils/mockAutocompleteSearch.js';

export const SearchBox = () => {
  const [autocompleteSuggestions, setAutocompleteSuggestions] = useState([]); 
  const {    
    getInputProps,
    getItemProps,
    getMenuProps,
    highlightedIndex,
  } = useCombobox({
    items: autocompleteSuggestions,
    onInputValueChange: ({inputValue}) => {
      // omitted for brevity
    },
  });
  return (
    <>
      {/* The search box is omitted for brevity */}
      <ul
        {...getMenuProps({
          'aria-label': "Autocomplete suggestions",
          'aria-labelledby': null,
        })}
      >
        {autocompleteSuggestions.length > 0
          ? autocompleteSuggestions.map((suggestion, index) => {
              return (
                <li
                  data-highlighted={index === highlightedIndex}
                  key={`suggestion-${index}`}
                  {...getItemProps({
                    suggestion,
                    index,
                    // ADDED FROM HERE
                    onClick: event => {
                      // Insert the code for showing the selected place on the map
                    },
                    // ADDED UNIL HERE
                  })}
                >
                  {suggestion}
                </li>
              );
            }) 
          : null}
      </ul>
    </>
  )
};

4. Demo

Here is the CodeSandbox demo for the entire code written in this article.

5. Next up

In the next post of this blog series, I will use the code written in this article but replace the mockAutocompleteSearch function with the one to make a request to Google Maps API so that I can obtain real autocomplete suggestions in response to the user's search text.

Watch this space!

Changelog

Oct 9, 2023 (v1.0.1): Fix typo in Section 1.

References

Holachek, Alex (undated) “Build a Better Mobile Input”, undated.

Johnson, Maisie (2019) “3 ways to autofocus an input in React that ALMOST always work!”, blog.maisie.ink, Oct 25, 2019.

Oliff, Christian (2019) “Everything You Ever Wanted to Know About inputmode”, CSS-Tricks, May 17, 2019.

Day 23: Animating the closing of a popup as if button ripple effect wipes it away

Masa Kudamatsu — Sun, 08 Jan 2023 08:43:33 +0000

TL;DR

A white popup with mix-blend-mode: lighten and color: black can be wiped away with its child whose background-color is currentColor.

Suppose you have the following DOM structure for a popup:

<div class="popup" data-closing='false'>
  <span class="ripple"></span>
</div>

where the data-closing attribute will turn true when the user presses the close button of the popup.

Then, the following CSS code

.popup[data-closing='true'] {
  background-color: white;
  color: black;
  mix-blend-mode: lighten;
}
.popup[data-closing='true'] .ripple {
  background-color: currentColor;
  animation: 300ms linear backwards expand 
}
@keyframes expand {
  from {
    transform: scale(0)
  }
  to {
    transform: scale(1)
  }
}

creates an impression that the popup is wiped away (as shown in the GIF below), because the span element is rendered with the background beneath the popup(!).

This article describes how I apply this technique to the popup for the web app I’m currently developing with React and Styled Components.

The animation this article will implement (a screen capture of the demo for this article)

1. Introduction

1.1 Problems

On Day 22 of this blog series, I animated the opening of a search box popup with the container transform pattern of Material Design. For closing the search box, then, Material Design guidelines would suggest the reversed version of the container transform pattern: the popup shrinks and morphs back into the button. Such animation reinforces the idea that closing the popup will not destory it but store it inside the container.

For My Ideal Map (the web app I’m building), however, a popup is likened to a cloud floating over the bird’s eye view of streets beneath (that is, the embedded Google Maps).

An embedded Google Maps overlaid with a cloud-like popup (a screenshot of the prototype version of My Ideal Map)

We never see clouds in the sky moving in one direction and then in the reversed direction. The reversed container transform animation would therefore break an illusion of the popup as a cloud.

I need another type of animation for closing the popup.

1.2 An inspirational UI design work

Searching for an inspiration, I stumbled upon a Dribbble work created by Rasmussen (2019). In his work, pressing the close button will erase a card from top-right to bottom-left:
(A screen capture of animation by Rasmussen (2019))

I think it is a clever UI design: it combines the animation of removing the card with the indication of the close button being pressed.

I immediately thought this animation could be useful to reinfoce the idea of a popup as a cloud. Pressing the top-right corner of a cloud would create the movement of air in the sky, blowing the cloud away.

1.3 Implementation with CSS

To implement this animation with CSS and JavaScript, Tudor (2021) proposes a clever technique.

First, for the black card (assuming its class selector is .card), set its color and mix-blend-mode properties as follows:

.card {
  color: #fff;
  mix-blend-mode: darken;
}

which turns text into “transparent”, revealing the background beneath the card. The darken value of mix-blend-mode picks the lowest RGB values among all the layers of HTML elements for each pixel. If the text color is #fff, that is, the brightest RGB values, the background color beneath the card will be picked as the lowest RGB values in all the pixels, with text turning“transparent” as a result.

Then, create a pseudo element of the card with its background property value equal to currentColor:

.class::after {
  background: currentColor;
  content: '';
  position: absolute;
    top: 0; right: 0; bottom: 0; left: 0;
}

which overlays the black card with a copy of the card that is filled with the background beneath the black card. In other words, the black card appears to be erased away(!). By scaling up this pseudo element from zero to its full size with animation, therefore, we can create a visual effect that appears like erasing the black card.

Tudor (2021), however, animates the clip-path property for scaling up the pseudo element. While Chromium’s browser developer team seems to be working hard to make the clip-path animation more performant (see Kravets 2021), it is still safe to animate either transform or opacity property for the best performance (see Chikuyonok 2016, for example). So we can instead animate the transform property to scale up the pseudo element.

1.4 Adaptations

Now, the animation by Rasmussen (2019) uses a rectangle to erase the card. There is no rectangle in nature, certainly not in the sky. To erase the cloud-like popup, therefore, something circular will look more natural.

Then I thought, how about erasing the popup with the button ripple effect, the ripple created after the pressing of the close button?

That’s what I’m going to implement below, by combining the CSS technique of Tudor (2021) with the button ripple effect by Cameron (2020).

2. Ripple

2.1 Rendering as a React component

Instead of using a pseudo element as in Tudor (2021), I will use a span element as a React component to erase the popup. This is because I need to specify the size and position of the ripple each time the user presses the close button. By rendering the ripple as a React component, we can set its size and position as the component’s prop values.

First, turn the span element into a circle and allow it to be positioned freely inside the parent element, with Styled Components:

// ./styled-components/SpanRipple.js
import styled from 'styled-components';

const shapeRipple = `
  border-radius: 50%;
`;
const positionRipple = `
  position: absolute;
`;
export const SpanRipple = styled.span`
  ${shapeRipple}
  ${positionRipple}
`;

Next, render this ripple as a React component. On Day 21 of this blog series, I defined the UI state as:

  const [ui, setUi] = useState({
    searchButton: 'open',
    searchBox: 'closed',
  });

When the search box was closing, the ui.searchBox value would change to 'closing' while the ui.searchButton value would turn to 'opening'. This was done with the click event handler:

const handleClickCloseButton = () => {
    setUi({
      searchButton: 'opening',
      searchBox: 'closing',
    });
  };

Consequently, I can render the ripple when the search box is closing, with the following JSX:

<DivSearchBackground
  data-closing={ui.searchBox === 'closing'}
>
  <CloseButton
    handleClick={handleClickCloseButton}
  />
  {ui.searchBox === 'closing' ? (
    <SpanRipple
      id="ripple"
    />
  ) : null}
</DivSearchBackground>

where DivSearchBackground is the div element styled as the cloud-like popup on Day 19, and CloseButton is the button element with the cross (x) icon as its label (see Day 18 for detail).

2.2 Styling dynamically

I need to style the ripple dynamically. For one thing, the ripple needs to be as large as the popup whose size can vary when the desktop user changes the browser window size (otherwise, the ripple will not erase the entire popup). For another, the ripple needs to start at the location where the user presses the button.

We can do this by editing the click event handler for the close button as follows:

const handleClickCloseButton = ({ 
  rippleDiameter,      // ADDED
  ripplePositionLeft,  // ADDED
  ripplePositionTop,   // ADDED
}) => {
  setUi({
    searchButton: 'opening',
    searchBox: 'closing',
    rippleDiameter,         // ADDED
    ripplePositionLeft,     // ADDED
    ripplePositionTop,      // ADDED
  });
};

The idea is that the CloseButton component will obtain the three values of rippleDiameter (the diameter of the ripple), ripplePositionLeft and ripplePositionTop (the x and y coordinates of the top-left corner of the ripple element, respectively) in response to the user’s click of the button. The handleClickCloseButton function, passed to the CloseButton component as a prop, will then be executed with these three values as its arguments. Then, it will update the UI state with the three values.

Then I use the UI state values to style the ripple dynamically:

<DivSearchBackground
  data-closing={ui.searchBox === 'closing'}
>
  <CloseButton
    handleClick={handleClickCloseButton}
  />
  {ui.searchBox === 'closing' ? (
    <SpanRipple
      id="ripple"
      style={{                       // ADDED
        height: ui.rippleDiameter,   // ADDED
        left: ui.ripplePositionLeft, // ADDED
        top: ui.ripplePositionTop,   // ADDED
        width: ui.rippleDiameter,    // ADDED
      }}                             // ADDED
    />
  ) : null}
  // ADDED UNTIL HERE
</DivSearchBackground>

When the UI state for the search box popup becomes closing, the SpanRipple styled component will be rendered with its height, left, top, and width CSS values supplied from the UI state values.

In the file for the CloseButton component, then, the handleClickCloseButton function is passed as the handleClick prop and will be executed inside the button click handler:

// ./components/CloseButton.js
export const CloseButton = ({handleClick}) => {
  const clickHandler = event => {

    // To be inserted here: the calculation of rippleDiameter, ripplePositionLeft, and ripplePositionTop

    handleClick({    
      rippleDiameter,
      ripplePositionLeft,
      ripplePositionTop
    });
  };
  return (
    <button
      onClick={clickHandler}
      type="button"
    >
      <!-- SVG code for cross mark (x) (omitted) -->
    </button>
  )
};

2.3 Calculating geometry

Now, let’s get into the detail of calculating the size and position of the ripple.

Inside the handler, I first retrieve the popup element which is the parent of the close button:

const clickHandler = event => {
  const popup = event.currentTarget.offsetParent; 
}

where event.currentTarget refers to the button element, the element to which the event handler is attached (if we use event.target instead, this will refer to the svg element that triggers the click event). And the offsetParent property of an HTML element] refers to the popup div element because its position property is set to be absolute (see Day 19 of this blog series.

I then retrieve the popup element’s geometry with the getBoundingClientRect() method:

const clickHandler = event => {
  const popup = event.currentTarget.offsetParent; 

  // ADDED FROM HERE
  const {
    left: popupLeft,
    top: popupTop,
    height: popupHeight,
    width: popupWidth,
  } = popup.getBoundingClientRect();
  // ADDED UNTIL HERE
}

where I use the destructuring assignment to simplify the code.

I want the ripple’s radius to be as large as the popup’s diagonal so that the ripple in its full size completely covers the popup rectangle:

const clickHandler = event => {
  const popup = event.currentTarget.offsetParent; 
  const {
    left: popupLeft,
    top: popupTop,
    height: popupHeight,
    width: popupWidth,
  } = popup.getBoundingClientRect();

  // ADDED FROM HERE
  const popupDiagonalLength = Math.sqrt(
    Math.pow(popupWidth, 2) + Math.pow(popupHeight, 2),
  );
  const rippleRadius = popupDiagonalLength;
  // ADDED UNTIL HERE
}

where I use the Pythagorean Theorem to obtain the length of a diagonal.

For positioning the ripple, we need the location of its center relative to the top-left corner of the popup (so we can use left and top CSS properties to position the ripple). The location of the user’s click relative to the top-left corner of the browser window is obtained with event.clientX and event.clientY (see Akar 2020 for visual explanation). So the ripple’s center coordinate relative to the top-left corner of the popup is obtained as follows:

const clickHandler = event => {
  const popup = event.currentTarget.offsetParent; 
  const {
    left: popupLeft,
    top: popupTop,
    height: popupHeight,
    width: popupWidth,
  } = popup.getBoundingClientRect();
  const popupDiagonalLength = Math.sqrt(
    Math.pow(popupWidth, 2) + Math.pow(popupHeight, 2),
  );
  const rippleRadius = popupDiagonalLength;

  // ADDED FROM HERE
  const rippleCenter = {
    x: event.clientX - popupLeft,
    y: event.clientY - popupTop,
  };
  // ADDED UNTIL HERE
}

Now we are ready to set the three arguments for the handleClick prop passed to the CloseButton component:

// ./components/CloseButton.js
const clickHandler = event => {
  const popup = event.currentTarget.offsetParent; 
  const {
    left: popupLeft,
    top: popupTop,
    height: popupHeight,
    width: popupWidth,
  } = popup.getBoundingClientRect();
  const popupDiagonalLength = Math.sqrt(
    Math.pow(popupWidth, 2) + Math.pow(popupHeight, 2),
  );
  const rippleRadius = popupDiagonalLength;
  const rippleCenter = {
    x: event.clientX - popupLeft,
    y: event.clientY - popupTop,
  };
  // REVISED FROM HERE
  handleClick({
    rippleDiameter: `${Math.round(rippleRadius * 2)}px`,
    ripplePositionLeft: `${Math.round(rippleCenter.x - rippleRadius)}px`,
    ripplePositionTop: `${Math.round(rippleCenter.y - rippleRadius)}px`,
  });
  // REVISED UNTIL HERE
};

where the ripplePositionLeft and ripplePositionTop are obtained by subtracting the ripple radius from the ripple center’s coordinate.

That’s all for sizing and locating the ripple to fully cover the popup.

2.4 Making the ripple “transparent”

Next, copy the image of the embedded Google Maps beneath the popup onto the ripple’s surface so that the animated ripple will appear like erasing the popup.
The ripple appears like erasing the popup (a screenshot of the demo for this article)

To do so, I revise the DivSearchBackground styled component as follows:

// ./styled-components/DivSearchBackground.js
const revealMapBeneath = `
  &[data-closing='true'] {
    color: black;
    mix-blend-mode: lighten;
  }
  &[data-closing='true'] [id="ripple"] {
    background-color: currentColor;
  }
`;

export const DivSearchBackground = styled.div`
  ...
  ${revealMapBeneath}
`;

This is different from Tudor (2021) does for erasing a black card:

color: #fff;
mix-blend-mode: darken;

But I have a white popup. The lighten value of mix-blend-mode does the opposite to darken: picking the highest RGB values for each pixel. By specifyiing the text color as black, then, the mix-blend-mode: lighten will pick the RGB values beneath the element, that is, the embedded Google Maps.

2.5 Animating the ripple

Finally, I set animation parameters so the ripple will expand from where the user presses the button into the area covering the entire popup.

As explained in Section 3 of Day 21 of this blog series, I find it easy to work with CSS animation if I put all the parameters together in one place as a Javascript object, with the help of Styled Component's keyframes function:

// ./utils/animation.js
import {keyframes} from 'styled-components';
export const animation = {
  openSearchBox: {
    // Code omitted for brevity (see Day 22 of this blog series)
  },
  closeSearchBox: {} // ADDED
};

The following parameters will scale the ripple from 0% to its full size for the duration of 300ms with the linear easing:

// ./utils/animation.js
import {keyframes} from 'styled-components';
export const animation = {
  openSearchBox: {
    // Code omitted for brevity
  },
  closeSearchBox: {
    // ADDED FROM HERE
    duration: '300ms',
    easing: 'linear',
    ripple: {
      scale: keyframes`
        from {
          transform: scale(0);
        }
        to {
          transform: scale(1);
        }
      `,
      fillMode: 'backwards'
    },
    // ADDED UNTIL HERE
  },
};

where the keyframes helper from Styled Components allows us to store the @keyframes at-rules as a JavaScript variable.

Then I update the SpanRipple styled component as follows:

// ./styled-components/SpanRipple.js
import styled, {css} from 'styled-components'; // REVISED
import {animation} from '../utils/animation'; // ADDED

const shapeRipple = `
  border-radius: 50%;f
`;
const positionRipple = `
  position: absolute;
`;

// ADDED FROM HERE
const animateRipple = css`
  animation-duration: ${animation.closeSearchBox.duration};
  animation-fill-mode: ${animation.closeSearchBox.ripple.fillMode};
  animation-name: ${animation.closeSearchBox.ripple.scale};
  animation-timing-function: ${animation.closeSearchBox.easing};
`;
// ADDED UNTIL HERE

export const SpanRipple = styled.span`
  ${shapeRipple}
  ${positionRipple}
  ${animateRipple} /* ADDED */
`;

By default, any HTML element has transform: scale(1). To avoid this from appearing before animation starts, the animation-fill-mode needs to be set as backwards.

For duration, I’ve settled with 300ms after trial and error. If duration is too short, it is not very noticeable for the popup to be erased by a ripple because animation is too quick. On the other hand, a duration longer than 300ms will prevent the user from moving on to next for too long. The duration of 300ms strikes the right balance between these two concerns.

For easing, I initially tried the decelerated easing used for opening the popup (see the section entitled “Easing” in Day 22 of this blog series). But this caused most of the animation to be too quick for the user to notice the ripple erasing the popup. Linear easing mitigates this problem.

3. Popup

The code that's been written so far will do most of the job. But there are a few other things to make animation neat, by styling the popup.

3.1 Containing the ripple inside the popup

First, I need to contain the ripple inside the popup, by applying overflow: hidden to the popup (that is, DivSearchBackground styled component):

// ./styled-components/DivSearchBackground.js

...

const containRippleWithin = `
  &[data-closing='true'] {
    overflow: hidden;
  }
`; //

export const DivSearchBackground = styled.div`
  ...
  ${revealMapBeneath}
  ${containRippleWithin} /* ADDED */
`;

Without this, the ripple will be overflown beyond the viewport, causing the scroll bars to appear and consequently the layout to shift temporarily.

3.2 Handling cross-browser inconsistency

The code now works beautifully with Safari and Firefox. With Chrome, however, the popup won’t be erased completely: the revealed Google Maps beneath the popup appears blurred until the animation is over.

Apparently, Chrome implements mix-blend-mode differently from Safari and Firefox, when background-filter is also used. On Day 19, I applied the glassmorphism technique to make the popup background appear like clouds. This technique involves the use of background-filter: blur(8px). When implementing mix-blend-mode, Chrome appears to incorporate the background-filter result into the calculation while Safari and Firefox seem to ignore it.

To minimize the impact of seeing the blurred image of Google Maps for Chrome users, therefore, I need to make the popup to fade out while being “erased” by the ripple:

// ./utils/animation.js
import {keyframes} from 'styled-components';
export const animation = {
  openSearchBox: {
    ...
  },
  closeSearchBox: {
    duration: '300ms',
    easing: 'linear',
    // ADDED FROM HERE
    popup: {
      opacity: keyframes`
        0% {
          opacity: 1;
        }
        100% {
          opacity: 0;
        }
      `,
      fillMode: 'forwards'
    },
    // ADDED UNTIL HERE
    ripple: {
      scale: keyframes`
        from {
          transform: scale(0);
        }
        to {
          transform: scale(1);
        }
      `,
      fillMode: 'backwards'
    },
  },
};

And update the DivSearchBackground styled component as follows:

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

// ADDED FROM HERE
const animateTransitionOut = css`
  &[data-closing='true'] {
    animation-duration: ${animation.closeSearchBox.duration};
    animation-fill-mode: ${animation.closeSearchBox.popup.fillMode};
    animation-name: ${animation.closeSearchBox.popup.opacity};
    animation-timing-function: ${animation.closeSearchBox.easing};
  }
`;
// ADDED UNTIL HERE

export const DivSearchBackground = styled.div`
  ...
  ${animateTransitionIn}
  ${animateTransitionOut} /* ADDED */
`;

Remember that DivSearchBackground is rendered with the following JSX:

<DivSearchBackground
  data-closing={ui.searchBox === 'closing'}
>
  ...
</DivSearchBackground>

So the [data-closing="true"] attribute selector only applies during the animation of closing the popup.

3.3 Handling the popup edges

So far so good as long as the popup is full-screen or the popup has no noticeable box shadow.

However, for aesthetic reasons, the cloud-like popup for My Ideal Map requires a white box shadow that imitates the edges of clouds (see the section entitled “Edge treatment” in Day 19 of this blog series).

Consequently, when the popup only occupies part of the screen, the ripple will not erase the box shadow of the popup. This is because the ripple is a child element of the popup that is styled with overflow: hidden (see Section 3.1 above).

To solve this issue, I need a wrapper div element that contains the box shadow of the popup. Then, render the ripple as a child of the wrapper element, rather than that of the popup, so that the ripple will cover not only the popup but also its box shadow.

More specifically, I first need to change the JSX code as follows:

<DivSearchBackground.Wrapper                // ADDED
  data-closing={ui.searchBox === 'closing'} // ADDED
>                                          {/* ADDED */}
  <DivSearchBackground
    data-closing={ui.searchBox === 'closing'}
  >
    <CloseButton
      handleClick={handleClickCloseButton}
    />
  </DivSearchBackground>                   {/* MOVED */}
  {ui.searchBox === 'closing' ? (
    <SpanRipple
      id="ripple"
      style={{
        height: ui.rippleDiameter,
        left: ui.ripplePositionLeft,
        top: ui.ripplePositionTop,
        width: ui.rippleDiameter,
      }}
    />
  ) : null}
</DivSearchBackground.Wrapper>             {/* ADDED */}

The wrapper is defined as DivSearchBackground.Wrapper in the file for DivSearchBackground:

// ./styled-components/DivSearchBackground.js
import styled, { css } from "styled-components";

...

export const DivSearchBackground = styled.div`
  /* Omitted for brevity */
`;

// ADDED FROM HERE
DivSearchBackground.Wrapper = styled.div`
  /* To be styled shortly */
`;
// ADDED UNTIL HERE

This way, the code itself conveys the idea that this wrapper is inseparable from the popup itself. Also, I don’t have to add another import statement: the following line of code

import {DivSearchBackground} from '../styled-components/DivSearchBackground';

will import the wrapper component as well.

Now, the wrapper component is styled as follows:

// ./styled-components/DivSearchBackground.js
import styled, { css } from "styled-components";

const placeOverMap = `
  position: absolute;
`;
const setOuterSize = `
  bottom: 10%;
  left: 10%;
  right: 10%;
  top: 10%;
`;
const revealMapBeneath = `
  &[data-closing='true'] {
    color: black;
    mix-blend-mode: lighten;
  }
  &[data-closing='true'] [id="ripple"] {
    background-color: currentColor;
  }
`;
const containRippleWithin = `
  overflow: hidden;
`;

export const DivSearchBackground = styled.div`
  /* Omitted for brevity */
`;

DivSearchBackground.Wrapper = styled.div`
  ${placeOverMap}         /* ADDED */
  ${setOuterSize}         /* ADDED */
  ${revealMapBeneath}     /* ADDED */
  ${containRippleWithin}  /* ADDED */
`;

Now the wrapper plays a role of making the ripple copy the image of the embedded Google Maps beneath the popup and containing the ripple inside.

Then, the popup itself is styled as follows:

// ./styled-components/DivSearchBackground.js
import styled, { css } from "styled-components";

...

const setBackground = `
  --blur-radius: 8px;
  background-color: var(--popup-background-color);
  -webkit-backdrop-filter: blur(var(--blur-radius));
  backdrop-filter: blur(var(--blur-radius));
  box-shadow: 0 0 var(--blur-radius) var(--blur-radius) var(--popup-background-color);

  /* The CSS code to support legacy browsers are omitted */
`;

// ADDED FROM HERE
const setInnerSize = `
  bottom: calc(var(--blur-radius) * 2);
  left: calc(var(--blur-radius) * 2);
  position: absolute;
  right: calc(var(--blur-radius) * 2);
  top: calc(var(--blur-radius) * 2);
`;
// ADDED UNTIL HERE

const animateTransitionIn = css`
  /* Omitted for brevity */
`;
const animateTransitionOut = css`
  &[data-closing="true"] {
    /* Omitted for brevity */
  }
`;

export const DivSearchBackground = styled.div`
  ${setBackground}
  ${setInnerSize}         /* ADDED */
  ${animateTransitionIn}
  ${animateTransitionOut}
`;

DivSearchBackground.Wrapper = styled.div`
  /* Omitted for brevity */
`;

The popup size is now set so that there will be 16px wide space between the wrapper’s (transparent) border and the the popup’s. It ensures that the entire box shadow (whose blur radius and spread radius of 8px each implies its width of 16px) is included inside the wrapper. (See my article Kudamatsu (2020) for how the blur radius and spread radius of box-shadow shapes the shadow length).

This way, the ripple will erase the entire popup including its blurry white edges.

4. Search button

To animate the reappearance of the button to open the search box popup, apply the keyframes to simply fade in:

// ./utils/animation.js
import {keyframes} from 'styled-components';
export const animation = {
  openSearchBox: {
    // omitted for brevity
  },
  closeSearchBox: {
    duration: '300ms',
    easing: 'linear',
    // ADDED FROM HERE
    button: {
      opacity: keyframes`
        0% {
          opacity: 0; 
        }
        100% {
          opacity: 1;
        }
      `,
      fillMode: 'backwards',
    },
    // ADDED UNTIL HERE
    popup: {
      // Omitted for brevity
    },
    ripple: {
      // Omitted for brevity
    }
  }
};

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionIn = css`
  animation-duration: ${animation.closeSearchBox.duration};
  animation-fill-mode: ${animation.closeSearchBox.button.fillMode};
  animation-name: ${animation.closeSearchBox.button.opacity};  
  animation-timing-function: ${animation.closeSearchBox.easing};

`;

export const ButtonCloud = styled.button`
  ...
  ${animateTransitionOut}
  ${animateTransitionIn} /* ADDED */
`;

5. Reduced motion preference

For uses who prefer the reduced motion mode, we simply fade out the popup and fade in the search button, removing the ripple effect.

Once the ripple effect is removed, however, the duration of 300ms is slightly too long. We shorten it to 250ms.

So we replace the duration parameter for the reduced motion preference:

// ./utils/animation.js
...
export const animation = {
  openSearchBox: {
    // omitted for brevity
  },
  closeSearchBox: {
    duration: '300ms',
    easing: 'linear',
    button: {
      // omitted for brevity
    },
    popup: {
      opacity: keyframes`
        0% {
          opacity: 1;
        }
        100% {
          opacity: 0;
        }
      `,
      fillMode: 'forwards'
    },
    ripple: {
      // omitted for brevity
    },
    // ADDED FROM HERE
    reducedMotion: {
      duration: '250ms',
    }
    // ADDED UNTIL HERE
  },
};

Accordingly, I revise the styled components as follows. For the ripple, I simply remove the animation and keep the ripple scaled to be zero so that the user will not see it at all:

// ./styled-components/SpanRipple.js
...
const animateRipple = css`
  animation-duration: ${animation.closeSearchBox.duration};
  animation-fill-mode: ${animation.closeSearchBox.ripple.fillMode};
  animation-name: ${animation.closeSearchBox.ripple.scale};
  animation-timing-function: ${animation.closeSearchBox.easing};
  /* ADDED FROM HERE */
  @media (prefers-reduced-motion: reduce) {
    animation-name: none;
    transform: scale(0);
  }
  /* ADDED UNTIL HERE */
`;
...

For the button to open the search box, I override the duration:

// ./styled-components/ButtonCloud.js
...
const animateTransitionIn = css`
  animation-duration: ${animation.closeSearchBox.duration};
  animation-fill-mode: ${animation.closeSearchBox.button.fillMode};
  animation-name: ${animation.closeSearchBox.button.opacity};  
  animation-timing-function: ${animation.closeSearchBox.easing};
  /* ADDED FROM HERE */
  @media (prefers-reduced-motion: reduce) {
    animation-duration: ${animation.closeSearchBox.reducedMotion.duration};
  }
  /* ADDED UNTIL HERE */
`;
...

The same applies to the popup:

// ./styled-components/DivSearchBackground.js
...
const animateTransitionOut = css`
  &[data-closing='true'] {
    animation-duration: ${animation.closeSearchBox.duration};
    animation-fill-mode: ${animation.closeSearchBox.popup.fillMode};
    animation-name: ${animation.closeSearchBox.popup.opacity};
    animation-timing-function: ${animation.closeSearchBox.easing};
    /* ADDED FROM HERE */
    @media (prefers-reduced-motion: reduce) {
      animation-duration: ${animation.closeSearchBox.reducedMotion.duration};
    }
    /* ADDED UNTIL HERE */
  }
`;
// ADDED UNTIL HERE
...

Demo

The entire code is available as the CodeSandbox demo for this article.

References

Akar, Soner (2020) “I don’t like and understand things, which can be explained visually, by words”, Stack Overflow, Aug 27, 2020.

Cameron, Bret (2020) “How to Recreate the Ripple Effect of Material Design Buttons”, CSS-Tricks, Oct 12, 2020.

Chikuyonok, Sergey (2016) “CSS GPU Animation: Doing It Right”, Smashing Magazine, Dec 9, 2016.

Kravets, Una (2021) “Updates in hardware-accelerated animation capabilities”, Chrome Developers, Feb 22, 2021.

Kudamatsu, Masa (2020) “CSS box shadow is not to create a shadow…”, Web Dev Survey from Kyoto, Jan 3, 2020.

Rasmussen, Daniel (2019) “Close Tiles”, dribbble, 2019.

Tudor, Ana (2021) “Close tiles”, CodePen, Feb 26, 2021.

Day 22: Using container transform pattern to animate the appearance of a search box

Masa Kudamatsu — Tue, 03 Jan 2023 03:25:15 +0000

TL;DR

This article describes a simple way of implementing Material Design’s container transform animation with animation and transform-origin CSS properties. More specifically, the opening of a search box by pressing the magnyfing glass button will be animated to create an impression that the button expands and morphs into a popup with the search box.

Here is the CodeSandbox demo for this blog post.

The animation this article will implement (screen-captured by the author)

Introduction

My Ideal Map, a web app I’m building to improve the UX of Google Maps, hides a search box by default, to allow the user to discover the saved places of their interest that would otherwise be hidden beneath the search box.

To search for a place, the user first needs to press the magnifying glass icon button to reveal a search box. And I want to animate this user interface transition with Material Design’s container transform pattern.

Below I describe how I implement it with CSS, after explaining the rationale behind the choice of the container transform pattern.

Why Container Transform?

There are three reasons why I go for the container transform pattern to animate the appearance of a search box.

Proximity

In discussing the magnifying glass icon button to open a search box, Sherwin (2014) recommends the following:

When users click on the search icon, display the text-entry field close to that icon. Placing it far away increases the interaction cost for the user by forcing them to find the box before they can start typing. It also goes against the Gestalt law of proximity to show related items far from each other.

The container transform pattern creates an impression that the incoming element comes out of the outgoing element, establishing “proximity” in a dynamic sense.

Parent-child relationship

Material Design guidelines recommend using the container transform pattern to reinforce the parent-child relationship between the outgoing and incoming elements.

A search box is not a brother or sister of the search button, certainly not unrelated to it. It is a parent-child relationship, and the container transform pattern conveys this relationship to the user.

Warmth

Feldman et al. (2022) report the results of their UX research on animated transitions. Participants were asked to use a food ordering app, tapping the thumbnail of a dish to see its detail and the button to order it.

Among eight animation patterns for the transition from the thumbnail to the detail view, the researchers found that a clear majority of users preferred the container transform pattern. Interestingly, many of them described it as “warm and inviting”.

The app I’m making, My Ideal Map, aims to evoke such nice feelings in the user’s mind. Its design concept is “Dye me in your hue from the sky”. It is about the personalization of Google Maps. It is about adding color to the otherwise bland canvas of Google Maps by dropping the place marks of the user’s own interest.

It is therefore desirable to enhance the warmth of user interface, with the container transform animation pattern.

Implementation with CSS

On Day 21 of this blog series, I wrote up the React code to animate transitions between the search button and the search box popup. Building on this code base, I can simply set CSS animation properties to implement the container transform pattern.

Fade-through variant

I apply the “fade through variant” of the container transform pattern from Material Design:

** (image source: Google (undated))**

As indicated in the above diagram, the duration of animation is 300ms. In the first 90ms, the outgoing elements fade out. In the remaining 210ms, the incoming elements fade in. At the same time, both elements scale up for the entire duration of animation.

This way, it creates an impression that a small container element, once pressed by the user, expands and turns into a large element with detailed information. Separating the fading-out of the outgoing elements from the fading-in of the incoming elements makes sure that the animation will not appear jarring with the overlaps of the two sets of elements.

Translating this logic into CSS code is a bit tricky. To organize how to specify animation parameters, I use Styled Components in the following manner.

Duration

Let’s first set the duration of the entire animation.

First, I create a JavaScript object in which all the animation parameters are defined in one place:

// ./utils/animation.js
export const animation = {
  openSearchBox: {
    duration: '300ms',
  },
};

where I define the duration for the entire animation for opening the search box as 300ms.

Then, I refer to this JavaScript object in the styled components for the search button (ButtonCloud) and the search box popup (DivSearchBackground):

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionOut = css`
  &[data-closing="true"] {
    animation-duration: ${animation.openSearchBox.duration};
  }
`;

export const ButtonCloud = styled.button`
  ${animateTransitionOut}
`;

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionIn = css`
  animation-duration: ${animation.openSearchBox.duration};
`;

export const DivSearchBackground = styled.div`
  ${animateTransitionIn}
`;

where I omit the code for static styling of these two components.

Below I’m going to add more code for CSS animation to these three files.

This way, I don’t have to go through both of the styled components to understand how the two elements coordinate to achieve the container transform animation. I just need to see the animation.js file.

Easing

For easing to be used for the container transform animation, Material Design guidelines specify “80% incoming, 40% outgoing”. According to the archived version of Material Design guidelines, this is achieved with the following CSS declaration:

animation-timing-function: cubic-bezier(0.4, 0.0, 0.2, 1);

This easing creates the impression of a machine. When we turn on a machine, it slowly starts up and then accelerates. When we turn it off, it decelerates before it completely stops.

For the web app I’m building, however, such a mechanical impression isn’t appropriate. Here is why.

The magnifying glass button is shaped like a cloud (see Day 7 of this blog series); the search box popup has the background of cloud-like texture (see Day 19 of this blog series); both of these design decisions are based on the likening of Google Maps as the view of a city from the sky.

Consequently, I want to imitate the movement of clouds, interacted with a human finger, rather than the one of machines.

So what kind of easing is appropriate?

It should be like the behavior of a ball thrown by a human. When a human throws a ball, the ball immediately moves at high speed. Then it gradually slows down until it completely stops. (I owe this metaphor to Liew (2017), who helped me understand how to choose the easing pattern for animation.)

I imagine if we were able to hit a cloud with our finger, the cloud would move away from the finger tip in a similar fashion: initially moves away at high speed and then gradually slows down.

In Material Design, this pattern of easing is called decelerated easing, achieved with the following CSS declaration (source: Material Design guidelines):

animation-timing-function: cubic-bezier(0.0, 0.0, 0.2, 1);

So in the JavaScript object that stores all the animation parameters, I add the following:

// ./utils/animation.js
import {keyframes} from 'styled-components';

export const animation = {
  openSearchBox: {
    duration: '300ms',
    easing: 'cubic-bezier(0.0, 0.0, 0.2, 1)', // ADDED
  },
};

And add the animation-timing-function properties to the two styled components:

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionOut = css`
  &[data-closing="true"] {
    animation-duration: ${animation.openSearchBox.duration};
    animation-timing-function: ${animation.openSearchBox.easing}; /* ADDED */
  }
`;

export const ButtonCloud = styled.button`
  ${animateTransitionOut}
`;

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionIn = css`
  animation-duration: ${animation.openSearchBox.duration};
  animation-timing-function: ${animation.openSearchBox.easing}; /* ADDED */
`;

export const DivSearchBackground = styled.div`
  ${animateTransitionIn}
`;

Using the common easing parameter, both the outgoing and incoming elements will be animated in a coordinated manner.

Opacity animation

Now, let’s work on the opacity part of the animation. According to the fade-through variant of the container transform pattern described earlier, the outgoing element disappears during the first 90ms. For this to be happening, I use keyframes to finish the animation at 30%, that is, 90ms divided by 300ms:

// ./utils/animation.js
import {keyframes} from 'styled-components'; // ADDED

export const animation = {
  open: {
    duration: '300ms',
    easing: 'cubic-bezier(0.0, 0.0, 0.2, 1)',
    // ADDED FROM HERE
    button: {
      opacity: keyframes`
        30%, /* mocking 90ms duration */
        100% {
          opacity: 0; 
        }
      `,
      fillMode: 'forwards',
    },
    // ADDED UNTIL HERE
  },
};

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionOut = css`
  &[data-closing="true"] {
    animation-duration: ${animation.openSearchBox.duration}; 
    animation-fill-mode: ${animation.openSearchBox.button.fillMode}; /* ADDED */
    animation-name: ${animation.openSearchBox.button.opacity}; /* ADDED */
    animation-timing-function: ${animation.openSearchBox.easing};
  }
`;

export const ButtonCloud = styled.button`
  ${animateTransitionOut}
`;

I set the value of animation-fill-mode to be forwards. Without this, as soon as animation is over, the opacity goes back to the default value of 1.

Before explaining why I don’t set animation-duration to be 90ms, let me first set the opacity animation for the search box popup:

// ./utils/animation.js
import {keyframes} from 'styled-components';

export const animation = {
  open: {
    duration: '300ms',
    easing: 'cubic-bezier(0.0, 0.0, 0.2, 1)',
    button: {
      opacity: keyframes`
        30%, /* mocking 90ms duration */
        100% {
          opacity: 0; 
        }
      `,
      fillMode: 'forwards',
    },
    // ADDED FROM HERE
    popup: {
      opacity: keyframes`
        0%,
        30% { /* mocking 90ms delay */
          opacity: 0;
        }
        100% {
          opacity: 1;
        }
      `,
      fillMode: 'backwards', 
    },
    // ADDED UNTIL HERE
  },
};

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionIn = css`
  animation-duration: ${animation.openSearchBox.duration};
  animation-fillMode: ${animation.openSearchBox.popup.fillMode}; /* ADDED */
  animation-name: ${animation.openSearchBox.popup.opacity}; /* ADDED */
  animation-timing-function: ${animation.openSearchBox.easing};
`;

export const DivSearchBackground = styled.div`
  ${animateTransitionIn}
`;

For the incoming element, its opacity animation should be delayed with 90ms. This delay is achieved by setting the opacity to be 0 until 30% of the duration.

This time, the value of animation-fill-mode must be backwards; otherwise the default opacity of 1 will apply at the beginning of the animation. For the incoming element’s animation to be delayed, this is essential.

Now, if I used animation-delay to delay the animation for the incoming element and specified animation-duration to be 90ms for the outgoing element, animation would slow down towards the end of the first 90ms and then suddenly speeds up after 90ms have passed because I have set the easing to be decelerated.

To control the speed of animation for both outgoing and incoming elements in a harmonious way, I've figured out that it is best to use keyframes to finish animation early for the outgoing element and to delay animation for the incoming element, along with the same duration and easing pattern for both elements.

Scaling

Now let’s turn to the scaling part of the animation.

To create an impression that the search button at the top-right corner of the screen morphs into the search box popup, the scaling animation needs to be anchored at the top right corner of elements. This is done with the transform-origin property:

transform-origin: "top right";

A footnote: instead of using transform-origin, a more proper implementation of the container transform animation is to use translateX() and translateY() CSS functions. See the CodePen by Ainalem (2021) for an example. In our case, however, I feel the transform-origin approach is good enough.

Armed with transform-origin, the following parameters will create a simple version of the container transform animation:

// ./utils/animation.js
import {keyframes} from 'styled-components';

export const animation = {
  open: {
    duration: '300ms',
    easing: 'cubic-bezier(0.0, 0.0, 0.2, 1)',   
    origin: 'top right', // ADDED
    button: {
      opacity: keyframes`
        30%, /* mocking 90ms duration */
        100% {
          opacity: 0; 
        }
      `,
      // ADDED FROM HERE
      scale: keyframes`
        100% {
          transform: scale(4);
        }
      `,
      // ADDED UNTIL HERE
      fillMode: 'forwards',
    },
    popup: {
      opacity: keyframes`
        0%,
        30% { /* mocking 90ms delay */
          opacity: 0;
        }
        100% {
          opacity: 1;
        }
      `,
      // ADDED FROM HERE
      scale: keyframes`
        0% {
          transform: scale(0);
        }
        100% {
          transform: scale(1);
        }
      `,
      // ADDED UNTIL HERE
      fillMode: 'backwards', 
    },
  },
};

While the search box popup scales up from zero to its full size, the search button scales up by four times by the end of the animation. With the value of four, the whole animation appears to be seamless (which I’ve found out after trial and error).

Now apply these parameter values to the two styled components:

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionOut = css`
  &[data-closing="true"] {
    animation-duration: ${animation.openSearchBox.duration};
    animation-fill-mode: ${animation.openSearchBox.button.fillMode};
    animation-name: 
      ${animation.openSearchBox.button.opacity}, 
      ${animation.openSearchBox.button.scale}; /* REVISED */
    animation-timing-function: ${animation.openSearchBox.easing};
    transform-origin: ${animation.openSearchBox.origin}; /* ADDED */
  }
`;

export const ButtonCloud = styled.button`
  ${animateTransitionOut}
`;

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionIn = css`
  animation-duration: ${animation.openSearchBox.duration};
  animation-fillMode: ${animation.openSearchBox.popup.fillMode}; 
  animation-name: 
    ${animation.openSearchBox.popup.opacity}, 
    ${animation.openSearchBox.popup.scale}; /* REVISED */
  animation-timing-function: ${animation.openSearchBox.easing};
  transform-origin: ${animation.openSearchBox.origin}; /* ADDED */
`;

export const DivSearchBackground = styled.div`
  ${animateTransitionIn}
`;

Reduced motion preference

Finally, to cater to those users who have configured their OS in the reduced motion mode (see Steiner 2019 for a good introduction), I remove the scaling animation by overriding the animation-name property values. I also simplify the opacity animation: there is no longer necessary to delay the incoming element appearance or to finish early the outgoing element disappearance.

// ./utils/animation.js
import { keyframes } from "styled-components";
export const animation = {
  openSearchBox: {
    duration: "300ms",
    easing: "cubic-bezier(0.0, 0.0, 0.2, 1)", 
    origin: "top right",
    button: {
      // Omitted for brevity
    },
    popup: {
      // Omitted for brevity
    },
    // ADDED FROM HERE
    reducedMotion: {
      button: {
        opacity: keyframes`
          0% {
            opacity: 1;
          }
          100% {
            opacity: 0;
          }
        `
      },
      popup: {
        opacity: keyframes`
          0% {
            opacity: 0;
          }
          100% {
            opacity: 1;
          }
        `
      }
    },
    // ADDED UNTIL HERE
  },
};

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionOut = css`
  &[data-closing="true"] {
    animation-duration: ${animation.openSearchBox.duration};
    animation-fill-mode: ${animation.openSearchBox.button.fillMode};
    animation-name: ${animation.openSearchBox.button.opacity}, ${animation.openSearchBox.button.scale};
    animation-timing-function: ${animation.openSearchBox.easing}; 
    transform-origin: ${animation.openSearchBox.origin};
    /* ADDED FROM HERE */
    @media (prefers-reduced-motion: reduce) {
      animation-name: ${animation.openSearchBox.reducedMotion.button.opacity};
    }
    /* ADDED UNTIL HERE */
  }
`;

export const ButtonCloud = styled.button`
  ${animateTransitionOut}
`;

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';
import {animation} from '../utils/animation';

const animateTransitionIn = css`
  animation-duration: ${animation.openSearchBox.duration};
  animation-fillMode: ${animation.openSearchBox.popup.fillMode}; 
  animation-name: ${animation.openSearchBox.popup.opacity}, ${animation.openSearchBox.popup.scale};
  animation-timing-function: ${animation.openSearchBox.easing};
  transform-origin: ${animation.openSearchBox.origin}; 
  /* ADDED FROM HERE */
  @media (prefers-reduced-motion: reduce) {
    animation-name: ${animation.openSearchBox.reducedMotion.popup.opacity};
  }
  /* ADDED UNTIL HERE */
`;

export const DivSearchBackground = styled.div`
  ${animateTransitionIn}
`;

Demo

The entire code is available in the CodeSandbox demo for this blog post.

Animation for closing the search box

That’s the topic for the next post of this blog series. Watch this space!

References

Ainalem, Mikael (2021) “Books”, CodePen, Jun 7, 2021.

Feldman, Julia, Brenton Simpson, Jonas Naimark, and Michael Gilbert (2022) “Choosing the Right Transitions”, Material Design Blog, Jan 20, 2022.

Google (undated) “The motion system”, Material Design, undated.

Liew, Zell (2017) “CSS Transitions explained”, zellwk.com, Dec 13, 2017.

Sherwin, Katie (2014) “The Magnifying-Glass Icon in Search Design: Pros and Cons”, Nielsen Norman Group, Feb 23, 2014.

Steiner, Thomas (2019) “prefers-reduced-motion: Sometimes less movement is more”, web.dev, Mar 11, 2019.

Day 21: Animating transitions for a React app without external libraries

Masa Kudamatsu — Mon, 02 Jan 2023 01:20:55 +0000

TL;DR

With four steps of coding, we can animate transitions for a React app without relying on external libraries.

First, use four state values for UI change: closed, opening, open, and closing.

Second, render a component when the state value is either opening, open, or closing. In other words:

{state !== "closed" ? (
  <div />
) : null}

Third, trigger the exiting animation by adding a data attribute to the exiting component:

{state !== "closed" ? (
  <div data-closing={state === "closing"} />
) : null}

With the following CSS selectors, entering and exiting animation start when the state turns opening and closing, respectively:

div {
  animation: /* Set entering animation parameters here */
}
div[data-closing="true"] {
  animation: /* Set exiting animation parameters here */
}

Finally, to switch the UI state from opening to open, or from closing to closed, use the onAnimationEnd prop:

{state !== "closed" ? (
  <div 
    data-closing={state === "closing"}
    onAnimationEnd={handleAnimationEnd} // ADDED
  />
) : null}

const handleAnimationEnd = () => {
  if (state === 'opening') {
    setState('open');
  }
  if (state === 'closing') {
    setState('closed');
  }
}

In the text below, I use an example of opening and closing a search box popup for more detailed description. Here is the CodeSandbox demo for this article.

1. Motivation

Implementing transition animation with React is a bit tricky. Entering animation is fine. We can simply use CSS animation, which will be triggered when a React component gets mounted. Difficulty comes with exiting animation. When a component gets dismounted, we have no opportunity to apply a set of CSS declarations for animation to that component.

There are a bunch of animation libraries to overcome this difficulty. The most famous is probably React Transition Group. There are also Framer Motion, React Spring, and Transition Hook.

To my eyes, all these libraries make the code for React components less intuitive than necessary. I'd rather code from scratch on my own to keep the code base easy to maintain.

Below I describe how I did so for My Ideal Map, a web app I’m building. As a specific example, this article aims to animate the opening and closing of a search box popup. But the same logic can be applied to other cases of transition animation.

For the ease of exposition, I stick to a simple transition animation of fade-in and fade-out (which I use for the reduced motion mode) so that the reader will not get distracted by the complexity of animation per se.

Fade-in and fade-out transitions that this article will implement with React

2. UI state management with React

Imagine that an app does not show a search box by default, to save the screen space. Instead, it shows a search button the pressing of which will open the search box.

2.1 Initial state

I set the UI state as an object called ui with two properties, searchButton and searchBox. The initial values of these two properties are open and closed, respectively.

const [ui, setUi] = useState({
  searchButton: 'open',
  searchBox: 'closed',
});

2.2 Opening search box

When the user presses the search button, the following event handler will be executed to change the UI state to closing and opening:

const handleClickSearchButton = () => {
  setUi({
    searchButton: 'closing',
    searchBox: 'opening',
  });
};

This handler is going to be attached to the search button element as the onClick prop value (see below for detail).

Then, when the transition animation ends, which triggers the animationend event, the following event handler will be executed to set the UI state to be closed and open:

const handleAnimationEnd = () => {
  setUi({
    searchButton: 'closed',
    searchBox: 'open',
  });

This handler is going to be attached to the form element, the parent of both the search button and the search box popup, as the onAnimationEnd prop value (see Section 2.6 below).

2.3 Closing search box

When the close button in the search box popup is pressed, the following event handler will set the UI state to be opening and closing:

const handleClickCloseButton = () => {
  setUi({
    searchButton: 'opening',
    searchBox: 'closing',
  });
};

This handler is going to be attached to the close button element as the onClick prop value (see Section 2.5 below).

When the transition animation ends, the event handler will set the UI state to be the initial values. This is done by revising the handleAnimationEnd function as follows:

  const handleAnimationEnd = () => {
    if (ui.searchButton === 'closing') { // ADDED
      setUi({
        searchButton: 'closed',
        searchBox: 'open',
      });
    } // ADDED
    // ADDED FROM HERE
    if (ui.searchBox === 'closing') {
      setUi({
        searchButton: 'open',
        searchBox: 'closed',
      });
    }
    // ADDED UNTIL HERE
  };

Since the animationend event is fired both when the search button completely disappears and when the search box popup completely disappears, I need to check which of these two events occurs. This is why I use the following two conditions:

if (ui.searchButton === 'closing') {}

if (ui.searchBox === 'closing') {}

2.4 Rendering search button

Now, we want to render the search button unless its UI state is closed:

{ui.searchButton !== 'closed' ? (
  <ButtonCloud
    aria-expanded="false"
    aria-label="Search a place on the map"
    onClick={handleClickSearchButton}
    type="button"
  >
    <!-- SVG code for magnifying glass icon (omitted) -->
  </ButtonCloud>
) : null}

where the ButtonCloud component refers to the search button element. Its CSS code for animation will be set with Styled Components in Section 3 below.

Note that the handleClickSearchButton function, defined in Section 2.2 above, is attached as the onClick prop value.

2.5 Rendering search box

We also want to render the search box unless its UI state is closed:

{ui.searchBox !== 'closed' ? (
  <DivSearchBackground
    data-testid="div-search-background"
  >
    <CloseButton
      ariaLabel="Close search box"
      handleClick={handleClickCloseButton}
    />
    <SearchBox closeSearchBox={closeSearchBox} id="searchbox" />
  </DivSearchBackground>
) : null}

where DivSearchBackground, CloseButton, and SearchBox refer to the popup, the close button, and the search box, respectively. Among these, DivSearchBackground will be styled with Styled Components for animation in Section 3 below.

Note that the handleClickCloseButton function, defined in Section 2.3 above, is attached to CloseButton as its handleClick prop (see Day 18 of this blog series how the CloseButton component is composed).

2.6 “Animaitonend” event handler

To listen to the animationend event, its event handler is attached to the <form role="search"> element that contains both the search button and the search box popup as its child elements. The entire JSX is now as follows:

<form 
  onAnimationEnd={handleAnimationEnd}
  role="search" 
>
  {ui.searchButton !== 'closed' ? (
    <ButtonCloud
      aria-expanded="false"
      aria-label="Search a place on the map"
      onClick={handleClickSearchButton}
      type="button"
    >
      <!-- SVG code for magnifying glass icon (omitted) -->
    </ButtonCloud>
  ) : null}
  {ui.searchBox !== 'closed' ? (
    <DivSearchBackground
      data-testid="div-search-background"
    >
      <CloseButton
        ariaLabel="Close search box"
        handleClick={handleClickCloseButton}
      />
      <SearchBox closeSearchBox={closeSearchBox} id="searchbox" />
    </DivSearchBackground>
  ) : null}
</form>

As the event bubbles up in the DOM tree, both the end of animation for the search button (ButtonCloud) and for the search box popup (DivSearchBackground) will be caught by their parent element, the <form role="search"> element.

2.7 For styling the exit animation

Finally, to animate the disappearance of the search button and the search box popup, the data-closing attribute is added to them to trigger CSS animation:

return (
  <form role="search" onAnimationEnd={handleAnimationEnd}>
    {ui.searchButton !== 'closed' ? (
      <ButtonCloud
        aria-expanded="false"
        aria-label="Search a place on the map"
        data-closing={ui.searchButton === 'closing'} // ADDED
        onClick={handleClickSearchButton}
        type="button"
      >
        <!-- SVG code for magnifying glass icon (omitted) -->
      </ButtonCloud>
    ) : null}
    {ui.searchBox !== 'closed' ? (
      <FocusLock>
        <DivSearchBackground
          data-closing={ui.searchBox === 'closing'} // ADDED
          data-testid="div-search-background"
        >
          <CloseButton
            ariaLabel="Close search box"
            handleClick={handleClickCloseButton}
          />
          <SearchBox closeSearchBox={closeSearchBox} id="searchbox" />
        </DivSearchBackground>
      </FocusLock>
    ) : null}
  </form>
)

This way, we can use the attribute selector

[data-closing="true"] {
  animation: ...
}

to style the exit animation (see Section 3 below for more detail).

We’re done with the coding for React components. Now it’s time to style transition animation with CSS.

3. Setting animation parameters

3.1 Opening search box

For the search box to enter, we want it to fade in with the duration of 300ms and the linear easing.

The choice of 300ms is inspired from Material Design. Jonas Naimark, a Material Design team member, states as follows:

Since nav transitions usually occupy most of the screen, a long duration of 300ms is a good rule of thumb. — Naimark (2018).

The linear easing is typically used for animation that doesn’t involve any movement:

Linear motion can, for example, be used only when the object changes its color or transparency. Generally speaking, we can use it for the states when an object does not change its position. — Skytskyi (2018)

The fade-in animation can be achieved with the following keyframes and the backwards value of animation-fill-mode property:

@keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

animation-fill-mode: backwards;
animation-name: fade-in;

The backwards value of animation-fill-mode prevents the flash of the default style before animation starts. Every HTML element has the opacity of 1 by default. If animation starts with the opacity value less than 1, we need animation-fill-mode: backwards.

At the same time as the search box enters, we want the search button to disappear with fade-out animation. To match the timing of animation, I use the same duration and easing values.

The fade-out animation can be defined as follows:

@keyframes fade-out {
  0% {
    opacity: 1;
  }
  100% {
    opacity: 0;
  }
}

animation-fill-mode: forwards;
animation-name: fade-in;

By default, an HTML element’s default style (including opacity: 1) will appear after animation is over. To avoid the flash of an element after fade-out animation, therefore, we need the forwards value of aniamtion-fill-mode.

To summarize the animation parameters I have set so far, let’s define a JavaScript object called animation:

// ./utils/animation.js
import { keyframes } from "styled-components";
export const animation = {
  openSearchBox: {
    duration: "300ms",
    easing: "linear",
    button: {
      opacity: keyframes`
        from {
          opacity: 0;
        }
        to {
          opacity: 1;
        }
     `,
      fillMode: "backwards",
    },
    popup: {
      opacity: keyframes`
        from {
          opacity: 0;
        }
        to {
          opacity: 1;
        }
     `,
      fillMode: "backwards",
    },
  },
};

Styled Components allow us to store keyframes as a variable with its keyframes helper (see Styled Components docs for detail).

To apply these parameters to the DivSearchBackground styled component for the search box popup, we code as follows:

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';

...

const animateTransitionIn = css`
  animation-duration: ${animation.openSearchBox.duration};
  animation-fill-mode: ${animation.openSearchBox.popup.fillMode};
  animation-name: ${animation.openSearchBox.popup.opacity};
  animation-timing-function: ${animation.openSearchBox.easing};
`;

export const DivSearchBackground = styled.div`
  ...
  ${animateTransitionIn}
`;

where the css helper is necessary to refer to the keyframes for the animation-name property.

To apply the animation parameters to the ButtonCloud styled component for the search button, we code as follows:

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';

...

const animateTransitionOut = css`
  &[data-closing="true"] {
    animation-duration: ${animation.openSearchBox.duration};
    animation-fill-mode: ${animation.openSearchBox.button.fillMode};
    animation-name: ${animation.openSearchBox.button.opacity};
    animation-timing-function: ${animation.openSearchBox.easing};
  }
`;
export const ButtonCloud = styled.button`
  ...
  ${animateTransitionOut}
`;

Note that I use the [data-closing="true"] attribute selector to define animation. This will apply only when the React state value for ui.searchButton is "closing" (see Section 2.7 above).

I believe this way of setting the parameters of transition animation is easier to maintain than using CSS variables with which (1) the nested structure of variables is infeasible and (2) the content of @keyframes cannot be stored. (Let me know if you have a different opinion.)

With the help of Styled Components (or other CSS-in-JS solutions), just going through one set of code, we can be reminded of how animation parameters were set by someone else or by ourselves in the past.

3.2 Closing search box

To close the search box, I want the fade-out animation with the duration of 250ms and the linear easing.

Duration is 50ms shorter than for opening the search box. According to the Material Design guidelines:

Transitions that close, dismiss, or collapse an element use shorter durations. Exit transitions may be faster because they require less attention than the user’s next task. — Google (undated)

For the search button to appear, I want the fade-in animation with the same duration and easing.

So we update the animation parameter object as follows:

// ./utils/animation.js
import { keyframes } from "styled-components";
export const animation = {
  openSearchBox: {
    ...
  },
  // ADDED FROM HERE
  closeSearchBox: {
    duration: "250ms",
    easing: "linear",
    button: {
      opacity: keyframes`
        from {
          opacity: 0;
        }
        to {
          opacity: 1;
        }
     `,
      fillMode: "backwards"
    },
    popup: {
      opacity: keyframes`
        from {
          opacity: 1;
        }
        to {
          opacity: 0;
        }
      `,
      fillMode: "forwards"
    },
  },
  // ADDED UNTIL HERE
};

These parameters are applied to the two styled components as follows:

// ./styled-components/DivSearchBackground.js
import styled, {css} from 'styled-components';

...

// ADDED FROM HERE
const animateTransitionOut = css`
  &[data-closing="true"] {
    animation-duration: ${animation.closeSearchBox.duration};
    animation-fill-mode: ${animation.closeSearchBox.popup.fillMode};
    animation-name: ${animation.closeSearchBox.popup.opacity};
    animation-timing-function: ${animation.closeSearchBox.easing};
  }
`;
// ADDED UNTIL HERE

export const DivSearchBackground = styled.div`
  ...
  ${animateTransitionIn}
  ${animateTransitionOut} /* ADDED */
`;

// ./styled-components/ButtonCloud.js
import styled, {css} from 'styled-components';

...

// ADDED FROM HERE
const animateTransitionIn = css`
  animation-duration: ${animation.closeSearchBox.duration};
  animation-fill-mode: ${animation.closeSearchBox.button.fillMode};
  animation-name: ${animation.closeSearchBox.button.opacity};
  animation-timing-function: ${animation.closeSearchBox.easing};
`;
// ADDED UNTIL HERE

export const ButtonCloud = styled.button`
  ...
  ${animateTransitionIn} /* ADDED*/
  ${animateTransitionOut}
 ;

3.3 More elaborate transition animation

For My Ideal Map, the web app I’m building, I use more elaborate transition animation for the search box popup. That’ll be the topic of next two posts of this blog series.

However, the above simple fade-in and fade-out animation will be used for the reduced motion mode.

4. Demo

The entire code is available in the CodeSandbox for this blog post.

Compare this demo to the one without transition animation. I believe it feels nice and tender with transition animation.

References

Google (undated) “Speed”, Material Design, undated.

Naimark, Jonas (2018) “Motion Design Doesn’t Have to be Hard”, Google Design, Sep 27, 2018.

Skytskyi, Taras (2018) “The ultimate guide to proper use of animation in UX”, UX Collective, Sep 5, 2018.

Day 20: Toggling a search box for keyboard users with React

Masa Kudamatsu — Mon, 19 Dec 2022 05:10:02 +0000

TL;DR

To toggle the visibility of a search box with React in a keyboard user-friendly manner, do the following:

Use the useEffect hook to trigger a keydown event handler for hiding the search box with the Esc key
Add the autoFocus prop to <input type="search"> so that the user can immediately start typing in the search box
Use the useEffect hook to programatically focus the toggle button after the user closes the search box
Trap the focus inside the search box popup with <FocusLock> from the react-focus-lock module.

The entire code described in this article can be found in the CodeSandbox demo.

Introduction

My Ideal Map, a web app I’m building to improve the UX of Google Maps, allows the user to search for a place on the map. While Google Maps always displays a search box on the map, My Ideal Map only shows a search button at the top-right corner to minimize the area of the map hidden from the view. I don’t want the user to fail to notice a place of their own interest beneath the search box.

My Ideal Map’s user interface with the toggle button for a search box at the top-right corner (screenshot by the author)

To search for a place on the map, therefore, the user needs to press the search button to see a search box. And, if they change their mind, the user should be allowed to close the search box and go back to the full-screen view of the map.

Implementing this user experience with React is straightforward if we care about touch device users and mouse users only. But there are keyboard users out there, including those screen reader users. Implementation for these users with React turns out to be not trivial at all.

Below I describe what I have learned, by constructing a React component for the search feature step by step.

1. HTML

To construct a React component, the first thing I do is to forget about React and focus on what HTML code to write.

1.1 Search button

By default, I want the following HTML code:

<form role="search">
  <button
    aria-expanded="false"
    aria-label="Search place"
    type="button"
  >
    <!-- SVG code for the search button (omitted) -->
  </button>
</form>

Here are some footnotes on this piece of code:

Wrapping the button to open a search box with <form role="search"> allows screen-reader users to notice that the search feature is available on a website (MDN Contributors 2022a).
Screen reader users, when focusing on the <button> element, will learn that the search box is currently hidden thanks to aria-expanded="false" (Silver 2019).
I use aria-label to give an accessible name to the button, because the button is an icon button with no text label (see Day 16 of this blog series for detail).

Incidentally, I initially used aria-controls to link the button with <input type="search">, to indicate which element the button will open.However, Pickering (2016) points out that only the JAWS screen reader supports the aria-controls attribute. ARIA Authoring Practices Guide on menu button recommends aria-controls only as optional. Apparently, we can forget about aria-controls (let me know if I’m wrong).

1.2 Search box

Now, when the user clicks the button, I want the HTML code to change as follows:

<form role="search">
  <div class="popup">
    <button
      aria-label="Close searchbox"
      type="button"
    >
      <!-- SVG code for a cross icon (x) (omitted) -->
    </button>
    <div class="searchbox">
      <!-- SVG code for a magnifyiing glass (omitted) -->
      <input
        aria-label="Search for a place on the map"
        autocomplete="off"
        inputmode="search"
        placeholder="Enter place name or address"
        type="search"
      />
    </div>
  </div>
</form>

The <div class="popup"> element is the one created in Day 19 of this blog series, styling the popup like clouds and positionining the close button at the top right corner.

The <button> element will be rendered by the close button component that I have created on Day 18 of this blog series.

The <div class="searchbox"> and its child elements is the search box that I have created on Day 17 of this blog series

1.3 Rendering HTML with React

Using the CloseButton component created on Day 18, I render the HTML code as described above with the following React component:

import {useState} from 'react';
import {CloseButton} from './components/CloseButton';

export const Search = () => {
  const [searchBoxOpen, setSearchBoxOpen] = useState('false');
  return (
    <form role="search">
      {searchBoxOpen === 'false' ? (
        <button
          aria-expanded="false"
          aria-label="Search place"
          onClick={() => setSearchBoxOpen('true')}
          type="button"
        >
          {/* SVG code for a magnifyiing glass (omitted) */}
        </button>
      ) : (
        <div className="popup">
          <CloseButton
            ariaLabel="Close searchbox"
            handleClick={() => setSearchBoxOpen('false')}
          />
          <div className="searchbox">
            <input
              aria-label="Search for a place on the map"
              autoComplete="off"
              inputMode="search"
              placeholder="Enter place name or address"
              type="search"
            />
          </div>
        </div>
      )}
    </form>
  );
};

I create a state variable called searchBoxOpen with the useState hook. When it is false, the toggle button is rendered. When it is true, the search box popup is rendered.

Note also that we now need to use the camelCase for autoComplete and inputMode props in place of autocomplete and inputmode HTML attributes.

Now let me get to the main point of this article: handling keyboard users.

2. Focus management

Keyboard users need to control which interactive element is currently focused. For this purpose, there are three things to implement: (1) focus the search box after opening it; (2) focus the button to open the search box after closing it; (3) trap the focus within the popup showing the search box.

2.1 After opening the search box

For good user experience, auto-focusing the search box is critical:

Don’t make people click twice when once (or not at all) will do. In some cases, the user has to first click the icon to open the search box and then click to move the input focus into the search field. One click on the icon should put the cursor in the field, ready for typing. — Sherwin (2014)

This feature is actually not just for keyboard users; touch device users and mouse users will also benefit from it.

For implementation, Johnson (2019) describes three ways of auto-focusing an interactive element in React: the autoFocus prop, the combination of useEffect and useRef, and callback refs. She concludes:

I would recommend that you use the autoFocus prop, unless you have odd circumstances (like I did) that prevent it from working. — Johnson (2019)

Following this piece of advice, I add the autoFocus prop to the <input type="search"> element:

export const Search = () => {
  const [searchBoxOpen, setSearchBoxOpen] = useState('false');
  ...
  return (
    <form role="search">
      {searchBoxOpen === 'false' ? (
        <button
          aria-expanded="false"
          aria-label="Search place"
          onClick={() => setSearchBoxOpen('true')}
          type="button"
        >
          {/* SVG code for a magnifyiing glass (omitted) */}
        </button>
      ) : (
        <div className="popup">
          <CloseButton
            ariaLabel="Close searchbox"
            handleClick={() => setSearchBoxOpen('false')}
          />
          <div className="searchbox">
            <input
              aria-label="Search for a place on the map"
              autoComplete="off"
              autoFocus // ADDED
              inputMode="search"
              placeholder="Enter place name or address"
              type="search"
            />
          </div>
        </div>
      )}
    </form>
  );
};

This way, whenenver the user presses the magnifying glass button, the popup opens up with the search box focused automatically.

Unfortunately, iOS Safari users cannot immediately type into the auto-focused search box, though. Here is Apple’s take:

We (Apple) ... do not want programmatic focus to bring up the keyboard when you do not have a hardware keyboard attached and the programmatic focus was not invoked in response to a user gesture. Why you may ask...because auto bringing up the software keyboard can be seen as annoying and a distraction to a user... — Bates (2019)

We just need to accept this iOS Safari’s behavior. There is no simple way around, it seems.

Incidentally, auto-focusing has an accessibility issue:

Automatically focusing a form control can confuse visually-impaired people using screen-reading technology and people with cognitive impairments. When autofocus is assigned, screen-readers "teleport" their user to the form control without warning them beforehand. — MDN Contributors (2022b)

Since I have labelled <input type="search"> with aria-label="Search for a place on the map", screen reader users will learn what kind of interactive element they are now focusing on.

2.2 After closing the search box

After the user closes the popup for search, the button that has opened the popup should be auto-focused. That’s the recommendation by the ARIA Authoring Practices Guide:

When a dialog closes, focus returns to the element that invoked the dialog... — the ARIA Authoring Practices Guide for “Dialog (Modal)”

This feature is convenient when the keyboard user mistakenly presses the close button. In this case, they want to go back to the search box immediately. With the button to open it automatically focused, they can just hit the Return key to undo their mistake.

For implementation, we cannot use the autoFocus prop this time. The button to open the search box is rendered every time the user accesses to the app. We don’t want the search button to be always focused; the user may want to open the menu first or locate themselves on the map by pressing the locator button (see Day 12).

Instead we want to auto-focus the search button only after the search box popup is closed. This happens when the searchBoxOpen state changes from true to false. We can regard the auto-focusing of the seach button as a side effect of state change. That is when we should use the useEffect hook.

So we can use what Johnson (2019) describes as the second approach of auto-focusing an element in React: the combination of useEffect and useRef.

First, refer to the toggle button with the useRef hook:

  ...
  const buttonElement = useRef();
  ...
  return (
    ...
        <button
          aria-expanded="false"
          aria-label="Search place"
          onClick={() => setSearchBoxOpen('true')}
          ref={buttonElement} // ADDED
          type="button"
        >
  )

Then, use the useEffect hook to run the following code whenever the search box is closed:

  useEffect(() => {
    if (searchBoxOpen === 'false') {
      buttonElement.current.focus();
    }
  }, [searchBoxOpen]);

Well, the above useEffet code block doesn’t work quite. It will auto-focus the search button when the button is first rendered (that is, when the user first accesses the app). The reason is that the useEffect hook only picks the current state, not the previous state as well.

I think there are a few ways around. One solution is to record whether the close button is pressed with the useRef hook. So revise the click handler of the close button as follows:

...
  // ADDED FROM HERE
  const closeButtonPressed = useRef();
  const handleClickCloseButton = () => {
    closeButtonPressed.current = true;
    setSearchBoxOpen('false');
  }
  // ADDED UNTIL HERE
...
          <CloseButton
            ariaLabel="Close searchbox"
            handleClick={handleClickCloseButton} // REVISED
          />
...

Then, we can check whether closeButtonPressed.current is true before auto-focusing the search button:

...
  const buttonElement = useRef();
  useEffect(() => {
    if (searchBoxOpen === 'false') {
      // REVISED FROM HERE
      if (closeButtonPressed.current === true) {
        buttonElement.current.focus();
      }
      // REVISED UNTIL HERE
    }
  })
...

So the entire code is as follows:

import {useEffect, useRef, useState} from 'react'; // REVISED
import {CloseButton} from './components/CloseButton';

export const Search = () => {
  const [searchBoxOpen, setSearchBoxOpen] = useState('false');

  ...

  // ADDED FROM HERE
  const buttonElement = useRef();
  const closeButtonPressed = useRef();

  const handleClickCloseButton = () => {
    closeButtonPressed.current = true;
    setSearchBoxOpen('false');
  }

  useEffect(() => {
    if (searchBoxOpen === 'false') {
      if (closeButtonPressed.current === true) {
        buttonElement.current.focus();
      }
    }
  }, [searchBoxOpen]);
  // ADDED UNTIL HERE

  return (
    <form role="search">
      {searchBoxOpen === 'false' ? (
        <button
          aria-expanded="false"
          aria-label="Search place"
          onClick={() => setSearchBoxOpen('true')}
          ref={buttonElement} // ADDED
          type="button"
        >
          {/* SVG code for a magnifying glass (omitted) */}
        </button>
      ) : (
        <div className="popup">
          <CloseButton
            ariaLabel="Close searchbox"
            handleClick={handleClickCloseButton} // REVISED
          />
          <div className="searchbox">
            <input
              aria-label="Search for a place on the map"
              autoComplete="off"
              autoFocus
              inputMode="search"
              placeholder="Enter place name or address"
              type="search"
            />
          </div>
        </div>
      )}
    </form>
  );
};

This solution can also handle the situation where the searchbox popup closes when the user selects one of the autocomplete suggestions (which will be implemented in one of the next posts of this blog series). In this case, the app will autofocus the popup showing the search result, not the search button. So we can create a click handler for the search result element like so:

 const closeSearchBox = () => {
    closeButtonPressed.current = false;
    setSearchBoxOpen('false');
  };

This way, the code block of useEffect for auto-focusing will not run.

2.3 Trap the focus within the popup

Finally, we want to trap the focus within the search box popup. Otherwise, keyboard users can end up having a focus on one of the place marks in the map beneath the popup. Again, let me cite ARIA Authoring Practices Guide:

If focus is on the last tabbable element inside the dialog, [Tab] moves focus to the first tabbable element inside the dialog.
If focus is on the first tabbable element inside the dialog, [Shift + Tab] moves focus to the last tabbable element inside the dialog.
— ARIA Authoring Practices Guide for “Dialog (Modal)”

The implementation of focus trap is very complicated to code from scratch. See Giraudel (2021) for how complex the code can be.

More recently, web developers have been talking about the inert attribute to trap the focus (see Klavenes 2022, for example). As of November 2022, however, Firefox is yet to support the inert attribute (source: Can I Use?). We need to wait for a bit more.

The solution I’ve adopted is the react-focus-lock library, used by Atlassian AtlasKit, ReachUI, SmoothUI, and Storybook among others.

With its FocusLock component, it’s remarkably simple to implement the focus trap:

...
import FocusLock from 'react-focus-lock'; // ADDED

export const Search = () => {
  ...
  return (
    <form role="search">
      {searchBoxOpen === 'false' ? (
        <button
          aria-expanded="false"
          aria-label="Search place"
          onClick={() => setSearchBoxOpen('true')}
          ref={buttonElement}
          type="button"
        >
          {/* SVG code for a magnifying glass (omitted) */}
        </button>
      ) : (
        <FocusLock> {/* ADDED */}
          <div className="popup">
            <CloseButton
              ariaLabel="Close searchbox"
              handleClick={() => setSearchBoxOpen('false')}
            />
            <div className="searchbox">
              <input
                aria-label="Search for a place on the map"
                autoComplete="off"
                autoFocus
                inputMode="search"
                placeholder="Enter place name or address"
                type="search"
              />
            </div>
          </div>
        </FocusLock> {/* ADDED */}
      )}
    </form>
  );
};

We just need to wrap the popup with <FocusLock>. This way, once the popup is open, pressing the Tab key will cycle the focus within the popup (in our case, the focus moves between the search box and the close button only).

3. Close with ESC key

For keyboard users, pressing the ESC key is the standard method for closing a popup. In the ARIA Authoring Practices Guide for “Dialog (Modal)”, the pressing of the Esc key to close the dialog is listed as one of keyboard interaction requirements.

How can we implement this feature with React?

Woodson (2020) gives me a clue. He suggests using the useEffect hook like this:

useEffect(() => {
  window.addEventListener('keydown', (event) => {
      // ...
  });
}, []);

The code block inside the useEffect hook will be run after the HTML code is rendered. Therefore, it allows the keydown event handler to be attached to the window object that will not be created until the HTML code is rendered.

However, the keydown event is fired on the document object, not the window object, according to the MDN Web Docs on “Event reference”. So I’m going to use document.addEventListener().

Let’s first work out the code inside the useEffect hook. I define an keydown event handler as closeByEsc:

const closeByEsc = event => {
  if (event.key === 'Escape') {
    handleClickCloseButton();
  }
};

If the pressed key, available as event.key, is the Esc key, this handler runs the handleClickCloseButton function defined in the previous section:

  const handleClickCloseButton = () => {
    closeButtonPressed.current = true;
    setSearchBoxOpen('false');
  }

This way, after pressing the Esc key to close the popup, the toggle button will be auto-focused, just like after pressing the close button.

Then, when the search box is opened, attach this event handler to document:

if (searchBoxOpen === 'true') {
  document.addEventListener('keydown', closeByEsc);
}

When the search box is closed, remove this event handler from document:

if (searchBoxOpen === 'true') {
  document.addEventListener('keydown', closeByEsc);

// ADDED FROM HERE
} else {
  document.removeEventListener('keydown', closeByEsc);
// ADDED UNTIL HERE

}

This way, pressing the Esc key will close the search box if and only if the search box is open. When another popup is open, I want them to be closed with the pressing of the Esc key as well. Each time a popup is opened (or closed), I will attach (or remove) the event handler dedicated to closing that particular popup.

Then insert them all into the useEffect hook code block:

useEffect(() => { // ADDED
  const closeByEsc = event => {
    if (event.key === 'Escape') {
      handleClickCloseButton();
    }
  };
  if (searchBoxOpen === 'true') {
    document.addEventListener('keydown', closeByEsc);
  } else {
    document.removeEventListener('keydown', closeByEsc);
  }
}, [searchBoxOpen]); // ADDED

where [searchBoxOpen], the second argument for the useEffect hook, makes the useEffect code block run each time the value of searchBoxOpen changes. This is critical to attach and remove the event listener each time the search box is opened and closed.

Finally, in case the Search component is dismounted while the search box remains open, we want to remove the event listener. To implement this, we use the return statement:

useEffect(() => {
  const closeByEsc = event => {
    if (event.key === 'Escape') {
      handleClickCloseButton();
    }
  };
  if (searchBoxOpen === 'true') {
    document.addEventListener('keydown', closeByEsc);
  } else {
    document.removeEventListener('keydown', closeByEsc);
  }

  // ADDED FROM HERE
  return () => {
    document.removeEventListener('keydown', closeByEsc);
  }
  // ADDED UNTIL HERE

}, [searchBoxOpen]);

The complete code for the Search component (including the one described in the previous section) is now as follows:

import FocusLock from "react-focus-lock"; // for trapping focus inside popup
import { useEffect, useRef, useState } from "react";
import { ButtonCloud } from "../styled-components/ButtonCloud";
import { CloseButton } from "./CloseButton";

export const Search = () => {
  const [searchBoxOpen, setSearchBoxOpen] = useState("false");

  // Auto-focus the search button after closing search box
  const buttonElement = useRef();
  const closeButtonPressed = useRef();
  const handleClickCloseButton = () => {
    closeButtonPressed.current = true;
    setSearchBoxOpen("false");
  };
  useEffect(() => {
    if (searchBoxOpen === "false") {
      if (closeButtonPressed.current === true) {
        buttonElement.current.focus();
      }
    }
  });

  // Close search box with Esc key
  useEffect(() => {
    const closeByEsc = (event) => {
      if (event.key === "Escape") {
        handleClickCloseButton();
      }
    };
    if (searchBoxOpen === "true") {
      document.addEventListener("keydown", closeByEsc);
    } else {
      document.removeEventListener("keydown", closeByEsc);
    }
    return () => {
      document.removeEventListener("keydown", closeByEsc);
    };
  }, [searchBoxOpen]);

  return (
    <form role="search">
      {searchBoxOpen === "false" ? (
        <button
          aria-expanded="false"
          aria-label="Search place"
          onClick={() => setSearchBoxOpen("true")}
          ref={buttonElement}
          type="button"
        >
          {/* SVG code for a magnifying glass (omitted) */}
        </button>
      ) : (
        <FocusLock> {/* trap focus inside popup */}
          <div className="popup">
            <CloseButton
              ariaLabel="Close searchbox"
              handleClick={handleClickCloseButton}
            />
            <div className="searchbox">
              <input
                aria-label="Search for a place on the map"
                autoComplete="off"
                autoFocus // Auto-focus search box when opened
                inputMode="search"
                placeholder="Enter place name or address"
                type="search"
              />
            </div>
          </div>
        </FocusLock>
      )}
    </form>
  );
};

Demo

Here is the CodeSandbox demo for the entire code discussed in this article. With this demo, try the following:

Press the magnifying glass icon button at the top-right corner. You should be able to enter text in the search box (unless you use iOS Safari).
Press the Tab key to see the focus ring move between the search box and the close button.
Press the Esc key to close the search box.
After closing the search box, press the Enter key, which should open the search box again.

References

Bates, Daniel (2019) “So, I've got some good news 🙂 and some bad news 🙁 for you. Let's do good news first...”, Comment to WebKit Bugzilla, Mar 19, 2019.

Giraudel, Kitty (2021) “Creating An Accessible Dialog From Scratch”, Smashing Magazine, Jul 28, 2021.

Johnson, Maisie (2019) “3 ways to autofocus an input in React that ALMOST always work!”, blog.maisie.ink, Oct 25, 2019.

Klavenes, Lars Magnus (2022) “Accessible modal dialogs using inert”, larsmagnus.co, Jun 11, 2022.

MDN Contributors (2022a) “”, MDN Web Docs, last modified on Dec 11, 2022.

MDN Contributors (2022b) “: The Input (Form Input) element”, MDN Web Docs, last modified on Nov 26, 2022.

Pickering, Heydon (2016) “Aria-Controls is Poop”, Heydonworks, Aug 21, 2016.

Sherwin, Katie (2014) “The Magnifying-Glass Icon in Search Design: Pros and Cons”, Nielsen Norman Group, Feb 23, 2014.

Silver, Adam (2019) “Why, How, and When to Use Semantic HTML and ARIA”, CSS-Tricks, May 7, 2019.

Woodson, Marques (2020) “Event Listeners in React Components”, Pluralsight, Jun 12, 2020.

Day 19: Styling a popup like clouds

Masa Kudamatsu — Fri, 16 Dec 2022 04:38:04 +0000

TL;DR

For a popup in web apps to appear like clouds, use the frosted glass look (aka. glassmorphism) with translucent white box shadows around (as seen in the top image). And write the CSS code as in the CodeSandbox demo for this article.

Introduction

My Ideal Map, a web app I'm buidling, aims to improve the user experience of Google Maps. For one thing, it allows users to see their saved places on Google Maps and nothing else.

Naturally, the app needs to embed Google Maps full-screen by default.

Given this default user interface, how should I design and code popups to show menus, a search box, error messages, etc.?

My answer is to make popups appear like the eye sight of being in the midst of clouds, with the CSS technique for glassmorphism.

In this article, I describe the rationale behind this design decision and the CSS code for realizing this UI design.

Design considerations

Whenever I need to make a decision on designing a web app component, I go back to the design concept for the whole app.

The design concept of My Ideal Map is “Dye me in your hue from the sky”. Likening Google Maps to the view of city streets from the sky, the app “dyes” the city view with colorful placemarks as the user’s favorite places. (For more detail, see Day 2 of this blog series.)

Consequently, I design the app’s user interface, featuring Google Maps full-screen, by mocking the view of a city from the sky. Which is why I have designed the buttons to open the menu and to open the search box as if they were the clouds floating in the sky. (For more detail, see Day 7.)

Now I need to design popups that opens up after pressing these cloud-shaped buttons. The popup will also display information on searched or saved places or error messages.

The city view, that is, the embedded Google Maps, will be overlaid with a popup. Imagine you’re flying high in the sky like a bird, looking down the streets of a city. What can the bird-eye’s view of a city be overlaid with?

Yes, clouds.
Aerial view of central London amid clouds (image source: Wirestock via Freepik)

Given that the user presses the cloud-shaped buttons to open the popups for the menu and the search box, popups should give an impression that the user moves into the midst of clouds, with their eye sight blurred due to the myriads of tiny water droplets in the clouds.

Now the question is what makes the popup background appear like being the midst of clouds.

What makes the popup look like clouds?

First attempt: solid white

Clouds are white. I can make the popup look like clouds by making its background purely white:

.popup {
  background-color: rgb(255, 255, 255);
}

Well, that doesn’t work. A solid white background reminds us of white paper. Many web apps use this analogy, including Google Maps. With the pure white background, I cannot distinguish My Ideal Map from Google Maps. That's not a good branding strategy because the app is not a copycat of Google Maps. Instead it aims to improve the user experience of Google Maps.

Second attempt: translucent white

A better idea is a translucent white background with the opacity of, say, 93%:

.popup {
  background-color: rgba(255, 255, 255, 0.93);
}

A cloud is not a solid. It’s made of myriads of tiny water droplets. What’s behind can be seen through clouds as long as clouds are not too thick.

But I wasn’t satisfied with this solution, without exactly knowing why.

Third attempt: Glassmorphism

I kept searching for inspiration, and I happened to learn about the UI style known as “glassmorphism” (Malewicz 2020). It is the frosty-glass look introduced by Microsoft’s Fluent Design System and later popularized by MacOS BigSur.

As the name suggests, it imitates the look of a glass sheet with uneven surface. Refraction of light in varoius directions (due to the unevenness of the glass surface) blurs the appearance of what’s behind the glass.

I realize that’s what happens when we are in the midst of clouds. Clouds are made of tiny water droplets, refracting light in various directions. As a result, the view of what’s behind clouds gets blurred.

Yes, I can use the “glassmorphism” look to make My Ideal Map's popups appear like clouds.

And I want to achieve something like this:

CSS for glassmorphism look

The basic technique to create the glassmorphism look is to use the CSS declaration of background-filter: blur().

Until very recently (July 22, 2022), however, Firefox didn’t support the background-filter property. As no one clearly explained how to allow Firefox users to see the glassmorphism look, I wrote an article entitled “Glassmorphism for Firefox” (Kudamatsu 2021), which now comes at the top of Google search for “glassmorphism Firefox”.

Using the technique descirbed in that article, I can make the popup’s background look like clouds as follows.

Supporting legacy browsers

First, provide the fallback for legacy browsers

.popup {
  --popup-background-color-fallback: rgba(255, 255, 255, 0.93);
  background-color: var(--popup-background-color-fallback);
}

A translucent white does the best job to imitate clouds as a fallback. The opacity value of 0.93 is chosen because it is used for cloud-shaped buttons as well (see Section 6.1 of Day 7).

For modern browsers

Then, for all the modern browsers (including the versions of Firefox released in July 2022 or later), overwrite the background-color property as follows:

.popup {
/* ADDED FROM HERE */
  --blur-radius: 8px;
  --popup-background-color: rgba(255, 255, 255, 0.75);
  /* ADDED UNTIL HERE */

  --popup-background-color-fallback: rgba(255, 255, 255, 0.93);
  background-color: var(--popup-background-color-fallback);
}

/* ADDED FROM HERE */
@supports (backdrop-filter: blur(var(--blur-radius))) or (-webkit-backdrop-filter: blur(var(--blur-radius))) {
  .popup {
    background-color: var(--popup-background-color);
    -webkit-backdrop-filter: blur(var(--blur-radius));
    backdrop-filter: blur(var(--blur-radius));
  }
}
/* ADDED UNTIL HERE */

First, the blur radius value of 8px for backdrop-filter and the opacity value of 0.75 for background-color were chosen after trial and error to make the popup background evoke a sense of clouds.

Second, the @supports at-rule is necessary to prevent legacy browsers from overwriting the background-color property value.

Finally, the -webkit-backdrop-filter property is necessary to support Safari, which ignores backdrop-filter without the prefix.

For legacy Firefox and Kai OS

Finally, for the versions of Firefox released before July 2022, which doesn’t support background-filter, I use the -moz-element() CSS function to achieve the same glassmorphism look. This Firefox-only function, which I wish other browsers would also support, copies another HTML element as an image. If we set

background-attachment: fixed;
background-image: -moz-element(#map);

then the background image is exactly the same as what is rendered as an HTML element with id="map". Since I embed Google Maps in <div id="map"> by following the Google Maps Platform documentation, the above CSS declaration uses the entire Google Maps as the background image(!). Plus, thanks to background-attachment: fixed, the positioning of an image of Google Maps is exactly the same as the original one.

Using this technique, here’s the entire CSS code to achieve the glassmorphism background:

.popup {
  --blur-radius: 8px; 
  --popup-background-color: rgba(255, 255, 255, 0.75); 
  --popup-background-color-fallback: rgba(255, 255, 255, 0.93);
  background-color: var(--popup-background-color-fallback);
}
@supports (backdrop-filter: blur(var(--blur-radius))) or (-webkit-backdrop-filter: blur(var(--blur-radius))) {
  .popup {
    background-color: var(--popup-background-color);
    -webkit-backdrop-filter: blur(var(--blur-radius));
    backdrop-filter: blur(var(--blur-radius));
  }
}

/* ADDED FROM HERE */
@supports (background-image: -moz-element(#map)) and (not (backdrop-filter: blur(var(--blur-radius)))) {
  .popup {
    background-color: transparent;
  }
  /* Blurring the map beneath */
  .popup::before {
    background-attachment: fixed;
    background-image: -moz-element(#map);
    content: "";
    filter: blur(var(--blur-radius));
    position: absolute;
    left: 0; right: 0; top: 0; bottom: 0;
    z-index: -2;
  }
  /* Applying translucent white on top */
  .popup::after {
    background-color: var(--popup-background-color);
    content: "";
    position: absolute;
    left: 0; right: 0; top: 0; bottom: 0;
    z-index: -1;
  }
}
/* ADDED UNTIL HERE */

First, the @supports at-rule includes (not (backdrop-filter: blur(var(--blur-radius)))) so that the latest versions of Firefox will ignore the rule.

Second, the popup element itself has a transparent background, because the other two pseudo elements, rendered beneath, create the glassmorphism look.

Third, the ::before pseudo element’s filter: blur() applies the same blurring effect to the background as the background-filter: blur() does.

Finally, the blurred map image is overlaid with the ::after pseudo element whose background color is --popup-background-color (i.e., the translucent white).

For more detail, please see Section 2 of Kudamatsu (2021).

It turns out that Kai OS, a Chinese mobile phone OS, also supports the -moz-element() CSS function, but not backdrop-filter (the links take you to Can I Use?). So the fallback for legacy Firefox also works for Kai OS.

Edge treatment

If the popup is full-screen, the above CSS code is enough to create an impression of clouds. But on a large screen, the popup needs to occupy only a part of the screen. Since the edge of an HTML element is straight by default, it kills an illusion of clouds as a popup.

My solution is to use box shadow as follows:

box-shadow: 0 0 var(--blur-radius) var(--blur-radius) var(--popup-background-color);

where --blur-radius and --popup-background-color are defined as 8px and rgba(255, 255, 255, 0.75), respectively, as in the previous section.

The first two values of box-shadow locate the shadow beneath the element. With 0 0, the shadow is positioned directly beneath the element, as if the light hits the element directly from the above. This way, all the four sides have shadows.

The third and fourth values of box-shadow are the blur radius and the spread radius, respectively. The former specifies the degree to which the shadow color blends with the image beneath while the latter sets the extent to which the shadow expands around the original rectangle (see my article, Kudamatsu 2020, for more detail).

It seems that the definition of blur radius differs between the box-shadow property and the blur() function (see Baron 2011). After trial and error, however, I find using 8px, the value for blur(), for both blur and spread radius values of box-shadow makes the popup's straight edge least noticeable.

And the fifth value of box-shadow is the shadow color. I use the same translucent white as the one used for the popup background. This changes whether we target legacy browsers or modern browsers. So the entire CSS code is now as follows:

.popup {
  --blur-radius: 8px; 
  --popup-background-color: rgba(255, 255, 255, 0.75); 
  --popup-background-color-fallback: rgba(255, 255, 255, 0.93);
  /* Legacy browsers */
  background-color: var(--popup-background-color-fallback);
  box-shadow: 0 0 var(--blur-radius) var(--blur-radius) var(--popup-background-color-fallback); /* ADDED */
}
@supports (backdrop-filter: blur(var(--blur-radius))) or (-webkit-backdrop-filter: blur(var(--blur-radius))) {
  .popup {
    background-color: var(--popup-background-color);
    -webkit-backdrop-filter: blur(var(--blur-radius));
    backdrop-filter: blur(var(--blur-radius));
    box-shadow: 0 0 var(--blur-radius) var(--blur-radius) var(--popup-background-color); / * ADDED */
  }
}
/* Legacy Firefox */
@supports (background-image: -moz-element(#map)) and (not (backdrop-filter: blur(var(--blur-radius)))) {
  .popup {
    background-color: transparent;
    box-shadow: none; /* ADDED */
  }
  /* Blurring the map beneath */
  .popup::before {
    background-attachment: fixed;
    background-image: -moz-element(#map);
    content: "";
    filter: blur(var(--blur-radius));
    position: absolute;
    left: 0; right: 0; top: 0; bottom: 0;
    z-index: -2;
  }
  /* Applying translucent white on top */
  .popup::after {
    background-color: var(--popup-background-color);
    box-shadow: 0 0 var(--blur-radius) var(--blur-radius) var(--popup-background-color); /* ADDED */
    content: "";
    position: absolute;
    left: 0; right: 0; top: 0; bottom: 0;
    z-index: -1;
  }
}

For legacy Firefox, the box-shadow is best to be applied to the ::after pseudo element to conceal the straight edges of a popup element. (Again it is the conclusion from trial and error; I don’t know the reason behind.) This is why I need to remove the box-shadow of the popup element itself: otherwise, the box shadow for legacy browsers will also be rendered.

Other styling

There are a couple of other CSS declarations necessary to render a popup over the map.

Placing over the map

The HTML code for the map and the popup in My Ideal Map will be something like this:

<body>
  <main>
    <div id="map">
      <!-- JavaScript embeds Google Maps here-->
    </div>
  </main>
  <form role="search">
    <div class="popup">
      <button aria-label="Close popup" type="button">
        <!-- SVG code for the cross (x) icon (omitted) -->
      </button>
    </div>
  </form>
</body>

where <form role="search"> can be other landmark role elements such as <nav> for the navigation menu.

To place the popup over the map, therefore, we need to apply position: absolute to the popup. If the popup is full screen, the following CSS code does the job:

.popup {
  bottom: 0;
  left: 0;
  position: absolute;
  right: 0;
  top: 0;
}

To make the popup smaller than the full-screen size, we can adjust the values of bottom, left, right, and top. In the demo for this article, I set these four property values to be 10% so that the popup size is 80% of the full screen size (and center-aligned).

Positioning the close button

To position the close button around the top right corner of the popup, I use the following CSS code:

.popup {
  --popup-margin: 8px;
}
.popup button[aria-label="Close popup"] {
  position: absolute;
  right: var(--popup-margin);
  top: var(--popup-margin);
}

The value of 8px is chosen as the minimum spacing between interactive elements:

Touch targets should also be spaced about 8 pixels apart, both horizontally and vertically, so that a user's finger pressing on one tap target does not inadvertently touch another tap target. — (Gash et al. 2020).

The top-right corner of the popup, if not full-screen, can be adjacent to a tappable element on Google Maps. To make sure the user will be able to tap the close button rather than something else on Google Maps, I want the tappable area of the close button 8px away from the top corner both vertically and horizontally.

Also, I use the attribute selector button[aria-label="Close popup"] to style the close button. A popup is very likely to have other buttons as its child elements. To target the close button only, we can use a class selector like .close-button. As I use Styled Components to style the close button (see Day 18), however, I need an alternative selector that does not require any change in the HTML code. In such a situation, the attribute selector is a great solution.

Demo

Here’s the demo of the entire code described in this article. It uses React to reuse the CloseButton component created on Day 18. But I use CSS stylesheet, rather than Styled Components, in line with what this article describes.

References

Baron, David (2011) “What does a blur radius mean?”, David Baron’s Weblog, Feb 25, 2011.

Gash, Dave, Meggin Kearney, Rachel Andrew, Rob Dodson, and Patrick H. Lauke (2020) “Accessible tap targets”, web.dev, Mar 31, 2020.

Kudamatsu, Masa (2020) “CSS box shadow is not to create a shadow...”, Web Dev Survey from Kyoto, Jan 3, 2020.

Kudamatsu, Masa (2021) “Glassmorphism for Firefox)”, Web Dev Surveys from Kyoto, Dec 3, 2021.

Malewicz, Michal (2020) “Glassmorphism in user interfaces”, UX Collective, Nov 23, 2020.

Day 18: Building a close button with ripple effect as a React component

Masa Kudamatsu — Mon, 12 Dec 2022 10:18:31 +0000

TL;DR

This article goes through the steps to build a close button as a React component.

You will also learn

HTML coding best practices for close buttons (Section 1)
How to style an SVG icon button (Section 3)
Best practices for styling the button focus state (Section 4)
How to display the ripple animation after clicking the button (Section 5)

The result is available as a CodeSandbox demo.

Introduction

The web app I’m developing features a view of Google Maps embedded in full-screen. For the user to search a place on the map, to save a searched place, to see the detail of a saved place, and to change the user setting, the app needs a popup window to provide information and relevant buttons to the user.

One of those buttons is the close button, that little cross icon at the top-right corner of a popup. Since it will be used for all these popups, it is best to build it as a reusable component.

It turns out that making a close button component involves quite a bit of web dev techniques. In this article, I’d like to share what I have learned out of my experience of creating a close button as a React component.

1. HTML

When I start composing a React component, the first thing I do is to forget about React. Instead I solely focus on HTML. What HTML code do I want the React component to render? That’s the question I ask myself.

A little investigation into the best practices of coding HTML for the close button led me to discover two excellent articles on the subject: Stanton (2020) and Matuzovic (2020). Below is what I digest from them.

1.1 SVG Icon

Using the character ✕ as an “icon” for the close button is not a good idea in terms of accessibility: for screen reader users, it does not mean “close something”. Matuzovic (2020) writes:

✕ doesn’t represent close or crossed out, it’s the multiplication sign, like in 2 ✕ (times) 2. Don’t use it for close buttons.

Instead, the best approach is to use an SVG icon, which itself has no literal meaning. For my purpose, using SVG is also beneficial in terms of visual consistency: since I’m developing a web app that heavily features Google Maps (see Day 1 of this blog series), an SVG icon taken from Google‘s Material Icons will achieve visual consistency in my web app design.

Material Icons’s “Close” icon has the following SVG code:

<svg
  xmlns="http://www.w3.org/2000/svg"
  height="24px"
  viewBox="0 0 24 24"
  width="24px"
  fill="#000000"
>
  <path d="M0 0h24v24H0V0z" fill="none" />
  <path
    d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"
  />
</svg>

What I actually need is the viewBox attribute value and the second <path> element.

The xmlns attribute is unnecessary if the SVG code is embedded in HTML (see MDN Web Docs on <svg>).
The height and width attributes are redundant when we use CSS to set the size (see Bellamy-Royds 2015).
So is the fill attribute (we can use CSS).
And I always wonder what the first <path> element is for, whenever I download Material Icons SVG images (please comment to this article if you have an idea).

So the first attempt to code HTML for the close button is something like this:

<button type="button">
  <svg viewBox="0 0 24 24">
    <path
      d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"
    />
  </svg>
</button>

1.2 Button label for screen reader users

However, the above HTML code would confuse screen reader users: the button has no label. To let them know what the button does, we need to add aria-label:

<button aria-label="Close" type="button"> <!-- REVISED -->
  <svg aria-hidden="true" viewBox="0 0 24 24"> <!-- REVISED -->
    <path
      d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"
    />
  </svg>
</button>

Here I apply the lesson learned on Day 16 of this blog series: “Icon buttons should be labelled with aria-label” (see the link for detail). It also happens to be what Stanton (2020) concluses as the best practice for close buttons.

You might wonder why the <svg> element is hidden for screen readers with aria-hidden="true". Once the button is labeled with aria-label, screen reader users do not need to know whether there is an SVG icon on the button or not. So we can remove it for them.

1.3 “Close what?”

One additional consideration comes from the following passage from Matuzovic (2020):

Sometimes it makes sense to use more descriptive labels like “Close dialog”, “Close gallery”, or “Close ad”.

So we need some flexibility in the value of aria-label, to make it reusable in different contexts. That means the aria-label value needs to be a prop of the React component.

2. React component

To reuse the above HTML structure whenever we render a close button, we can create a Reaxt component. Here‘s how I go about it.

2.1 ARIA attributes as props

To allow aria-label to differ, I make it as a prop:

export const CloseButton = ({ ariaLabel }) => {
  return (
    <button aria-label={ariaLabel} type="button">
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z" />
      </svg>
    </button>
  );
};

To make it explicit that aria-label is always required, I add PropTypes:

import PropTypes from "prop-types"; // ADDED

export const CloseButton = ({ ariaLabel }) => {
  return (
    <button
      aria-controls={ariaControls}
      aria-expanded={ariaExpanded}
      aria-label={ariaLabel}
      type="button"
    >
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z" />
      </svg>
    </button>
  );
};

// ADDED FROM HERE
CloseButton.propTypes = {
  ariaLabel: PropTypes.string.isRequired,
};
// ADDED UNTIL HERE

So, in case I forget giving the ariaLabel prop to the CloseButton component, React will complain in the JavaScript console. (Which indeed happened when I was creating a demo for this article with CodeSandbox.)

Maybe it’s time for me to start using TypeScript, though.

2.2 Click handler

Of course, we need to attach a click event handler to the <button> element so that the pressing of it will close something.

For this purpose, I add handleClick prop:

import PropTypes from "prop-types";

export const CloseButton = ({
  ariaLabel,
  handleClick, // ADDED
}) => {
  return (
    <button
      aria-label={ariaLabel}
      onClick={handleClick} // ADDED
      type="button"
    >
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z" />
      </svg>
    </button>
  );
};

CloseButton.propTypes = {
  ariaLabel: PropTypes.string.isRequired,
  clickHandler: PropTypes.string.isRequired, // ADDED
};

Again, I add the prop type so React will complain if I forget adding the clickHandler prop.

Now, let’s move on to style the close button.

3. CSS

3.1 Using Styled Components

To style React components, I always use Styled Components:

import PropTypes from 'prop-types';

import { Button } from '../styled-components/Button'; // ADDED

export const CloseButton = ({
  ariaLabel,
  handleClick
}) => {
  return (
    <Button // REVISED
      aria-label={ariaLabel}
      onClick={handleClick}
      type="button"
    >
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z" />
      </svg>
    </Button> {/* REVISED */}
  );
};

CloseButton.propTypes = {
  ariaLabel: PropTypes.string.isRequired,
  clickHandler: PropTypes.string.isRequired,
};

where the Button styled component is defined in a separate file:

// styled-components/Button.js

import styled from "styled-components";

export const Button = styled.button`
  /* CSS declarations to be inserted */
`;

In this file, let’s add CSS declarations to style the close button step by step.

3.2 Reset the default button style

The button element has a particular set of default style. I want to reset it first:

// styled-components/Button.js

import styled from "styled-components";

// ADDED FROM HERE
const resetStyle = `
  background-color: rgba(255, 255, 255, 0);
  border: none;
`;
// ADDED UNTIL HERE

export const Button = styled.button`
  ${resetStyle} /* ADDED */
`;

The kind of the close button that I’m after is minimally styled, just a cross mark icon without borders or solid background color.

For transparency, I always use the transparent white (i.e., rgba(255, 255, 255, 0)) rather than the named color keyword of transparent ever since I learned about cross-browser inconsistency: Safari interprets transparent as the transparent black (see Coyier 2017).

And I use a variable resetStyle to define a set of CSS declarations for code readability. This is what I like about CSS-in-JS.

3.3 Set clickable area

Next, let‘s shape the close button.

Although there is no border, when the keyboard user focuses it with the Tab key, I want it to show a circular focus ring, rather than a square one. The border-radius: 50%; does the job.

For the size of the button, Google recommends the 48x48 pixel area as a minimum touch target size, because:

“The 48x48 pixel area corresponds to around 9mm, which is about the size of a person’s finger pad area.” (Gash et al. 2020)

So the diameter of the button is set to be 48px.

Therefore, we have:

// styled-components/Button.js

import styled from 'styled-components';

...

// ADDED FROM HERE
const setClickableArea = `
  --minimum-target-size: 48px;
  border-radius: 50%;
  height: var(--minimum-target-size);
  width: var(--minimum-target-size);
`;
// ADDED UNTIL HERE

export const Button = styled.button`
  ${resetStyle}
  ${setClickableArea} /* ADDED */
`;

Using a CSS variable name (--minimum-target-size), I can embed the logic behind the numbers into the CSS code.

3.4 Center-align the icon

Now we need to position the SVG icon inside the clickable area. I want it to be center-aligned both vertically and horizontally. So I use flexbox:

// styled-components/Button.js

import styled from 'styled-components';

...

// ADDED FROM HERE
const centerAlignIcon = `
  align-items: center;
  display: flex;
  justify-content: center;
`;
// ADDED UNTIL HERE

export const Button = styled.button`
  ${resetStyle}
  ${setClickableArea}
  ${centerAlignIcon} /* ADDED */
`;

3.5 Style the icon

Now let’s style the icon:

// styled-components/Button.js

import styled from 'styled-components';

...

// ADDED FROM HERE
const styleIcon = `
  & svg {
    fill: var(--button-label-color-default);
    height: calc(var(--minimum-target-size) * 0.75);
    width: calc(var(--minimum-target-size) * 0.75);
  }
`;
// ADDED UNTIL HERE

export const Button = styled.button`
  ${resetStyle}
  ${setClickableArea}
  ${centerAlignIcon}
  ${styleIcon} /* ADDED */
`;

To specify the color of an SVG icon, we need the fill property. I use a CSS variable so it will switch between light and dark modes (see Dodds 2020 for how).

The SVG icon’s height and width are set to be three-quarters of the minimum target size of 48px, which makes the close button look decent when the focus ring appears around it. Rather than hard-coding 36px, using the calc() CSS function and the CSS variable of --minimum-target-size makes clear the logic behind the choice of 36px.

That’s all for the default style.

Notice that I don’t include any CSS code for positioning the close button at the top-right corner of a dialog. That’s the job for the CSS code of a dialog element (<div role="dialog>). We will see an example of it in the future article of this blog series.

4. Focus state style

4.1 Consistency with cloud buttons

On Day 7 of this blog series (see Section 8), I styled the focus ring for cloud-shaped buttons in a shade of blue rgb(69,159,189) and made it glow with drop-shadow(0 0 5px rgb(69,159,189)). Also, I made the button label's color change to rgb(3, 3, 3).

To achieve visual consistency, I want the close button to have the same focus ring. So the first attempt is something like this:

// styled-components/Button.js
import styled from 'styled-components';

...

// ADDED FROM HERE
const glowFocusRing = `
  border: 1px solid rgb(69, 159, 189);
  box-shadow: 0 0 5px rgb(69, 159, 189);
`;
const darkenButtonLabel = `
  fill: rgb(3, 3, 3);
`;
const supportHighContrastMode = `
  outline: 1px solid transparent;
`
const styleFocusState = `
  &:focus {
    ${glowFocusRing}
    ${supportHighContrastMode}
  }
  &:focus svg {
    ${darkenButtonLabel}
  }
`;
// ADDED UNTIL HERE

export const Button = styled.button`
  ${resetStyle}
  ${setClickableArea}
  ${centerAlignIcon}
  ${styleIcon}
  ${styleFocusState} /* ADDED */
`;

The above code gives us a focus ring like this:

4.2 Fallback for Windows High Contrast Mode

The above CSS code includes the declaration of outline: 1px solid transparent. This is for Windows High Contrast Mode, which removes the color of border and box shadow and instead renders any outline in solid white (even if it’s transparent). It’s becoming the norm (as far as I see) to include a transparent outline when the custom focus style involves border and box shadow. See Higley (2020) for detail.

An added bonus is that it also removes the default focus ring by overriding the outline property.

4.3 Remove focus style for touch device users and mouse users

The focus state style for a button is unnecessary for smartphone/tablet users and mouse users. We only need to style the focus state for keyboard users.

However, for all the browsers except Safari, the :focus pseudo selector gets activated when the button is clicked (as pointed out by Underhill 2021). So there will be a flash of the focus style when touch device users tap the button (or when mouse users click the button). That’s not desirable.

A solution is the :focus-visible pseudo selector which gets activated only when the button is focused with keyboard strokes. Underhill (2021) provides an excellent overview of :focus-visible.

But there is an issue of handling those “legacy” browsers (including the versions of Safari released before March 2022) that do not support :focus-visible. Consequently, we also need to use the :focus pseudo selector so that keyboard users with old devices won’t be ignored.

Lauke (2018) proposes to define the focus state style with :focus for legacy browsers and then to remove the focus state style with the following pseudo selector:

:focus:not(:focus-visible)

which refers to the clicking of a button by smartphone, tablet and mouse users.

Following this technique, I revise the previous code for styling the focus state as follows:

// styled-components/Button.js
import styled from 'styled-components';

...

const glowFocusRing = `
  border: 1px solid rgb(69, 159, 189);
  box-shadow: 0 0 5px rgb(69, 159, 189);
`;
const darkenButtonLabel = `
  fill: rgb(3, 3, 3);
`;
const supportHighContrastMode = `
  outline: 1px solid transparent;
`;

// ADDED FROM HERE
const removeFocusRing = `
  border: none;
  box-shadow: none;
`;
const resetButtonLabelColor = `
  fill: rgb(90, 90, 90);
`;
// ADDED UNTIL HERE

const styleFocusState = `
  &:focus {
    ${glowFocusRing}
    ${supportHighContrastMode}
  }
  &:focus svg {
    ${darkenButtonLabel}
  }

  /* ADDED FROM HERE */
  &:focus:not(:focus-visible) {
    ${removeFocusRing}
  }
  &:focus:not(:focus-visible) svg {
    ${resetButtonLabelColor}
  }
  /* ADDED UNTIL HERE */
`;

export const Button = styled.button`
  ${resetStyle}
  ${setClickableArea}
  ${centerAlignIcon}
  ${styleIcon}
  ${styleFocusState}
`;

where rgb(90, 90, 90) is the default color for button icons.

5. Active state style

The active state (or what Material Design calls the “pressed” state) is critical to tell the user whether the button is pressed or not. If the button doesn‘t visually respond to the user’s action, the user might think the app is not working, especially when the network connection is slow or the user’s device is slow (like my iPad Mini 2 bought in 2015).

For some reason, many web designers and web developers are not keen on styling the button active state. Lorenz (2019) showcases the CodePen demos of “Top 50 CSS Buttons”. When I click these buttons, very few of them clealry indicate that the button is indeed pressed.

5.1 Ripple effect

Today the most popular active state style is probably the ripple effect, popularized by Google with its Material Design.

And I follow this practice because, due to the popularity, the user can immediately tell what ripple animation means. Strictly speaking, it is not fully consistent with the design concept of my web app (see Day 2 of this blog series). For creating the minimum viable product, however, the ripple effect is good enough, and relatively easy to implement.

5.2 Adding the ripple to the DOM

Cameron (2020) provides a React code snippet for the ripple effect. Adapting this snippet, I first write down a function called createRipple:

// /utils/createRipple.js

export function createRipple(event) {
  const button = event.currentTarget;

  const diameter = Math.max(button.clientWidth, button.clientHeight);
  const radius = diameter / 2;

  const circle = document.createElement('span');

  circle.style.width = circle.style.height = `${diameter}px`;
  circle.style.left = `${event.offsetX - radius}px`;
  circle.style.top = `${event.offsetY - radius}px`;

  circle.classList.add('ripple');

  circle.addEventListener('animationend', () => button.removeChild(circle));

  button.appendChild(circle);
}

The core idea is to create a temporary <span> element as a child of the <button> element, to shape it as a circle, and to set its left and top CSS properties to be dependent on where the user clicks on the button (event.offsetX and event.offsetY). For more detail, see Cameron (2020).

Note that the above code is revised from the original snippet by Cameron (2020). I have incorporated a couple of comments to the article:

Gonzalez (2020) for the use of offsetX and offsetY
Jonas (2020) for removing the <span> element once animation is over.

5.3 Style the ripple

The above code attaches a class ripple to the <span> element. This class is used to style the ripple:

// /styled-components/Button.js
import styled, {css, keyframes} from 'styled-components'; // REVISED

...

// ADDED FROM HERE
const ripple = keyframes`
  to {
      transform: scale(4);
      opacity: 0;
    }
`;
const styleActiveState = css`
  overflow: hidden;
  position: relative;
  & .ripple {
    animation: ${ripple} 600ms linear;
    background-color: var(--ripple-color);
    border-radius: 50%;
    position: absolute;
    transform: scale(0);
  }
`;
// ADDED UNTIL HERE

export const Button = styled.button`
  ${resetStyle}
  ${setClickableArea}
  ${centerAlignIcon}
  ${styleIcon}
  ${styleFocusState}
  ${styleActiveState} /* ADDED */
`;

At the top of the code, I import the css and keyframes helper functions, which is necessary to use CSS animation with Styled Components. The keyframes is for defining animation, and the css is required whenever CSS declarations include the animation keyframe (see Styled Components Docs for detail).

The animation defined with keyframes involves transform and opacity properties. The <span> element is animated to scale from zero to four with transform: scale(). It’s not clear why four. But I follow Cameron (2020), who must have reached this magnic number by trial and error.

And opacity is animated from 1 (default) to 0, imitating the vanishing water ripples.

Animation duration is 600ms, which is another magic number from Cameron (2020). Animation easing is linear: water ripples move at a constant speed according to this Reddit discussion.

The color of the ripple is set with --ripple-color, which is defined (elsewhere in the code base) as rgba(3, 3, 3, 0.33) for light mode and rgba(255, 255, 255, 0.4) for dark mode. According to the Material Design guideline, the (initial) opacity of the ripple should be higher the darker the background.

Finally, the <button> element itself needs to be styled with

overflow: hidden;
position: relative;

so that the <span> element’s position is contained inside the button and that the ripple disappears when it hits the edges of the button.

5.4 Create the ripple on the click event

Then execute the createRipple function when the user clicks the button (but before executing the close button’s functionality given by the handleClick prop):

import PropTypes from 'prop-types';

import { Button } from '../styled-components/Button';

import { createRipple } from '../utils/createRipple'; // ADDED

export const CloseButton = ({
  ariaLabel,
  handleClick,
}) => {
  // ADDED FROM HERE
  const clickHandler = (event) => {
    createRipple(event);
    handleClick();
  };
  // ADDED UNTIL HERE

  return (
    <Button
      aria-label={ariaLabel}
      onClick={clickHandler} // REVISED
      type="button"
    >
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z" />
      </svg>
    </Button>
  );
};

CloseButton.propTypes = {
  ariaLabel: PropTypes.string.isRequired,
  clickHandler: PropTypes.string.isRequired,
};

The snippet by Cameron (2020) ends here. But I realize that there is one thing missing: handling the button click with a keyboard.

5.5 Handle keyboard users

The above code won’t create the ripple effect when keyboard users press the button with the Enter key.

Let’s assume that the button is pressed at its center in this case. So the createRipple function is revised as follows:

// /utils/createRipple.js

export function createRipple(event) {
  const button = event.currentTarget;

  const diameter = Math.max(button.clientWidth, button.clientHeight);
  const radius = diameter / 2;

  const circle = document.createElement('span');

  circle.style.width = circle.style.height = `${diameter}px`;

  // REVISED FROM HERE
  if (event.key === 'Enter') {
    circle.style.left = 0;
    circle.style.top = 0;
  } else {
    circle.style.left = `${event.offsetX - radius}px`;
    circle.style.top = `${event.offsetY - radius}px`;
  } 
  // REVISED UNTIL HERE

  circle.classList.add('ripple');

  circle.addEventListener('animationend', () => button.removeChild(circle));

  button.appendChild(circle);
}

Also the CloseButton component needs to be revised as follows:

import PropTypes from 'prop-types';

import { Button } from '../styled-components/Button';

import { createRipple } from '../utils/createRipple';

export const CloseButton = ({
  ariaLabel,
  handleClick,
}) => {
  const clickHandler = (event) => {
    createRipple(event);
    handleClick();
  };

  // ADDED FROM HERE
  const keydownHandler = (event) => {
    if (event.key === 'Enter') {
      event.preventDefault(); // otherwise click event will be fired as well
      createRipple(event);
      handleClick();
    }
  };
  // ADDED UNTIL HERE

  return (
    <Button
      aria-label={ariaLabel}
      onClick={clickHandler}
      onKeyDown={keydownHandler} // ADDED
      type="button"
    >
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z" />
      </svg>
    </Button>
  );
};

CloseButton.propTypes = {
  ariaLabel: PropTypes.string.isRequired,
  clickHandler: PropTypes.string.isRequired,
};

Demo

Here’s a CodeSandbox demo of what the code in this article achieves. Try to click the close button on the top right. It won’t close anything, but it does give you the UI feedback of the ripple effect!

References

Bellamy-Royds, Amelia (2015) “How to Scale SVG”, CSS-Tricks, Jan 6, 2015.

Cameron, Bret (2020) “How to Recreate the Ripple Effect of Material Design Buttons”, CSS-Tricks, Oct 12, 2020.

Coyier, Chris (2017) “A Thing To Know about Gradients and ‘Transparent Black’”, CSS-Tricks, Jan 10, 2017.

Dodds, Kent C. (2020) “Use CSS Variables instead of React Context”, Epic React, Oct 2020.

Gash, Dave, Meggin Kearney, Rachel Andrew, Rob Dodson, and Patrick H. Lauke (2020) “Accessible tap targets”, web.dev, Mar 31, 2020.

Gonzalez, Angelo (2020) “Awesome work! For anyone trying to apply this to absolute positioned elements...”, comment to CSS-Tricks, Oct 14, 2020.

Higley, Sarah (2020) “Quick Tips for High Contrast Mode”, sarahmhigley.com, May 26, 2020.

Jonas (2020) “Thanks for this nice article! One thing I did differently is...”, comment to CSS-Tricks, Oct 14, 2020.

Lauke, Patrick H. (2018) “:focus-visible and backwards compatibility”, TPGi, Mar 23, 2018.

Lorenz (2019) “Top 50 CSS Buttons (+ animations)”, Dev Community, Jun 9, 2019.

Matuzovic, Manuel (2020) “#20 HTMHell special: close buttons”, HTMHell, May 23, 2020.

Stanton, Benjy (2020) “Accessible close buttons”, benjystanton.co.uk, Apr 30, 2020.

Underhill, Martin (2021) “Refining focus styles with focus-visible”, tempertemper, May 25, 2021.

Day 17: Styling a search box like Google's

Masa Kudamatsu — Thu, 11 Aug 2022 10:00:00 +0000

TL;DR

To style a search box like the one on google.com, write the HTML and CSS code as in this CodePen demo that I’ve made. Then you'll have a user experience shown in the GIF animation below:

Intro

I’m making a web app that improves the user experience of Google Maps. Its core feature is to allow the user to save a place with their own note in the rich text format. (Google Maps only allows plain text notes.)

To save a place, the user first needs to search for that place on the map. Consequently, a search box is one of the essential UI components of the web app I’m making.

I want the search box to look like the one the user sees after visiting google.com: Google.com landing page (screenshot by the author)

Everyone is familiar with Google's search box appearance. By making my own app's search box resemble the one by Google, the user will immediately figure out that it is a search box, rather than the standard text field.

This is a UI design tip derived from what Jakob Nielsen claimed back in 2005:

”In user testing, people tell us that they want search on websites and intranets to work like X , where X is their favorite major search engine.” (Nielsen 2005)

The implementation of this UI design with HTML/CSS turns out to be rather tricky, however. This article describes the solution I’ve reached by trial and error. It involves various tips to style any search box. I hope it will be helpful for you one day.

Let's start with HTML.

1. HTML code for a search box

The semantic HTML element for a search box is <input type="search">. One benefit, compared to <input type="text">, is that Chrome and Safari users will see the delete button at the end of the search box once they enter text in it (Coyier 2021 and MDN Contributors 2022).

Chrome's search box delete button (Screenshot by the author)

Safari’s search box delete button (Screenshot by the author)

But a few more attributes need to be added to the <input> element:

<input
  aria-label="Search for a place on the map"
  autocomplete="off"
  inputmode="search"
  placeholder="Enter place name or address"
  type="search"
/>

First of all, I use aria-label to label the search box, to allow screen reader users to tell what the <input> element is for. I don't use <label> here, because a magnifying glass icon will play a role of the label for sighted users (cf. MDN Contributors 2022).

Second, I turn off the browser's default autocomplete feature with autocomplete="off". This is because I’m going to render Google Maps API’s autocomplete suggestions directly below the search box. The input element's own autocomplete suggestions would then overlap the suggestions from Google Maps.

Third, for smartphone users, the keyboard that appears after tapping the search box is altered with inputmode="search", which changes the return button label into something more appropriate for search. See Oliff (2019) for detail.

Finally, the placeholder attribute specifies the text to be shown in the search box before the user clicks it. For the text content, I follow MDN Contributors (2022), who recommends "a word or short phrase that demonstrates the expected type of data".

2. SVG code for a magnifying glass icon

I borrow a magnifying glass icon from Material Icons. Downloading an SVG file and removing unnecessary pieces of code in it, I get this:

<svg aria-hidden="true" viewBox="0 0 24 24">
  <path
    d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"
  />
</svg>

I've added aria-hidden="true", because there is no point telling the presence of a magnifying glass icon to screen reader users. They know what the element is for, by listening to its aria-label attribute value (see Section 1 above).

3. Wrapping the `<svg>` and `<input>` elements with a `<div>`

Google puts the magnifying glass icon inside of the search box. To follow this UI design, the icon needs to be “absolutely positioned” relative to the search box.

For this purpose, we need to wrap the <input type="search"> and <svg> elements with a <div> element that is going to be "relatively positioned". (See Section 7 below for detail.)

Let the <div>’s class name is searchbox. So the entire HTML code is as follows:

<div class="searchbox">
  <svg aria-hidden="true" viewBox="0 0 24 24">
    <path
      d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"
    />
  </svg>
  <input
    aria-label="Search for a place on the map"
    autocomplete="off"
    inputmode="search"
    placeholder="Enter place name or address"
    type="search"
  />
</div>

Now it's time to work on CSS.

CSS stylesheets are often difficult to maintain, because you will for sure forget what role each CSS declaration plays in the construction of UI.

To ease this difficulty, I chunk CSS declarations by purpose. Let's start with the color palette.

4. Setting up the color palette

I use three colors to style the search box.

Dark gray for the search box's border, the magnifying glass icon, and the user's input text
Light gray for the placeholder text
Light blue for the search box's border when it is focused.

Set these colors as CSS variables at the root element so other UI components elsewhere in the web app may also use them:

html {
  --dark-gray: rgb(90, 90, 90);
  --light-gray: rgb(148, 148, 148);
  --focus-blue: rgb(69, 159, 189);
}

5. Shaping the search box

Next, I’m going to shape the search box, by setting its size and drawing the border.

5.1 Deriving the height from a minimum touch target size

The search box's height needs to be large enough that the user will find it easy to tap to start typing text in it.

Google recommends the 48x48 pixel area as a minimum touch target size, because:

“The 48x48 pixel area corresponds to around 9mm, which is about the size of a person's finger pad area.” (Gash et al. 2020)

So I use 48px for the height of <input type="search">.

.searchbox {
  --target-size: 48px;
  --box-height: var(--target-size);

  height: var(--box-height);
}
.searchbox input[type='search'] {
  height: 100%;
}

Here I use CSS variables to record the reasoning behind styling so that my future self will quickly understand the CSS code written a long while ago.

I could directly set height for <input[type="search"]>. But it's not intuitive, at least for me, to guess the parent element's height from its children. I prefer defining height for the parent and letting it cascade down the DOM tree.

5.2 Drawing the search box's border

The border width of a search box is, in my view, best set to be 2px. A 1px border is too thin for the user to notice the search box. Being thicker than 2px will make the search box look unsophisticated.

Let's draw the border now:

.searchbox {
  --target-size: 48px;
  --box-height: var(--target-size);
  --border-width: 2px; /* ADDED */

  height: var(--box-height);
}
.searchbox input[type='search'] {
  border: var(--border-width) solid var(--dark-gray); /* ADDED */
  height: 100%;
}

To replicate Google's search box shape, the both sides of the box need to be semi-circles. That is, border-radius needs to be half the height of the box:

.searchbox {
  --target-size: 48px;
  --box-height: var(--target-size);
  --border-width: 2px;
  --border-radius: calc(var(--box-height) / 2); /* ADDED */

  height: var(--box-height);
}
.searchbox input[type='search'] {
  border: var(--border-width) solid var(--dark-gray);
  border-radius: var(--border-radius); /* ADDED */
  height: 100%;
}

I define the border radius as a CSS variable, because this value will be used for another purpose later (see Section 7.2 below).

5.3 Setting the width of the search box

For mobile devices, the search box should be as wide as possible, with some side margins to keep a distance from the screen edges.

For wide screens like laptops, however, the search box shouldn't be as wide as screens, just like the paragraphs of text shouldn't. A very long line of text is difficult to read.

Given this consideration, the use of max-width is appropriate to set the width of a search box.

Google's search box is 561px wide for widest screens. I don't know where this magic number comes from. But I just follow this “convention”:

.searchbox {
  --target-size: 48px;
  --box-height: var(--target-size);
  --border-width: 2px;
  --border-radius: calc(var(--box-height) / 2);

  height: var(--box-height);
  max-width: 561px; /* ADDED */
}
.searchbox input[type='search'] {
  border: var(--border-width) solid var(--dark-gray);
  border-radius: var(--border-radius);
  height: 100%;
  width: 100%; /* ADDED */
}

The width of <input type="search"> has to be 100%, to override the browser's default style.

6. Styling the sub-components of our search box

Our search box has two sub-components: the magnifying glass icon and the search box text.

The standard approach would be to assign a class to each sub-component to define its style, like searchbox__icon in the BEM convention.

But I’d rather use the descendant combinator, that is,

.searchbox svg {
  /* Style for the magnifying glass icon */
}
.searchbox input[type='search'] {
  /* Style for the search box text */
}

This way, the CSS code self-explains that the set of CSS declarations is defined for a subcomponent of the search box, rather than an independent component. It also saves me from the hassle of coming up with extra class names. Naming is the hardest thing to do in coding.

6.1 Styling the magnifying glass icon

By trial and error, I’ve reached a conclusion that the magnifying glass icon looks best when it's sized three-quarters of the search box's height:

.searchbox {
  --icon-size: calc(var(--box-height) * 3 / 4);
}
.searchbox svg {
  fill: var(--dark-gray);
  height: var(--icon-size);
  width: var(--icon-size);
}

With the fill property, I match the icon color with the search box border.

6.2 Styling the search box text

The <input> element does not inherit the font property values from its parent. So we need to define the font style explicitly.

.searchbox input[type='search'] {
  -webkit-appearance: none; /* for Safari */
  color: var(--dark-gray);
  font-family: 'Noto Sans', Verdana, sans-serif;
  font-size: 1rem;
}

Safari ignores font-size for <input type="search">. To disable this behavior, we need -webkit-appearance: none. See Coyier (2021).

The text color is set so it will match the icon color as well as the search box border color.

We also need to style the placeholder text. The font style gets inherited; but the text color does not. To style the placeholder text, use the ::placeholder pseudo element:

.searchbox input[type='search']::placeholder {
  color: var(--light-gray);
  opacity: 1;
}

If the placeholder text has the same color as the search box border, it can give a wrong impression that text is already filled in. A convention is that the placeholder text is in a lighter shade of gray than the search box border.

But the color property alone isn't enough. Firefox's default style makes the placeholder text translucent. The opacity: 1 corrects this.

As we've seen by now, the default style of <input type="search"> is inconsistent across browsers in an unexpected way. This makes it tricky to style a search box. We'll see more examples of it below.

7. Positioning the icon and the text field within the search box

The next step is to adjust the positioning of sub-components inside the search box.

7.1 Placing the icon inside the box

I need to overlap the icon above the search box. The standard CSS technique for overlapping is the relatively-absolute positioning (see James 2017 for a beginner-friendly introduction):

.searchbox {
  position: relative;
}
.searchbox svg {
  position: absolute;
}

This is why I had to wrap the icon and the search box with a <div> element (see Section 3 above).

7.2 Horizontal spacing

Now let's set the horizontal margins. First, I want the icon to sit half the border radius from the left edge of the search box:

.searchbox {
  --side-margin: calc(var(--border-radius) / 2); /* ADDED */

  position: relative;
}
.searchbox svg {
  position: absolute;
  left: var(--side-margin); /* ADDED */
}

Then, I want the icon to be optically center-aligned between the left edge of the search box and the left edge of the text in the search box (placeholder text or user input text).

.searchbox {
  --side-margin: calc(var(--border-radius) / 2);
  position: relative;
}
.searchbox svg {
  position: absolute;
  left: var(--side-margin);
}
/* ADDED from here */
.searchbox input[type='search'] {
  padding-left: calc(var(--side-margin) + var(--icon-size) + 4px);
}

Optical center-alignment is an important technique for graphic designers. Most characters and icons have a different amount of white space on each side. For the magnifying glass icon, it has more white space to its right, because the thin handle sticks out to its bottom-right. For human eyes to see the icon center-aligned, then, we need less white space to the right of the icon.

By trial and error, I find 4px is the magic number for the right-hand white space to achieve the optical center-alignment of the icon.

To implement this spacing, we need to set the value of padding-left to be the sum of the icon's width and its side margins. This is why I have the following CSS declaration:

padding-left: calc(var(--side-margin) + var(--icon-size) + 4px);

Finally, I need to set the space between the right edge of the search box and the end of text (or the delete button which appears in Chrome and Safari once the user enters text; see Section 10 below for detail).

A symmetric appearance always looks decent to our eyes. So I go for the same amount of space as the left margin for the icon:

.searchbox {
  --side-margin: calc(var(--border-radius) / 2);
  position: relative;
}
.searchbox svg {
  position: absolute;
  left: var(--side-margin);
}
.searchbox input[type='search'] {
  padding-left: calc(var(--side-margin) + var(--icon-size) + 4px);
  padding-right: var(--side-margin); /* ADDED */
}

The above CSS code works perfect except for Safari, which inserts a little horizontal space to the left of the text field. The padding property does not override this spacing.

A solution to this is provided by Lines 136-138 of RESS, a modern CSS reset stylesheet by Linhares (2022):

input[type='search']::-webkit-search-decoration {
  -webkit-appearance: none;
}

The <input type="search"> has a few obscure pseudo elements for Webkit browsers like this one (Peter 2010). We'll see another one in action in Section 10 below.

7.3 Vertical spacing

I want the magnifying glass icon to be vertically center-aligned within the search box.

Usually, the flexbox is the easiest way to vertically center-align items. In my case, however, I use the relatively-absolute positioning technique for the icon. So it's best to set the top and bottom values to be equal:

.searchbox {
  --side-margin: calc(var(--border-radius) / 2);
  --icon-vertical-margin: calc(
    (var(--box-height) - var(--icon-size)) / 2
  ); /* ADDED */

  position: relative;
}
.searchbox svg {
  position: absolute;
  left: var(--side-margin);
  top: var(--icon-vertical-margin); /* ADDED */
  bottom: var(--icon-vertical-margin); /* ADDED */
}

We tend to think that styling is done by now. For interactive elements like a search box, however, there is one more important thing to style: the focus state.

8. Styling focus state

8.1 Using border and box-shadow to style the focus ring

The focus ring is usually styled with the outline property. But I want the focus ring to glow, as in Coyier (2012)'s code snippet, like this:

To achieve this style, I use the combination of border and box-shadow:

.searchbox input[type='search']:focus {
  border-color: var(--focus-blue);
  box-shadow: 0px 0px 5px var(--focus-blue);
}

When we style the focus ring with properties other than outline, however, Soueidan (2021) recommends adding a transparent outline as a fallback for Forced Color Modes, which will remove the focus ring styled with background, border, and/or box-shadow properties. Following her suggestion, I add:

.searchbox input[type='search']:focus {
  border-color: var(--focus-blue);
  box-shadow: 0px 0px 5px var(--focus-blue);
  outline: 1px solid transparent; /* ADDED */
}

Explicitly styling the outline property has an additional benefit: it removes the browser's default focus ring, which is usually done with outline: none.

9. Allowing user to tap the icon for focusing the search box

At this point, styling the search box is essentially done. However, I notice one thing unsatisfactory.

When I click the magnifying glass icon, expecting the search box to be focused, nothing actually happens. This is because the magnifying glass icon is rendered on top of the search box, preventing the user from tapping the search box.

To solve this issue, the icon needs to be rendered beneath the search box:

.searchbox svg {
  z-index: -1;
}
.searchbox input[type='search'] {
  background: transparent;
}

Since <div class="searchbox"> is relatively positioned (see Section 7 above), it creates its own stacking context (Comeau 2022). By setting z-index to be -1, the <svg> element goes beneath all the child elements of the <div> (i.e. the <input type="search"> in our case).

But the <input> element, by default, has a white background, hiding the <svg> element beneath. So we need to make it transparent.

Limitations

This solution won't work if the search box needs a distinct background color, though.

If you know an alternative solution that allows a non-transparent background for the search box, please let me know.

10. Customizing the text delete button style for Chrome and Safari

As described in Section 1 above, one benefit of using <input type="search"> instead of <input type="text"> is that, once the user enters text, Chrome and Safari will render a delete button in the search box so the user can delete the entire text by clicking it.

But the default style of the delete button differs between Chrome and Safari, and it is inconsistent with the rest of my web app's design.

Chrome's search box delete button (Screenshot by the author)

Safari’s search box delete button (Screenshot by the author)

To customize the style of the delete button, we can use the ::-webkit-search-cancel-button pseudo element (Coyier (2010)):

.searchbox input[type='search']::-webkit-search-cancel-button {
  /* Remove default */
  -webkit-appearance: none;
  /* Now your own custom styles */
  background-image: url("data:image/svg+xml, %3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='rgb(148, 148, 148)' %3E%3Cpath d='M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z' /%3E%3C/svg%3E%0A");
  height: calc(var(--box-height) / 2);
  width: calc(var(--box-height) / 2);
}

First, remove the browser's default style with -webkit-appearance: none;. Then, we can use the background, height, and width properties to shape our own delete button.

In the above CSS code, I use an SVG image of the cross icon from Material Icons. I edit the SVG code so that the color of the icon is set with fill="rgb(148, 148, 148)".

Then, following Coyier (2013), I convert the SVG code into a Data URL to be used as a background-image value, by using the URL-encoder for SVG.

Finally, I scale the icon to half the size of the search box's height.

Limitations

This approach works if we do not need to care about the dark mode. To switch the color between light and dark modes, we need to replace the entire data URL. This requires quite a bit of code duplication.

If you know a better approach to customize the delete button, please let me know.

11. Removing the flash of gray background when tapping the search box on iOS Safari

Here's one final gotcha of a search box. This time, it's iOS Safari.

By default, <input type="search"> will flash the grey background when the user taps it on iOS Safari. This is unnecessary, because tapping a search box will prompt the appearance of a keyboard at the bottom of the screen. We do not need an additional feedback to the user for indicating that the search box is now ready to be typed in.

To disable this feature, use an obscure Webkit-specific CSS property:

input[type='search'] {
  -webkit-tap-highlight-color: transparent;
}

See Apple Developer (2016) for detail.

Final words

That's all about styling a search box like Google's. Here's the demo with CodePen.

I’m surprised by the sheer number of things to remember for styling a very simple search box...

References

Comeau, Josh W. (2022) “What the heck, z-index??”, joshwcomeau.com, Jan 27, 2022.

Coyier, Chris (2010) “WebKit HTML5 Search Inputs”, CSS-Tricks, Aug 25, 2010.

Coyier, Chris (2012) “Glowing Blue Input Highlights”, CSS-Tricks, Apr 11, 2012.

Coyier, Chris (2013) “Using SVG”, CSS-Tricks, Mar 5, 2013.

Coyier, Chris 2021 “What do you get for using a search input type?”, CSS-Tricks, Nov 17, 2021.

Gash, Dave, Meggin Kearney, Rachel Andrew, Rob Dodson, and Patrick H. Lauke (2020) “Accessible tap targets”, web.dev, Mar 31, 2020.

James, Oliver (2017) “Advanced Positioning”, Interneting Is Hard, 2017.

Linhares, Filipe (2022) “ress”, GitHub, last updated on Mar 9, 2022.

MDN Contributors (2022) “”, MDN Web Docs, last modified on Aug 9, 2022.

Nielsen, Jakob (2005) “Mental Models For Search Are Getting Firmer”, Nielsen Norman Group, May 8, 2005.

Oliff (2019) “Everything You Ever Wanted to Know About inputmode”, CSS-Tricks, May 17, 2019.

Peter 2010 “It's not enough. To get rid of superfluous padding, you need...”, CSS-Tricks, Aug 26, 2010.

Soueidan, Sara (2021) “A guide to designing accessible, WCAG-compliant focus indicators”, sarasoueidan.com, Aug 13, 2021.

DEV Community: Masa Kudamatsu

Vanilla JS carousel that is accessible, swipeable, infinite-scrolling, and autoplaying

TL;DR

Why do I write this article?

1. HTML for accessibility

1.1 Carousel container

1.2 Slide wrapper

1.3 Slide containers

1.4 Slide content

1.5 Navigation dots

2. CSS for swiping to slide

2.1 Setting each slide width

2.2 CSS Scroll Snap for slides

2.3 Disable scroll bars

3. CSS and JS for Navigation Dots

3.1 Positioning navigation dots

3.2 Styling each navigation dot

3.3 Dynamic styling

3.4 JS for click event handler

3.5 Smooth scrolling

3.6 JS for dynamically styling navigation dots

3.7 Responsive design

4. JS for infinite-scrolling

4.1 Duplicating slides

4.2 Instantly scrolling back/forward to the original

4.3 Initial slide

4.4 Why not jump-link navigation dots?

5. JS for autoplay

5.1 Moving to next slide

5.2 Starting to autoplay

5.3 Stopping autoplay

5.4 Intersection Observer

5.5 Togging autoplay for mouse users

5.6 Togging autoplay for keyboard users

5.7 Togging autoplay for touch device users

5.8 Toggling autoplay for window resizing

Last words

Changelog

References

Responsive images: DIY implementation in 6 steps

TL;DR

Why writing this article?

Step 1: Maximum image width

Step 2: Image file conversion (Part I)

Enough to deal with 2x screens only

Image resizing tools

Step 3: Draft HTML code

Temporary sizes value

Go with w descriptor, not x descriptor

Use src for a fallback image file

How sizes and srcset work

Step 4: RespImageLint

Step 5: Revise HTML code

Step 6: Image file conversion (Part II)

Changelog

References

Day 26: Integrating Google Maps search with a React app

TL;DR

1. Introduction

2. Making an API call to Google Maps server

2.1 Vanilla JavaScript version

2.2 Adapting to React

2.3 Handling successful responses

2.4 Handling error responses

3. Dropping a place mark on the map

3.1 Specify the location

3.2 Snap the map to the searched place

3.3 Remove the marker for the previously searched place

3.4 Customize the marker

4. Showing the place detail

4.1 React state for place data

4.2 Render the place data in a popup window

4.3 Close the place detail popup

4.4 Reopen the popup by pressing the place mark

5. Final words

No demo available...

References

Day 25: Adding Google Maps autocomplete search to a React app

TL;DR

1. Introduction

Temporary `sizes` value

Go with `w` descriptor, not `x` descriptor

Use `src` for a fallback image file

How `sizes` and `srcset` work

3.3 `<input>` element markup

3.4 `<ul>` element markup

3.6 `<li>` element markup