VueJS

Getting started with Vitepress

Published Dec 21, 2023

Updated Dec 29, 2023

12 min read

Getting started with Vitepress to create your blog site

Have you heard about Vitepress, but you have not checked it out at it yet? Well, in this article, we are going to cover the basic setup and share what all the fuss about this new fantastic static site generator.

If you are looking for something that would allow you to quickly create a static site with Markdown support, search, Light/Dark theme, advertisement, navigation, and much more, then Vitepress is what you are looking for.

Suppose you want some proof of Vitepress's power without having to invest any further time, I suggest you head over to the main Vitepress site (vitepress.dev) and experience what Vitepress can do, as the official site is built on Vitepress!

What is Vitepress

Vitepress is a powerful Static Site Generator powered by Vite mainly used for Documentation and Blogs with the default theme, and open to customization to be used for anything you may need it to with custom themes and theme overrides.. Vitepress power comes from its low learning curve, powerful configuration settings, and the ability to easily customize it.

For example, internationalization is built-in, Theme toggling is built-in and even full-site searches require a single line in the config to be set up.

What makes Vitepress so powerful is its extensive configuration and the fact that it can be customized by overriding the existing theme, creating your theme, or simply enhancing pages with custom Vue code.

Prerequisites

To successfully run the following demo, you will need:

Node.js version 18 or higher.
Terminal for accessing VitePress via its command line interface (CLI).
Text Editor with Markdown syntax support.
VSCode is recommended, along with the official Vue extension.

Create your project

To create the project, we will follow the steps shown in the official Getting Started guide.

If you want to set up a Vitepress project quickly, run the following steps:

Create a new folder mkdir vitepress-tutorial
Access the folder cd vitepress-tutorial
Install Vitepress npm add -D vitepress
Run the Wizard npx vitepress init
Answer the questions:
- Where should VitePress initialize the config?
- Site title
- Site Description
- Theme
- Do you want Typescript support?
run npm run docs:dev
Enjoy your site.

After you run the above steps, your Vitepress will be ready and running as shown below

What is available out of the box

The site comes fully set up with enough to get you started. Let's see what features are available within the software:

Navbar: The site comes with a Navbar that already includes links to our blog pages
Light/Dark theme: Out of the box theming
Home page: Basic Homepage layout
Blogs: Two different blog posts with sidebar navigation

All of the above is available with just 4 files! Let's move forward and see how to customize our app.

Overriding the homepage

It is time to modify our site by accessing its folders. What you will probably notice when opening the site, is that Vitepress follows a very simple file structure, in fact, a new installation just includes 4 extra files on top of the expected package.json and node_modules.

Let's update our homepage to make it more unique. Because Vitepress follows a "file-system based router" we can find this file within the root of the project within a file called index.md. This file will be accessible at "/" or "/index.html" of your site.

The content of the file is the following:

---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

hero:
 name: "Vitepress tutorial"
 text: "A VitePress Site"
 tagline: My great project tagline
 actions:
   - theme: brand
     text: Markdown Examples
     link: /markdown-examples
   - theme: alt
     text: API Examples
     link: /api-examples

features:
 - title: Feature A
   details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
 - title: Feature B
   details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
 - title: Feature C
   details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
---

As you can see, the file has no code in it, and it is just driven by configuration, or more specifically in this case Markdown frontmatter, that is a set of configurations accepted by markdown files that help you set up your options such as title, description, og:image. We will describe frontmatter in more detail later in the article.

Before we jump into modifying the configuration of the file, you should know that Vitepress has a very extensive and well-detailed documentation site where you can find help if you are stuck or would like to learn more. In this case, we are overriding the "home" page, so the documentation can be found here: Home Page Default Theme configuration.

If you read the current file within the homepage, you will notice that it defines a "layout" of "home". This layout displays a main header with CTAs and a set of feature blocks.

There are three different layouts available in the Default theme: "home", "doc" and "page".

The title and description have already been set from the information we provided from the installation wizard. But the rest is just a basic boiler template. Let's see what we can change:

Add a hero image. This image can either be externally sourced or saved within the repository.

hero:
 name: "Vitepress tutorial"
 text: "A VitePress Site"
 tagline: My great project tagline
 image:
   src: 'assets/logo.png'
   alt: 'My logo'

Update the action buttons.

 actions:
   - theme: brand
     text: First Blog
     link: /first
   - theme: alt
     text: Thisdot.co
     link: https://thisdot.co

As shown above, Action buttons have two themes "brand" or "alt" and can accept internal or external links.

Vitepress is clever enough to set the external links to open in a new tab and set the rel="noreferrer".

Change the feature blocks:

Features blocks are great for engaging with the user and telling them what makes your site special. This accepts an icon and some text, so let's change ours with the following:

features:
 - icon: 🏚️
   title: Your Documentation house
   details: This is the house of your documentation
 - icon:
     src: https://emojipedia.org/house
   title: This is the logo
   details: Nothing else to say

The homepage is now completed and updated and it should look like this: Vitepress homepage with redesign

Please note that what we did on the homepage is just changing the markdown front matter of the "home" layout. What this means is that if you want to, you can easily customise the page further by either adding more blocks to the layout file or actually by writing and styling the rest of the page as normal.

Site configuration

In this step, we are going learn about the main site configuration and how we can use it to customize our site.

The configuration file can be found in the .vitepress folder under the name of "config.mjs".

Just like the homepage layout, the configuration used in the preset file is self-explanatory:

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
 title: "Vitepress tutorial",
 description: "A VitePress Site",
 themeConfig: {
   // https://vitepress.dev/reference/default-theme-config
   nav: [
     { text: 'Home', link: '/' },
     { text: 'Examples', link: '/markdown-examples' }
   ],

   sidebar: [
     {
       text: 'Examples',
       items: [
         { text: 'Markdown Examples', link: '/markdown-examples' },
         { text: 'Runtime API Examples', link: '/api-examples' }
       ]
     }
   ],

   socialLinks: [
     { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
   ]
 }
})

This file is very important and you are probably going to have it open at all times as it is going to be responsible for the layout of the sidebar navigations of your site.

In this section, we are going to learn how to use the Vitepress configuration file to achieve the following:

Modify the sidebar navigation
Enable Search
Add Favicon to your site

The sidebar is the component displayed on the left-hand side of the blog pages. This is not automatically generated, but it is manually set in this file.

You can have more than one navigation, so, for example, you could specify sidebar navigation that shows in pages that have "/blog/" within their path and another one for all markdown pages that have "/tutorials/".

Let's see how to implement this:

{
   sidebar: {
     '/blog/': [
       {
         text: 'Blog',
         items: [
           { text: 'Index', link: '/blog/' },
           { text: 'One', link: '/blog/one' }
         ]
       }
     ],

     '/tutorials/': [
       {
         text: 'Tutorial',
         items: [
           { text: 'Index', link: '/tutorials/' },
           { text: 'Two', link: '/tutorials/two' }
         ]
       }
     ]
   },
}

With the above code, there will be 2 different sidebars. One will just show if the URL includes "/blog" and the other will be displayed if the path includes "tutorials".

Clicking on the above items will give a 404 error as we do not have any pages in that specific location. Still, we can easily fix the issue by creating the two folders "blog" and "tutorial" and creating the required files within these folders in our case are "index.md" and "one.md" for the blog and "index.md" and "two.md" for tutorials.

The sidebar has further settings like the ability to create a nested tree or create collapsable menus. You can learn more by checking out the the official documentation on default theme sidebar.

Enable Search

No documentation or blog site is complete until a search is fully implemented on it. Luckily for us, enabling a site-wide search is extremely simple with Vitepress.

Vitepress supports two different search types: a full-text search using minisearch and Algolia based search.

In this tutorial, we are going to enable the full-text search. This is fully built-in and requires no external accounts.

To enable search, we need to add a "Search" parameter within our themeConfig and set the provider to "local". We can add this right below the socialLinks.

   socialLinks: [
     { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
   ],
   search: {
     provider: 'local'
   }
 }

With just a simple config change, our site will now have a full site search working as shown below: Full site search of Vitepress

The official search documentation has further information about the look and functionality of the search.

Add Favicon to your site

Even if the site configuration is very extensive, there are times when you will need to add something within the site-wise page that is not available.

In this section we are going to learn how to add specific attributes to the <head> of our site, and specifically how to add a favicon.

To add custom values to the head, we are going to use the "head" properties available with the Vitepress configuration.

The "head" configuration is an array that accepts an array with the element type (eg. link, script, meta), and an object including all the attributes for that specific element.

So for example to replicate the following HTML:

<link rel="icon" href="/image/favicon.ico"/>

we would define the following head config:

 head: [
   [ 'link', { rel: 'icon', href: '/images/favicon.ico' } ],
 ]

We can use this technique to set up metadata and even load fonts or Google Analytics. More info in the site-config head

Writing your post

In the last section of this article, we are going to learn how to actually write a blog post and also learn how to customize the pages with JS and styles.

Writing your first page

In the previous section, we created a couple of markdown files, but they are currently empty. Let's see how to create beautiful documentation using the built-in feature of Vitepress.

In this section, we are going to work on the file stored in /blog/index.md. This file can be accessed in your browser by accessing "http://localhost:5174/blog/index.html".

Blog Frontmatter

Every file needs to have a frontmatter defined. This is used to define basic information on the page, such as the title, description, and more.

For best SEO results, it is best practice to always define a title and description for a new page. We can do this by adding the following code at the top of our file:

---
title: My Blog post title
description: My unique description
---

Frontmatter in Markdown files are delimited by the "---". In the above code, we set our title and description.

Vitepress frontmatter supports further config like lastUpdates, sidebar, outline, and more. You can find info on the frontmatter-config documentation.

Frontmatter has some global configuration, such as title and description, but also "layout specific" settings that are just available on specific layouts. This is clearly explained in the documentation.

Blog Markdown

Now that our post frontmatter is set, it is time to write the content of it. This is done using a very extensive markdown engine.

Let's start with the basics and write a heading with some text and a link as shown below:

## My heading one

My text

[link](thisdot.co)

After saving, our development environment will show the following results:

Let's add a couple of headings and a table of contents to our document using [[toc]] to the top of our page:

My Table of Contents:
[[toc]]

## first heading
My text

[link](thisdot.co)

### inner heading 3

## second heading
My text

[link](thisdot.co)

The above will produce an unordered list with all our links. Table of content

The last feature that I want to share about the Vitepress markdown engine is the code editors. The markdown engine used in Vitepress offers extensive features when it comes to code rendering.

Features available are "code highlight", "code focus", external snippets loading and much more. The full list of features can be found in the markdown docs.

Let's implement a simple code snippet with a line of code focused. This can be achieved by adding "// [!code focus]" at the end of our row. Let's give it a try:

const myNewFunction = () => {
   externalApi();
   const newCode = true; // [!code focus]
   return newCode;
}

The output of this will be:

Customize your blog with Vue

In this last section, we will learn how to customize our code by adding js logic, style, and external components.

Before we begin, it is important to understand that when you use the default template of Vitepress, your pages are going to be rendered with Vue.

This means that we can expand the individual page's functionality by rendering other vue components and/or writing logic and styles directly on the page.

To better explain this concept, we are going to create a team page. Create a file called team.md within the root of our repository.

This file will be accessible on "http://localhost:5174/team.html" and will be just a simple Markdown file.

First, we set up the frontmatter as before. In this case, we have to specify an additional config called "layout". This will ensure the page has no style or components loaded such as sidebar or aside.

---
layout: page
title: My team page
---

Then we will have to create our team variable, just like a normal Vue component; we can do so by defining a script setup tag and defining the constant there.

<script setup>
import {
 VPTeamMembers
} from 'vitepress/theme'

const members = [
 {
   avatar: 'assets/logo.png',
   name: 'Simone',
   title: 'Software Architect',
   links: [
     { icon: 'github', link: 'https://github.com/#' },
     { icon: 'Twitter', link: 'https://twitter.com/#' }
   ]
 },
 {
   avatar: 'assets/logo.png',
   name: "This Dot",
   title: "Software Company"
 }
]
</script>

In the above code, we have imported the VPTeamMembers component from the vitepress/theme and defined an array of members. The values used in the members array are hardcoded, but as you may expect, you can load this information directly from an API.

We now have to use the "members" variable within our file. We can do so by writing normal JavaScript. The markdown file will evaluate the JavaScript and render it, so in the following example it will render a specific component.

## Our Team

Say hello to our awesome team.
<VPTeamMembers size="small" :members="members" />

Before we move forward we need to define some style as the page is unstyled since we have loaded the layout of "page".

Just like we did with the <script> tag, we can load a <style> tag and update our styles:

<style>
h1 {
   color: red;
}
h1, p {
   text-align: center;
}
</style>

The completed file will look like this:

---
layout: page
title: My team page
---
<script setup>
import {
 VPTeamPage,
 VPTeamPageTitle,
 VPTeamMembers
} from 'vitepress/theme'

const members = [
 {
   avatar: 'assets/logo.png',
   name: 'Simone',
   title: 'Software Architect',
   links: [
     { icon: 'github', link: 'https://github.com/#' },
     { icon: 'Twitter', link: 'https://twitter.com/#' }
   ]
 },
 {
   avatar: 'assets/logo.png',
   name: "This Dot",
   title: "Software Company"
 }
]
</script>

<style>
h2 {
   color: red;
}
h2, p {
   text-align: center;
}
</style>
## Our Team

Say hello to our awesome team.

<VPTeamMembers size="small" :members="members" />

The file above now includes:

A frontmatter that specifies a "page" layout
A script tag that loads an external component and defines a variable
Styles to make the page pretty
Markdown with a custom component

The completed team page would render the following: Customised Theme page in Vitepress

Conclusion

Vitepress is an extremely flexible static site generator. Its default theme provides you with everything you need to get started quickly. The ability to load external themes, enhance the current theme, and or write custom code within your page makes this tool extremely powerful.

In future articles, we will discover what components are available within the Default Theme and see how you can make the most of your Vitepress site but keep on coding.

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)

Simone Cuomo
Software Architect, Mentor, Speaker and Writer. Passionate about all aspect of web development, with a special love for VueJs
@zelig880 @zelig880

Understanding Vue.js's <Suspense> and Async Components

In this blog post, we will delve into how and async components work, their benefits, and practical implementation strategies to make your Vue.js applications more efficient and user-friendly. Without further ado, let’s get started! Suspense Let's kick off by explaining what Suspense components are. They are a new component that helps manage how your application handles components that need to await for some async resource to resolve, like fetching data from a server, waiting for images to load, or any other task that might take some time to complete before they can be properly rendered. Imagine you're building a web page that needs to load data from a server, and you have 2 components that fetch the data you need as they will show different things. Typically, you might see a loading spinner or a skeleton while the data is being fetched. Suspense components make it easier to handle these scenarios. Instead of manually managing loading states and error messages for each component that needs to fetch data, Suspense components let you wrap all these components together. Inside this wrapper, you can define: 1. What to show while the data is loading (like a loading spinner). 2. The actual content that should be displayed once the data is successfully fetched. This way, Vue Suspense simplifies the process of handling asynchronous operations (like data fetching) and improves the user (and the developer) experience by providing a more seamless and integrated way to show loading states and handle errors. There are two types of async dependencies that can wait on: - Components with an async setup() hook. This includes components using with top-level await expressions. *Note: These can only be used within a component.* - Async Components. Async components Vue's asynchronous components are like a smart loading system for your web app. Imagine your app as a big puzzle. Normally, you'd put together all the pieces at once, which can take time. But what if some pieces aren't needed right away? Asynchronous components help with this. Here's how they work: - Load Only What's Needed: Just like only picking up puzzle pieces you need right now, asynchronous components let your app load only the parts that are immediately necessary. Other parts can be loaded later, as needed. - Faster Start: Your app starts up faster because it doesn't have to load everything at once. It's like quickly starting with the border of a puzzle and filling in the rest later. - Save Resources: It uses your web resources (like internet data) more wisely, only grabbing what’s essential when it's essential. In short, asynchronous components make your app quicker to start and more efficient, improving the overall experience for your users. Example: ` Combining Async Components and Suspense Let's explore how combining asynchronous components with Vue's Suspense feature can enhance your application. When asynchronous components are used with Vue's Suspense, they form a powerful combination. The key point is that async components are "suspensable" by default. This means they can be easily integrated with Suspense to improve how your app handles loading and rendering components. When used together, you can do the following things: - Centralized Loading and Error Handling: With Suspense, you don't have to handle loading and error states individually for each async component. Instead, you can define a single loading indicator or error message within the Suspense component. This unified approach simplifies your code and ensures consistency across different parts of your app. - Flexible and Clean Code Structure: By combining async components with Suspense, your code becomes more organized and easier to maintain. An asynchronous component has the flexibility to operate independently of Suspense's oversight. By setting suspensible: false in its options, the component takes charge of its own loading behavior. This means that instead of relying on Suspense to manage when it appears, the component itself dictates its loading state and presentation. This option is particularly useful for components that have specific loading logic or visuals they need to maintain, separate from the broader Suspense-driven loading strategy in the application. In practice, this combo allows you to create a user interface that feels responsive and cohesive. Users see a well-timed loading indicator while the necessary components are being fetched, and if something goes wrong, a single, well-crafted error message is displayed. It's like ensuring that the entire puzzle is either revealed in its completed form or not at all rather than showing disjointed parts at different times. How it works When a component inside the boundary is waiting for something asynchronous, shows fallback content. This fallback content can be anything you choose, such as a loading spinner or a message indicating that data is being loaded. Example Usage Let’s use a simple example: In the visual example provided, imagine we have two Vue components: one showcasing a selected Pokémon, Eevee, and a carousel showcasing a variety of other Pokémon. Both components are designed to fetch data asynchronously. Without , while the data is being fetched, we would typically see two separate loading indicators: one for the Eevee Pokemon that is selected and another for the carousel. This can make the page look disjointed and be a less-than-ideal user experience. We could display a single, cohesive loading indicator by wrapping both components inside a boundary. This unified loading state would persist until all the data for both components—the single Pokémon display and the carousel—has been fetched and is ready to be rendered. Here's how you might structure the code for such a scenario: ` Here, is the component that's performing asynchronous operations. While loading, the text 'Loading...' is displayed to the user. Great! But what about when things don't go as planned and an error occurs? Currently, Vue's doesn't directly handle errors within its boundary. However, there's a neat workaround. You can use the onErrorCaptured() hook in the parent component of to catch and manage errors. Here's how it works: ` If we run this code, and let’s say that we had an error selecting our Pokemon, this is how it is going to display to the user: The error message is specifically tied to the component where the issue occurred, ensuring that it's the only part of your application that shows an error notification. Meanwhile, the rest of your components will continue to operate and display as intended, maintaining the overall user experience without widespread disruption. This targeted error handling keeps the application's functionality intact while indicating where the problem lies. Conclusion stands out as a formidable feature in Vue.js, transforming the management of asynchronous operations into a more streamlined and user-centric process. It not only elevates the user experience by ensuring smoother interactions during data loading phases but also enhances code maintainability and application performance. I hope you found this blog post enlightening and that it adds value to your Vue.js projects. As always, happy coding and continue to explore the vast possibilities Vue.js offers to make your applications more efficient and engaging!...

Apr 24, 2024

6 mins

VueWeb PerformanceUXJavaScript

How to test React custom hooks and components with Vitest

Introduction In this guide, we'll navigate through the process of testing React hooks and components using Vitest—a powerful JavaScript unit testing framework. Discover how Vitest simplifies testing setups, providing an optimal solution for both Vite-powered projects and beyond. Vitest is a javascript unit testing framework that aims to position itself as the Test Runner of choice for Vite projects and as a solid alternative even for projects not using Vite. Vitest was built primarily for Vite-powered projects, to help reduce the complexity of setting up testing with other testing frameworks like Jest. Vitest uses the same configuration of your App (through vite.config.js), sharing a common transformation pipeline during dev, build, and test time. Prerequisites This article assumes a solid understanding of React and frontend unit testing. Familiarity with tools like React Testing Library and JSDOM will enhance your grasp of the testing process with Vitest. Installation and configuration Let’s see how we can use Vitest for testing React custom hooks and components. But first, we will need to create a new project with Vite! If you already have an existing project, you can skip this step. ` Follow the prompts to create a new React project successfully. For testing, we need the following dependencies installed: Vitest as the unit testing framework JSDOM as the DOM environment for running our tests React Testing Library as the React testing utilities. To do so, we run the following command: ` Once we have those packages installed, we need to configure the vite.config.js file to run tests. By default, some of the extra configs we need to set up Vitest are not available in the Vite config types, so we will need the vite.config.ts file to reference Vitest types by adding /// reference types=”vitest” /> at the top of the file. Add the following code to the vite.config.ts ` We set globals to true because, by default, Vitest does not provide global APIs for explicitness. So with this set to true, we can use keywords like describe, test and it without needing to import them. To get TypeScript working with the global APIs, add vitest/globals to the types field in your tsconfig.json. ` The environment property tells Vitest which environment to run the test. We are using jsdom as the environment. The root property tells Vitest the root folder from where it should start looking for test files. We should add a script for running the test in package.json ` With all that configured, we can now start writing unit tests for customs hooks and React components. Writing test for custom hooks Let’s write a test for a simple useCounter hook that takes an initial value and returns the value, an increment function and a decrement function. ` We can write a test to check the default return values of the hook for value as below: ` To test if the hook works when we increment the value, we can use the act() method from @testing-library/react to simulate the increment function, as shown in the below test case: ` Kindly Note that you can't destructure the reactive properties of the result.current instance, or they will lose their reactivity. Testing hooks with asynchronous logic Now let’s test a more complex logic that contains asynchronous logic. Let’s write a useProducts hook that fetches data from an external api and return that value ` Now, let’s see what the test looks like: ` In the above example, we had to spy on the global fetch API, so that we can mock its return value. We wrapped that inside a beforeAll so that this runs before any test in this file. Then we added an afterAll method and called the mockRestore() to run after all test cases have been completed and return all mock implementations to their original function. We can also use the mockClear() method to clear all the mock's information, such as the number of calls and the mock's results. This method is handy when mocking the same function with different return values for different tests. We usually use mockClear() in beforeEach() or afterEach() methods to ensure our test is isolated completely. Then in our test case, we used a waitFor(), to wait for the return value to be resolved. Writing test for components Like Jest, Vitest provides assertion methods (matchers) to use with the expect methods for asserting values, but to test DOM elements easily, we will need to make use of custom matchers such as toBeInTheDocument() or toHaveTextContent(). Luckily the Vitest API is mostly compatible with the Jest API, making it possible to reuse many tools originally built for Jest. For such methods, we can install the @testing-library/jest-dom package and extend the expect method from Vitest to include the assertion methods in matchers from this package. ` After installing the jest-dom testing library package, create a file named vitest-setup.ts on the root of the project and import the following into the project to extend js-dom custom matchers: ` Since we are using typescript, we also need to include our setup file in our tsconfig.json: ` In vite.config.ts, we need to add the vitest-setup.ts file to the test.setupFiles field: ` Now let’s test the Products.tsx component: ` We start by spying and mocking the useProducts hook with vi.spyOn() method from Vitest: ` Now, we render the Products component using the render method from @testing-library/react and assert that the component renders the list of products as expected and also the product has the title as follows: ` In the above code, we use the render method from @testing-library/react to render the component and this returns some useful methods we can use to extract information from the component like getByTestId and getByText. The getByTestId method will retrieve the element whose data-testid attribute value equals product-list, and we can then assert its children to equal the length of our mocked items array. Using data-testid attribute values is a good practice for identifying a DOM element for testing purposes and avoiding affecting the component's implementation in production and tests. We also used the getByText method to find a text in the rendered component. We were able to call the toBeInTheDocument() because we extended the matchers to work with Vitest earlier. Here is what the full test looks like: ` Conclusion In this article, we delved into the world of testing React hooks and components using Vitest, a versatile JavaScript unit testing framework. We walked through the installation and configuration process, ensuring compatibility with React, JSDOM, and React Testing Library. The comprehensive guide covered writing tests for custom hooks, including handling asynchronous logic, and testing React components, leveraging custom matchers for DOM assertions. By adopting Vitest, developers can streamline the testing process for their React applications, whether powered by Vite or not. The framework's seamless integration with Vite projects simplifies the setup, reducing the complexities associated with other testing tools like Jest....

Mar 15, 2024

5 mins

ViteReactTesting

How to add Dark Mode in your Web Application

How to Create Dark/Light Mode in your JavaScript project? Providing our visitors with the ability to toggle between white and dark themes has become one of the most important features of all time. In this article, we will cover the requirements to develop a persistent theme for your website successfully. The code provided as part of this article will be technology agnostic and can be used with all major front-end frameworks such as Vue, React, or Svelte. TL;DR If you are in a rush and just want access to the code, you can grab it from this Stackblitz: Light / Dark theme functionality in Vanilla JS. What is White/Dark Mode Before we jump into the code, we should first explain what the meaning behind the feature name "White/Dark Mode is". This feature was first introduced in our Operating system by allowing users to change their default theme into Dark Mode, After this, Dark Mode has slowly made its way into our most used applications and websites as users expected to have a consistent look from their native application to Web App equivalent. Providing "White/Dark mode" in your site means giving the user the ability to toggle their theme to either align to the Operating system theme settings or override it from the Web App UI. The above example shows the feature on thisdot.co triggered by the little toggle button available within the main navbar. Implementing Dark Mode with Javascript This feature has two main implementation levels. The first is the ability to assign the theme directly from the Operating System preferences, while the second combines the feature of the first plus the ability to override that feature from the UI. Some websites just offer the first option and allow the site to emulate the OS preferences, even if this is mostly fine for most users, in this post, we will develop the second option as it is the most complicated approach and, therefore the most complete. The development of this feature is going to be divided into the following steps: - Ensure CSS variables drive our application - Create a second set of variables for a dark theme - Create logic to read user preferences - Create logic to override the theme preference - Make our theme selection persistent Let's dive into the code with our first step and initialize our application. Move all styles into CSS variables We are going to start our application by initializing a plain VanillaJs Stackblitz. This creates a simple project with an index.js file that includes our HTML and a style.css file that includes our global styles. To be able to have a good starting point for our post, we are going to add some more elements on the main page of the app and then define some CSS variables to make our example more appealing. First, we are going to clean our index.js and just leave the style import: ` Then, we are going to change our index.html with the following content: ` And finally, define some CSS variables and styles in style.css: ` If you are new to CSS variables, you can read more about them in the MDN docs: Using CSS custom properties. There is one point to clarify regarding CSS variables and their naming convention. Because the color held within our variables will change (for example from red to blue), the variable name should be based on the color "role" (eg primary, shadow, border") and not on the actual color "blue, green". In our example, we can see this naming convention in action as the variables are called "primary", "secondary" and "background". The above should output a very simple but colorful design: Create a second set of variables for the dark theme Now that our basic application is set, it is time to create a second set of variables to be able to define the difference between the light and dark theme. As you may notice, the CSS variables are not a must for this to work, but having all the variables set makes the maintenance of the site much easier than having to update color and styles scattered around. We are returning to our style.css file and updating a few of the CSS properties. These variables will just be updated if the body has a specific class dark associated with it: ` As the above code shows, because we are just overriding the variables, we do not actually need to redeclare them all and we can just declare the variables that we wish to update. If we would go back and add a class of "dark" to our body in index.html we would see the following output: As you can see, both white themes are fully set up and working. All that is left is creating the logic that can handle the theme toggle, but before we do so, there is one more change to add to our CSS. In fact, some components, such as form controls and scrollbar, use a property called "color-scheme" to change their theme, to give this a try, we will add an in our HTML: ` Then, let's see how this would look in our design: The input is showing a white theme even if the dark theme is selected, and this is happening because we are not changing the "color-scheme" that is what is used for the form input. Let's fix this by adding another CSS variable and a CSS declaration within our body: ` With the above code, the "color-scheme" variable will be changed to align with our overall theme, as shown below: Note that settings can be overridden on a component-by-component level. In fact, if you would like to always display the white theme for a button or field, you can just redeclare the "color-scheme" and apply it to the CSS selection of your choice. It is now time to move forward and include some JS to make the toggling automatic. Create logic to read user preferences It is now time to write some JavaScript and make our application dynamic. In this first logical step, we are going to read our Operating System color preference and use it to toggle the class assigned to our body. To do so, we are going to use the "matchMedia" method to read the "prefer-color-scheme" just like shown in the code below: ` The next step is to assign or remove the class from our body depending on the preferred scheme: ` Let's see if this works. If you are on Mac you can change the preferences by following the following steps: 1) System settings 2) Appearance 3) Change the appearance If you change the preferences and refresh your application, you should be able to see the application changing on the fly. Create logic to override the theme preference Having to change the full OS just for a single Website theme preference may be a little bit too much. So, in this step, we are going to enhance our logic to be able to override the preferences. First, we are going to add a simple button in the HTML called Toggle Theme: ` Now, it is time to update the logic. First, we need to allow a way to override the preferences. We can do this by adding an argument to our updateScheme function: ` The above code just adds a global variable called selectedTheme and then, as we previously mentioned, adds a parameter of overrideScheme to our method and finally makes sure we use this variable if available selectedTheme = overriddenScheme || preferredScheme. The next step requires us to be able to update our selectedTheme on a button click: ` With the above code added to our application, we could override the system preferences, but unfortunately, our work is not completed. The logic we wrote above is not persistent, and the theme selection will be lost if we refresh the page. Make our theme selection persistent In this last step, we are going to save our selectedTheme in localStorage using the documentation provided in the MDN documentation: Local Storage. First, let's save the selectedTheme into local storage by using localStorage.setItem: ` Then make sure we read this value on load using localStorage.getItem: ` After the above changes, you should be able to toggle the theme, refresh the page and be able to see the correct theme loaded up for you. NOTE: Due to the way StackBlitz loads the JS, there will be a small flash, but if you would place this code in the head that flash should be extremely minimal. What about the images You may have noticed that we have left the image unchanged between the different themes. This was, unfortunately not by choice, as there is no native way to swap images when using class-based theming. If you were just to implement the theme based on System Preference, you could declare different images using the media query (prefers-color-scheme: dark). This would allow you to declare images like this: ` The above code will show day.jpg if your theme settings are light or night.jpg if dark. If you would like to implement something similar with a class-based theme, you will have to create a custom image component in your framework of choice that loads the correct theme, but this is outside this tutorial's scope. Conclusion It is now time to conclude this post and leave you to go and apply what we learned in your Web applications. Implementing this feature is quite simple, and it helps to improve your user's experience. The code we have written above is available on StackBlitz: Light / Dark theme functionality in Vanilla JS. But let's see it in action in: So, in this article, we have introduced CSS variables and ensured our design colors were driven solely by them. We created an override for this variable using a class-based approach; we then learned how some elements, such as input fields, can change the theme using the "color-theme" property. We then moved into the JS, where we used the media query "prefers-color-scheme" to read the user Operating System theme preferences and, last but not least, created a live toggle that would create and save a personal preference in LocalStorage....

Dec 26, 2023

9 mins

JavaScriptCSSHTML

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

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.

Getting started with Vitepress

Getting started with Vitepress to create your blog site

What is Vitepress

Prerequisites

Create your project

What is available out of the box

Overriding the homepage

Site configuration

Modify the sidebar navigation

Enable Search

Add Favicon to your site

Writing your post

Writing your first page

Blog Frontmatter

Blog Markdown

Customize your blog with Vue

Conclusion

Simone Cuomo

You might also like

Understanding Vue.js's <Suspense> and Async Components

How to test React custom hooks and components with Vitest

How to add Dark Mode in your Web Application

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

Let's innovate together!

You might also like

Understanding Vue.js's <Suspense> and Async Components

How to test React custom hooks and components with Vitest

How to add Dark Mode in your Web Application

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