Javascript

Deploying Multiple Apps From a Monorepo to GitHub Pages

Published Jan 24, 2024

Updated Jan 24, 2024

4 min read

Deploying Multiple Apps from a Monorepo to GitHub Pages

When it comes to deploying static sites, GitHub Pages is a popular solution thanks to being free and easy to set up in CI. The thing is, however, while it's perfectly suited for hosting a single application, such as a demo of your library, it does not support hosting multiple applications out of the box. It kind of just expects you to have a single app in your repository.

It just so happened I ended up with a project that originally had a single app deployed to GitHub Pages via a GitHub Actions workflow, and I had to extend it to be a monorepo with multiple apps. Once a second app was deploy-worthy, I had to figure out how to deploy it to GitHub Pages as well. As I found myself struggling a little bit while figuring out the best way to do it, I decided to write this post to share my experience and hopefully help someone else with a similar problem.

The Initial Setup

Initially, the project had a GitHub Actions workflow to test, build, and deploy the single app to GitHub Pages. The configuration looked something like this:

name: Build and deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ['main']

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Instal deps and run unit tests
        run: |
          npm ci
          npm run test

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: [unit-tests]
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Build
        run: |
          npm ci
          npm run build
      - name: Setup Pages
        uses: actions/configure-pages@v2
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: 'dist/my-app'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

The URL structure for GitHub Pages is [your-organization-name].github.io/[your-repo-name], which means on a merge to the main branch, this action deployed my app to thisdot.github.io/my-repo.

Accommodating Multiple Apps

As I converted the repository to an Nx monorepo and eventually developed the second application, I needed to deploy it to GitHub Pages too.

I researched some options and found a solution to deploy the apps as subdirectories. In the end, the changes to the workflow were not very drastic. As Nx was now building my apps into the dist/apps folder alongside each other, I just had to update the build step to build both apps and the upload step to upload the dist/apps directory instead of the dist/my-app directory. The final workflow at this point looked like this:

name: Build and deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ['main']

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install dependencies and run unit tests
        run: |
          npm ci
          nx run app1:test
          nx run app2:test

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: [unit-tests]
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Build app1
        run: |
          nx run app1:build
      - name: Build app2
        run: |
          nx run app2:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: 'dist/apps'
      - name: Setup Pages
        uses: actions/configure-pages@v2
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

And that seemed to work fine. The apps were deployed to thisdot.github.io/my-repo/app1 and thisdot.github.io/my-repo/app2 respectively. But, then I noticed something was off...

Addressing Client-Side Routing

My apps were both written with React and used react-router-dom. And as GitHub Pages doesn't support client-side routing out of the box, the routing wasn't working properly and I've been getting 404 errors.

One of the apps had a workaround using a custom 404.html from spa-github-pages. The script in that file redirects all 404s to the index.html, preserving the path and query string. But that workaround wasn't working anymore at this point, and adding it to the second app didn't work either.

The reason why it wasn't working was that the 404.html wasn't in the root directory of the GitHub pages for that repository, as the apps were now deployed to subdirectories. So, the 404.html was not being picked up by the server. I needed to move the 404.html to the root directory of the apps.

I moved the 404.html to a shared folder next to the apps and updated the build script to copy it to the dist/apps directory alongside the two app subdirectories:

      - name: Move 404.html
        run: |
          mv dist/apps/app1/404.html dist/apps/404.html

So the whole workflow definition now looked like this:

name: Build and deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ['main']

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install dependencies and run unit tests
        run: |
          npm ci
          nx run app1:test
          nx run app2:test

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: [unit-tests]
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Build app1
        run: |
          nx run app1:build
      - name: Build app2
        run: |
          nx run app2:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: 'dist/apps'
      - name: Setup Pages
        uses: actions/configure-pages@v2
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

Another thing to do was to increase the segmentsToKeep variable in the 404.html script to accommodate the app subdirectories:

var pathSegmentsToKeep = 2;

Handling Truly Missing URLs

At this point, the routing was working fine for the apps and I thought I was done with this ordeal. But then someone mistyped the URL and the page just kept redirecting to itself and I was getting an infinite loop of redirects. It just kept adding ?/&/~and~/~and~/~and~/~and~/~and~/~and~ over and over again to the URL. I had to fix this.

So I dug into the 404.html page and figured out, that I'll just check the path segment corresponding to the app name and only execute the redirect logic for known app subdirectories. So I added a allowedPathSegments array and check if the path segment matches one of the allowed ones:

// allowed subdirectories
var allowedPathSegments = ['app1', 'app2'];

// if the current URL is for an allowed subdirectory, redirect to it
var shouldRedirect =
    pathSegments.length > pathSegmentsToKeep &&
    allowedPathSegments.indexOf(pathSegments[pathSegmentsToKeep]) !== -1;
if (shouldRedirect) {
    // existing redirect code
}

At that point, the infinite redirect loop was gone. But the 404 page was still not very helpful. It was just blank.

So I also took this opportunity to enhance the 404.html to list the available apps and provide some helpful information to the user in case of a truly missing page.

I just had to add a bit of HTML code into the body:

  <div id="not-found-content" style="display: none">
   <h1>404</h1>
   <p>This page not found. Looks like such an app doesn't exist.</p>
   <p>Here is a list of apps we have:</p>
   <ul id="app-list"></ul>
  </div>

And a bit of javascript to populate the list of apps and show the content:

  if (shouldRedirect) {
    // existing redirect code
   } else {
    // populate the app list and show the not-found content
    document.addEventListener('DOMContentLoaded', function () {
     var appList = document.getElementById('app-list');
     allowedPathSegments.forEach(function (segment) {
      var listItem = document.createElement('li');
      var link = document.createElement('a');
      link.href = `/my-repo/${segment}`;
      link.textContent = segment.charAt(0).toUpperCase() + segment.slice(1);
      listItem.appendChild(link);
      appList.appendChild(listItem);
     });
     document.getElementById('not-found-content').style.display = 'block';
    });
   }

Now, when a user mistypes the URL, they get a helpful message and a list of available apps to choose from. If they use one of the available apps, the routing works as expected. This is the final version of the 404.html page:

<!DOCTYPE html>
<html>
 <head>
  <meta charset="utf-8" />
  <title>Single Page Apps for GitHub Pages</title>
  <script type="text/javascript">
   // Single Page Apps for GitHub Pages
   // MIT License
   // https://github.com/rafgraph/spa-github-pages
   // This script takes the current url and converts the path and query
   // string into just a query string, and then redirects the browser
   // to the new url with only a query string and hash fragment,
   // e.g. https://www.foo.tld/one/two?a=b&c=d#qwe, becomes
   // https://www.foo.tld/?/one/two&a=b~and~c=d#qwe
   // Note: this 404.html file must be at least 512 bytes for it to work
   // with Internet Explorer (it is currently > 512 bytes)

   // If you're creating a Project Pages site and NOT using a custom domain,
   // then set pathSegmentsToKeep to 1 (enterprise users may need to set it to > 1).
   // This way the code will only replace the route part of the path, and not
   // the real directory in which the app resides, for example:
   // https://username.github.io/repo-name/one/two?a=b&c=d#qwe becomes
   // https://username.github.io/repo-name/?/one/two&a=b~and~c=d#qwe
   // Otherwise, leave pathSegmentsToKeep as 0.
   var pathSegmentsToKeep = 2;

   var allowedPathSegments = ['app1', 'app2'];

   var l = window.location;

   var pathSegments = l.pathname.split('/');

   var shouldRedirect =
    pathSegments.length > pathSegmentsToKeep &&
    allowedPathSegments.indexOf(pathSegments[pathSegmentsToKeep]) !== -1;

   if (shouldRedirect) {
    l.replace(
     l.protocol +
      '//' +
      l.hostname +
      (l.port ? ':' + l.port : '') +
      l.pathname
       .split('/')
       .slice(0, 1 + pathSegmentsToKeep)
       .join('/') +
      '/?/' +
      l.pathname
       .slice(1)
       .split('/')
       .slice(pathSegmentsToKeep)
       .join('/')
       .replace(/&/g, '~and~') +
      (l.search ? '&' + l.search.slice(1).replace(/&/g, '~and~') : '') +
      l.hash,
    );
   } else {
    document.addEventListener('DOMContentLoaded', function () {
     var appList = document.getElementById('app-list');
     allowedPathSegments.forEach(function (segment) {
      var listItem = document.createElement('li');
      var link = document.createElement('a');
      link.href = `/my-repo/${segment}`;
      link.textContent = segment.charAt(0).toUpperCase() + segment.slice(1);
      listItem.appendChild(link);
      appList.appendChild(listItem);
     });
     document.getElementById('not-found-content').style.display = 'block';
    });
   }
  </script>
 </head>
 <body>
  <div id="not-found-content" style="display: none">
   <h1>404</h1>
   <p>This page was not found. Looks like such an app doesn't exist.</p>
   <p>Here is a list of apps we have:</p>
   <ul id="app-list"></ul>
  </div>
 </body>
</html>

Conclusion

Deploying multiple apps from an Nx monorepo to GitHub Pages required some adjustments, both in the GitHub Actions workflow and in handling client-side routing. With these changes, I was able to deploy and manage two apps effectively and I should be able to deploy even more apps in the future if they get added to the monorepo.

And, while the changes were not very drastic, it wasn't easy to find information on the topic and figure out what to do. That's why I decided to write this post. and I hope it will help someone else with a similar problem.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Jan Kaiser
Software engineer passionate about everything web-related. Particularly loves Angular, SCSS, TypeScript, soccer and dachshunds
@honzikec @honzikec

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

Introduction In the world of software development, GitHub workflows are crucial for automating CI/CD processes. However, a key challenge emerges when these workflows report a 'success' despite underlying issues, like failed tests. This is especially common in scenarios involving tests (e.g., Cypress) and notifications (e.g., Slack) within the same workflow. This blog post aims to highlight the importance of accurate GitHub workflow statuses for better visibility and team response, and how to ensure your workflows reflect the true outcome of their runs. The Problem with Misleading Workflow Statuses Consider a scenario in a GitHub workflow where end-to-end tests are run using Cypress. ` If these tests fail, but the workflow proceeds to a subsequent step, like sending a notification via Slack, which completes successfully, the entire workflow might still show a green checkmark. This misleading success status suggests everything is functioning as intended, when in fact, there could be significant underlying issues. The core issue is the determination of workflow success. Even if critical steps like testing fail, later steps without errors can override this, resulting in a false sense of security. This not only delays bug detection but can also lead to faulty code advancing in the CI/CD pipeline. It's crucial for the overall workflow status to accurately reflect failures in critical steps to ensure prompt and appropriate responses to issues. Crafting a Solution and Best Practices Ensuring Accurate Status Reporting To address the issue of misleading workflow statuses, it’s essential to configure your GitHub Actions properly. The goal is to ensure that the workflow accurately reflects the success or failure of critical tasks, such as running tests, regardless of the success of subsequent steps. Adjusting the Workflow Conditional Notifications: First, set up notifications to execute conditionally based on the outcome of critical steps. This ensures you're alerted of the workflow status without altering the overall result. For example, sending a Slack message if a Cypress test fails: ` Explicit Failure Handling: After configuring conditional notifications, explicitly handle failure scenarios. If a critical step like a Cypress test fails, force the workflow to exit with a failure status. This step is crucial to ensure that the overall workflow reflects the true status: ` Best Practices: Clear Step Separation: Clearly separate and label each step in your workflow for easier readability and troubleshooting. Regular Reviews: Periodically review your workflows to ensure they are aligned with the latest project requirements and best practices. Document Workflow Logic: Maintain documentation for your workflows, especially for complex ones, to aid in understanding and future modifications. By first setting up conditional notifications and then enforcing explicit failure handling, you maintain both alertness to issues and accuracy in workflow status. This approach ensures that failures in critical steps like tests are not overshadowed by subsequent successful steps, keeping the reported status of your workflow true to its actual state. Conclusion Accurate GitHub workflow statuses are vital for a transparent and efficient CI/CD process. By implementing conditional notifications and explicit failure handling, we ensure that our workflows truthfully represent the success or failure of critical tasks. This not only fosters better issue awareness and response but also upholds the integrity of our development practices. Embrace these steps as part of your commitment to maintaining clear and reliable automation processes in your projects. Happy coding!...

Mar 22, 2024

3 mins

GitHubGit

Improving INP in React and Next.js

Improving INP in React and Next.js In one of my previous articles, I've explained what INP is, how it works, and how it may affect your website. I also promised you to follow up with more concrete advice on how to improve your INP in your favorite framework. This is the follow-up article, where I'll focus on how to improve your INP score in React and Next.js. How to prepare for INP in React and Next.js? The first thing to do is to ensure you're using the latest version of React. The React team has been working on making React more INP-friendly and has already made some improvements in the latest versions. To enhance your INP score, consider fully taking advantage of new features introduced in React 18, such as Concurrent Rendering, Automatic Batching, and Selective Hydration. However, there are also some general areas to focus on, such as SSR and SSG in Next.js, Web Workers, or optimizing your hooks and state management. Concurrent Rendering The Concurrent Mode in React uses an algorithm that breaks rendering down into so-called "fiber nodes" and schedules the renders based on their expiration and priority. This effectively allows the user to interact with the page while the rendering is still in progress. In previous React versions, all updates, such as setState calls were treated as "urgent" and once the re-render had started, there was no way to interrupt it. Concurrent Mode changes this by being able to prioritize the updates and interrupt a non-blocking state update started with startTransition. For a simple explanation of concurrency in React, you can check out Dan Abramov's explanation. As part of the Concurrent Mode, React introduced several lifecycle methods that allow you to prioritize the rendering of certain parts of your UI, such as: - useTransition hook that allows you to update the state without blocking the UI, - useDeferredValue hook that allows you to defer the rendering of certain parts of your UI, - startTransition API that, similarly to the useTransition hook lets you mark a state update as non-blocking. It lacks, however, an indication of whether it's still pending. Automatic Batching Introduced in React 18, Automatic Batching reduces the number of re-renders that happen on state changes even when they happen outside of event handlers, e.g. in a setTimeout or Promise callback. This feature comes out of the box and you don't have to do anything to enable it, and it makes a great argument for upgrading to React 18. Selective Hydration Selective Hydration allows you to take hydration off the main thread by wrapping your components in a Suspense boundary. This way, components can become interactive faster as the browser can do other work on the main thread while the hydration is happening. To fully take advantage of selective hydration, consider the following: - Prioritizing Above-the-Fold Content: Use Suspense boundaries strategically around any parts of your application that may take the server longer to deliver to ensure they don’t block critical content from becoming interactive as soon as possible. - Hydration on Interaction: Implementing hydration upon user interaction for non-critical components can drastically reduce the main thread's workload, enhancing INP. Vercel even has a small case study showing how using selective hydration improved the performance of a Next.js site. Server-Side Rendering (SSR) and Static Site Generation (SSG) in Next.js Not everything has to run client-side. Next.js excels in SSR and SSG capabilities, which can significantly impact INP by delivering content to users faster. Optimizing SSR with techniques like incremental static regeneration (ISR) or leveraging SSG for static pages ensures that users can interact with content faster, improving the perceived performance. Workers Offloading heavy computations to Web Workers can free up the main thread, enhancing the responsiveness of React and Next.js applications. This strategy is especially useful when dealing with third-party scripts. Offloading such scripts in Next.js can be easily done by specifying the "worker" strategy on your Script component. Be aware that this feature is not yet stable and does not work with the app directory, though. If you want to take things one step further, you could use Partytown, which helps you offload any resource-intensive scripts to Web Workers. It comes with a React component that you can use to wrap your third-party scripts and offload them to a Web Worker, and it's compatible with Next.js as well. Hooks and State Management State management in React applications can easily get out of hand, leading to unnecessary re-renders and effectively an increased INP. Sometimes, using a state management library like Redux or MobX can help you consolidate your state and reduce the number of re-renders. However, they are not silver bullets and can also introduce performance issues if not used properly. If you are dealing with a lot of re-renders due to prop changes, make sure you are leveraging memoization. As of now, you may need to work with useMemo and useCallback hooks to memoize your values and functions, respectively. The upcoming React 19’s Forget Compiler, however, will apparently memoize everything under the hood, making these hooks obsolete. Using memoization properly can help you reduce the number of re-renders and improve your INP. To investigate your hook dependencies and re-renders, you can leverage React Developer Tools or use this handy helper hook I found on the internet to trace your re-renders: ` Conclusion Improving INP in React and Next.js is not easy and can require much investigation and fine-tuning. Still, it's worth doing to avoid being penalized by Google in its search results and provide a better experience for your users. Adopting React 18's new features, leveraging SSR and SSG in Next.js, utilizing Web Workers, and optimizing hooks and state management can significantly boost your INP score and deliver a faster application to your users. Remember, INP is just one among many performance metrics emphasizing the need for a comprehensive approach to performance optimization...

Apr 19, 2024

5 mins

Web PerformanceReactNextJSJavaScript

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

Understanding the Difference Between :focus and :focus-visible in CSS I have learned my fair share about the importance of keyboard accessibility, so I know that visual indication of the focused element is very important. But the well-known :focus pseudo-class is not always the best fit for this job. That's where :focus-visible comes in. Let's look at the differences between these two pseudo-classes and explore the best practices for using them effectively. What is the :focus Pseudo-Class? The :focus pseudo-class is a CSS selector that applies styles to any element that receives focus, regardless of how that focus was triggered. This includes focus events from keyboard navigation, mouse clicks, and touch interactions. Example Usage of :focus ` In this example, the button will display a blue outline whenever it is focused, whether the user clicks on it with a mouse, taps it on a touchscreen, or navigates to it using the keyboard. What is the :focus-visible Pseudo-Class? The :focus-visible pseudo-class is more specialized. It only applies styles to an element when the browser determines that the focus should be visible. This typically occurs when the user navigates via the keyboard or assistive technologies rather than through mouse or touch input. Example Usage of :focus-visible ` Here, the button will only show a blue outline when focused through keyboard navigation or another input method that usually requires visible focus indicators. Key Differences Between :focus and :focus-visible :focus - Behavior: Applies to any element that receives focus, regardless of the input method. - Use Cases: Ensures that all interactions with the element are visually indicated, whether by mouse, keyboard, or touch. :focus-visible - Behavior: Applies styles only when the focus should be visible, such as using a keyboard or assistive technology. - Use Cases: Ideal for scenarios where you want to provide focus indicators only to keyboard and assistive technology users while avoiding unnecessary outlines for mouse and touch users, typically required by design. Accessibility Implications :focus - Pros: - Guarantees that all users can see when an element is focused, which is critical for accessibility. - Cons: - Can lead to a suboptimal experience for mouse users, as focus styles may appear unnecessarily during mouse interactions. :focus-visible - Pros: - Enhances user experience by showing focus indicators only when necessary, thus keeping the interface clean for mouse and touch users. - Tailors the experience for keyboard and assistive technology users, providing them with clear visual cues. - Cons: - Additional considerations may be required to ensure that focus indicators are not accidentally omitted, especially in older browsers that do not support :focus-visible. - There may be cases where you want to show focus indicators for all users, regardless of input method. Best Practices for Using :focus and :focus-visible To achieve the best accessibility and user experience, combining both :focus and :focus-visible in your CSS is often a good idea. Combining :focus and :focus-visible ` Here is a Stackblitz example of what such styling could look like for you to try out and play with. Additional Tips - Test with Keyboard and Assistive Technology: Ensure that your web application is navigable using a keyboard (Tab, Shift + Tab, etc.) and that focus indicators are visible for those who rely on them. It's never a bad idea to include accessibility testing in your e2e testing suite. - Provide Clear Focus Indicators: Make sure that focus indicators are prominent and easy to see. A subtle or hard-to-spot focus indicator can severely impact accessibility for users who rely on keyboard navigation. Conclusion The :focus-visible pseudo-class offers a more refined way to manage focus indicators, improving accessibility and user experience, particularly for keyboard and assistive technology users. By understanding the differences between :focus and :focus-visible, and applying best practices in your CSS, you can create more accessible and user-friendly web applications. Remember, accessibility should never be an afterthought. By thoughtfully applying focus styles, you ensure that all users, regardless of how they interact with your site, can easily navigate and interact....

Nov 8, 2024

3 mins

AccessibilityCSSPlaywright

The HTML Dialog Element: Enhancing Accessibility and Ease of Use

The HTML Dialog Element: Enhancing Accessibility and Ease of Use Dialogs are a common component added to applications, whether on the web or in native applications. Traditionally there has not been a standard way of implementing these on the web, resulting in many ad-hoc implementations that don’t act consistently across different web applications. Often, commonly expected features are missing from dialogs due to the complexity of implementing them. However, web browsers now offer a standard dialog element. Why use the dialog element? The native dialog element streamlines the implementation of dialogs, modals, and other kinds of non-modal dialogs. It does this by implementing many of the features needed by dialogs for you that are already baked into the browser. This is helpful as it reduces the burden on the developer when making their applications accessible by ensuring that user expectations concerning interaction are met, and it can also potentially simplify the implementation of dialogs in general. Basic usage Adding a dialog using the new tag can be achieved with just a few lines of code. ` However, adding the dialog alone won’t do anything to the page. It will show up only once you call the .showModal() method against it. ` Then if you want to close it you can call the .close() method on the dialog, or press the escape key to close it, just like most other modals work. Also, note how a backdrop appears that darkens the rest of the page and prevents you from interacting with it. Neat! Accessibility and focus management Correctly handling focus is important when making your web applications accessible to all users. Typically you have to move the current focus to the active dialog when showing them, but with the dialog element that’s done for you. By default, the focus will be set on the first focusable element in the dialog. You can optionally change which element receives focus first by setting the autofocus attribute on the element you want the focus to start on, as seen in the previous example where that attribute was added to the close element. Using the .showModal() method to open the dialog also implicitly adds the dialog ARIA role to the dialog element. This helps screen readers understand that a modal has appeared and the screen so it can act accordingly. Adding forms to dialogs Forms can also be added to dialogs, and there’s even a special method value for them. If you add a element with the method set to dialog then the form will have some different behaviors that differ from the standard get and post form methods. First off, no external HTTP request will be made with this new method. What will happen instead is that when the form gets submitted, the returnValue property on the form element will be set to the value of the submit button in the form. So given this example form: ` The form element with the example-form id will have its returnValue set to Submit. In addition to that, the dialog will close immediately after the submit event is done being handled, though not before automatic form validation is done. If this fails then the invalid event will be emitted. You may have already noticed one caveat to all of this. You might not want the form to close automatically when the submit handler is done running. If you perform an asynchronous request with an API or server you may want to wait for a response and show any errors that occur before dismissing the dialog. In this case, you can call event.preventDefault() in the submit event listener like so: ` Once your desired response comes back from the server, you can close it manually by using the .close() method on the dialog. Enhancing the backdrop The backdrop behind the dialog is a mostly translucent gray background by default. However, that backdrop is fully customizable using the ::backdrop pseudo-element. With it, you can set a background-color to any value you want, including gradients, images, etc. You may also want to make clicking the backdrop dismiss the modal, as this is a commonly implemented feature of them. By default, the <dialog> element doesn’t do this for us. There are a couple of changes that we can make to the dialog to get this working. First, an event listener is needed so that we know when the user clicks away from the dialog. ` Alone this event listener looks strange. It appears to dismiss the dialog whenever the dialog is clicked, not the backdrop. That’s the opposite of what we want to do. Unfortunately, you cannot listen for a click event on the backdrop as it is considered to be part of the dialog itself. Adding this event listener by itself will effectively make clicking anywhere on the page dismiss the dialog. To correct for this we need to wrap the contents of the dialog content with another element that will effectively mask the dialog and receive the click instead. A simple element can do! ` Even this isn’t perfect though as the contents of the div may have elements with margins in them that will push the div down, resulting in clicks close to the edges of the dialog to dismiss it. This can be resolved by adding a couple of styles the the wrapping div that will make the margin stay contained within the wrapper element. The dialog element itself also has some default padding that will exacerbate this issue. ` The wrapping div can be made into an inline-block element to contain the margin, and by moving the padding from the parent dialog to the wrapper, clicks made in the padded portions of the dialog will now interact with the wrapper element instead ensuring it won’t be dismissed. Conclusion Using the dialog element offers significant advantages for creating dialogs and modals by simplifying implementation with reasonable default behavior, enhancing accessibility for users that need assistive technologies such as screen readers by using automatic ARIA role assignment, tailored support for form elements, and flexible styling options....

Oct 25, 2024

4 mins

HTMLJavaScript

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Deploying Multiple Apps From a Monorepo to GitHub Pages

Deploying Multiple Apps from a Monorepo to GitHub Pages

The Initial Setup

Accommodating Multiple Apps

Addressing Client-Side Routing

Handling Truly Missing URLs

Conclusion

Jan Kaiser

You might also like

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

Improving INP in React and Next.js

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

The HTML Dialog Element: Enhancing Accessibility and Ease of Use

Let's innovate together!

You might also like

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

Improving INP in React and Next.js

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

The HTML Dialog Element: Enhancing Accessibility and Ease of Use