DEV Community: Gaurav Soni

Build accessible and functional Sidenav with Chakra UI

Gaurav Soni — Mon, 29 May 2023 13:55:21 +0000

Overview

Every web app on the internet has some kind of navigation that allows users to quickly navigate through different pages. Some web apps have navigation on the top and some have navigation on the side. In this blog, we will cover how to build a responsive and accessible sidenav. Building a responsive and accessible sidenav for your web app is quite challenging. There are various things that we need to consider while developing it. For example, In mobile devices where space is limited, a sidenav should be replaced with a drawer.

From the Accessibility(a11y) point of view, if we are navigating via keyboard(Tab key) through nav items, then the order of items should be followed. If we are using icon buttons instead of text for the nav items, then each button should have a proper aria-label to define the purpose of the icon button.

In this blog, we will work on building functional and accessible sidenav. Along the sidenav, we will also focus on creating a reusable responsive layout with well-defined HTML regions to improve accessibility (a11y).

Prerequisite

In order to get most of this blog, I will assume you have some knowledge about React, chakra ui, and typescript. We will use typescript instead of javascript to build our sidenav with type safety. This will help us to find the bugs at the compile time. Nowadays, every framework support typescript. In addition to these, we will also use react-router-dom and react-icons. I am also assuming you already have a React project created. There are a bunch of options to create. You can choose your favorite framework for setup. If you are ready, then let’s start constructing our sidenav.

Understanding the Role of Sidenav Within the App Layout

A sidenav is a navigation panel in your web app that provides links to navigate through different routes. It is provided in the root level component along with the main content.

In the image below, a typical layout of a web app is shown. A web app can have a header, sidenav, main content, and footer.

To make them accessible, they should be defined with appropriate landmarks. With the right landmarks, a screen reader(assistive technologies that audibly convey the content of a computer screen to visually impaired users) can easily switch between different regions of the web app. By adhering to HTML semantics, we can effectively establish meaningful landmarks. In HTML 5, some elements have pre-defined landmarks for different regions. A header has a banner landmark, an aside element has a complimentary landmark, the main has a primary content landmark, and the footer has a content info landmark. You can read more about it on W3C patterns.

A sidenav is a complementary landmark. The purpose of the complementary landmarks is to provide a supporting section to the primary content. The navigation links are not the primary content of our web app but are important for the user to navigate through primary content. They should be on the same level as primary content. So, in order to provide the supporting content such as navigation links, we need sidenav.

Why is Accessibility (a11y) Important to Us?

A11y(Accessibility) or digital a11y is a way to make your web app available for everyone. With everyone, we mean people with disabilities as well. According to WHO, “About 15% of the world's population lives with some form of disability, of whom 2-4% experience significant difficulties in functioning”. By default, the web/internet is designed to make it accessible to all kinds of people. That’s why there are different HTML elements and aria attributes exist. An accessible web app can reach a wider range of people and may result in more visitors to your app. There are various types of disabilities that can be covered by an accessible web app. You can learn more about it here.

Screen readers are the most useful tools for quickly navigating through web apps for disabled people. A screen reader can understand the semantics of the HTML elements that are used. That’s why we should use the correct HTML elements instead of div or span everywhere. Not only the HTML elements, but the order of the elements also matters a lot. The order in which the elements are laid out will define which text will be read out first and which one after that. For example, in the DOM, we have two elements, and with CSS we change the order(by position absolute or fixed). The order is changed on the screen but for the screen readers, it’s not changed. So, it’s our responsibility to let the screen reader devices know about this.

The keyboard also plays an important role while handling a11y. As we know the mobility-impaired person might not be able to use the mouse or touch devices. In this case, a keyboard-accessible app makes it easy to use for such kinds of people.

A Brief Introduction to Chakra UI

As per docs, "Chakra UI is a simple, modular, and accessible component library that gives you the building blocks you need to build your React applications." It is built on top of the emotion package, which provides a different pattern of writing CSS in JavaScript. Let’s start with installing the chakra ui package,



npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion

Additionally, we also need react-router-dom and react-icons. Let’s install it you haven’t installed it,



npm install react-icons react-router-dom --save

Folder Structure



.
└── sidenav/
├── sidenav-container/
│   ├── sidenav-container.tsx
│   └── sidenav-container.spec.tsx
├── sidenav-items/
│   ├── sidenav-items.tsx
│   └── sidenav-items.spec.tsx
├── sidenav-context/
│   ├── sidenav-context.tsx
│   └── sidenav-context.spec.tsx
├── sidenav.tsx
└── sidenav.spec.tsx

We have a sidenav folder within our components directory. The following components need to be created:-

<Sidenav /> - Our sidenav which is visible by default on the large screen and convert into the drawer in mobile devices.
<SidenavContainer /> - A container where our sidenav will be rendered along with the main content.
<SidenavItems /> - List of all the nav items in the sidenav.
<SidnavContext /> - Context to provide the props that can be shared in nested components. This will be used in case of the mobile devices where we have use drawer and the drawer can be opened from any place.

Create a `<SidenavItems />` component

Let’s create our first component. Create a sidenav/sidenav-items/sidenav-items.tsx file. Inside the file, we will first create an interface for our props:



import { IconType } from "react-icons";

export interface SidenavItem {
  icon: IconType;
  label: string;
  to: string;
}

export interface SidenavItemsProps {
  navItems: SidenavItem[];
  mode?: "semi" | "over";
}

Our SidenavItemsProps has two properties:

navItems: List of items of type SidenavItem. SidenavItem defines the structure of the single nav item that can be passed. It has icon, labeland to(route URL).
mode: Used to decide how nav items should be rendered in different devices. semi mode is set when opened on large screens and over is used when opened on mobile devices. This is an optional prop and the default value for this will be semi.

We have our props in place. Let's create our <SidenavItems /> component for semi mode.



import { List, ListItem, Icon, Flex, Text, Link, Tooltip, IconButton } from "@chakra-ui/react";
import { NavLink } from "react-router-dom";

export function SidenavItems({ navItems, mode = "semi" }: SidenavItemsProps) {
  const sidebarItemInSemiMode = (
    { icon: Icon, ...item }: SidenavItem,
    index: number
  ) => (
    <ListItem key={index}>
      <Tooltip label={item.label} placement="right">
        <IconButton
          key={index}
          as={NavLink}
          _focus={{ bg: "gray.100" }}
          _activeLink={{ boxShadow: "md", bg: "orange.500", color: "white" }}
          bg="transparent"
          aria-label={item.label}
          borderRadius="xl"
          icon={<Icon />}
          to={item.to}
        />
      </Tooltip>
    </ListItem>
  );
  return (
    <List spacing={3}>
        {navItems.map((item, index) => sidebarItemInSemiMode(item, index))}
    </List>
  );
}

export default SidenavItems;

We have sidebarItemInSemiMode in our SidenavItems component. This will render a single nav item inside our SidenavItems component. Since our nav items are a kind of list, List component from chakra-ui would be appropriate for this. We need to wrap each item in ListItem component. Then we have Tooltip component wrapping the IconButton component. Sometimes understanding the purpose of the nav item is not clear by just looking at the icon. In such cases, giving a tooltip will make it easier for the users to understand by providing additional information.

The nav item should be a link that navigates to the provided route. But at the same time, it is also an icon. The IconButton component seems like the correct component for this. But from the a11y point of view, it should be a link(anchor tag). How can we combine both? Well, it’s not difficult. Charka-ui provides us as prop which can be used to specify the ReactElement that can be rendered but with the same styles. We will use the NavLink component from react-router-dom to render the IconButton as a link. We also need to highlight our nav item whenever the user either hovers or focuses on it. On click, it should be marked as active in order to make the current nav item highlighted. This will help us to convey the right state of the link. The _activeLink and _focus props are used for this. The hover state is already handled by IconButton. Note that the active state of the link is provided by NavLink. So in order to _activeLink to work, this is required.

Chakra ui provides us with a set of default color palettes. I am using orange here. But you can choose anyone.

aria-label is also provided to help screen readers to read the appropriate text for visually impaired users.

In the end, we need to iterate over the nav items and render them using the array map function.

Next, let’s create sidenav items for over mode.



import { List, ListItem, Icon, Flex, Text, Link, Tooltip, IconButton } from "@chakra-ui/react";
import { NavLink } from "react-router-dom";

export function SidenavItems({ navItems, mode = "semi" }: SidenavItemsProps) {
  const sidebarItemInOverMode = (item: SidenavItem, index: number) => (
    <ListItem key={index}>
      <Link
        display="block"
        as={NavLink}
        to={item.to}
        _focus={{ bg: "gray.100" }}
        _hover={{
          bg: "gray.200"
        }}
        _activeLink={{ bg: "orange.500", color: "white" }}
        w="full"
        borderRadius="md"
      >
        <Flex alignItems="center" p={2}>
          <Icon boxSize="5" as={item.icon} />
          <Text ml={2}>{item.label}</Text>
        </Flex>
      </Link>
    </ListItem>
  );
  return (
    <List spacing={3}>
        {navItems.map((item, index) => sidebarItemInSemiMode(item, index))}
    </List>
  );
}

export default SidenavItems;

sidebarItemInOverMode is similar to sidebarItemInSemiMode . The only difference is instead of IconButton we are using Link component. In over mode, we are rendering the icon along with the text. So it is easy to understand the purpose of the icon. Hence, we don’t need to wrap it inside the tooltip. So the full component will look like this,



import {
  List,
  ListItem,
  Icon,
  Flex,
  Text,
  Link,
  Tooltip,
  IconButton
} from "@chakra-ui/react";
import { IconType } from "react-icons";
import { NavLink } from "react-router-dom";

export interface SidenavItem {
  icon: IconType;
  label: string;
  to: string;
}

export interface SidenavItemsProps {
  navItems: SidenavItem[];
  mode?: "semi" | "over";
}

export function SidenavItems({ navItems, mode = "semi" }: SidenavItemsProps) {
  const sidebarItemInOverMode = (item: SidenavItem, index: number) => (
    <ListItem key={index}>
      <Link
        display="block"
        as={NavLink}
        to={item.to}
        _focus={{ bg: "gray.100" }}
        _hover={{
          bg: "gray.200"
        }}
        _activeLink={{ bg: "orange.500", color: "white" }}
        w="full"
        borderRadius="md"
      >
        <Flex alignItems="center" p={2}>
          <Icon boxSize="5" as={item.icon} />
          <Text ml={2}>{item.label}</Text>
        </Flex>
      </Link>
    </ListItem>
  );
  const sidebarItemInSemiMode = (
    { icon: Icon, ...item }: SidenavItem,
    index: number
  ) => (
    <ListItem key={index}>
      <Tooltip label={item.label} placement="right">
        <IconButton
          key={index}
          as={NavLink}
          _focus={{ bg: "gray.100" }}
          _activeLink={{ boxShadow: "md", bg: "orange.500", color: "white" }}
          bg="transparent"
          aria-label={item.label}
          borderRadius="xl"
          icon={<Icon />}
          to={item.to}
        />
      </Tooltip>
    </ListItem>
  );
  return (
    <List spacing={3}>
      {mode === "semi"
        ? navItems.map((item, index) => sidebarItemInSemiMode(item, index))
        : navItems.map((item, index) => sidebarItemInOverMode(item, index))}
    </List>
  );
}

export default SidenavItems;

While iterating over the nav items, we can check the mode provided to the and render them accordingly. The preview of this component will looks like below,

Sidenav context

Why do we need sidenav context?

We are creating a responsive sidenav. As we mentioned earlier, for mobile devices we will use the <Drawer /> component. The drawer will be hidden by default and can be opened by some action(button click etc). On some action, we need to convey this message to our drawer. This can be done by passing a callback as a prop to the sidenav. This is fine if you have one level of nesting for your component that will trigger the action. But if you have a deeply nested component that will trigger the action, this might be a tedious task. As per react docs,

“Context provides a way to pass data through the component tree without having to pass props down manually at every level.”

Our sidenav component is a layout component and will be added at the root level. Other components may be placed within routes or deeply nested. To enable communication between these components, we utilize sidenav context. This type of scenario commonly arises during application development. Alternatively, you could use simple props, but that would lead to prop drilling.

Create a SidenavContext

Create a sidenav/sidenav-context.tsx file. We will add context inside the file:



import { useDisclosure } from "@chakra-ui/react";
import { createContext } from "react";
const SidenavContext = createContext<ReturnType<typeof useDisclosure> | null>(
  null
);

Our sidenav requires specific props like open, close, toggle, etc. to manage the behavior of the drawer. Chakra ui provides a custom hook useDisclosure, designed for such components. Additionally, it is important to have a strongly typed context. To achieve this, we will utilize the ReturnType utility from TypeScript to obtain the functions and properties exposed by useDisclosure. Initially, the context will have no value, so we will initialize it with null.

Now, let’s create a custom hook for our sidenav context.



import { useContext } from "react";

export function useSidenav() {
  const sidebar = useContext(SidenavContext);
  if (!sidebar) {
    throw new Error("Cannot use `sidebar context` outside SidebarProvider");
  }
  return { ...(sidebar as ReturnType<typeof useDisclosure>) };
}

Wrapping our context in the custom hook makes it easy to use in other places. Our sidenav context initially has a null value. So, it’s good to check if the context value is provided or not. If not, then simply throw an error.

Let’s create a provider,



import { useDisclosure } from "@chakra-ui/react";

export function SidenavProvider({
  children,
  ...props
}: {
  children: React.ReactNode;
}) {
  const disclosure = useDisclosure();
  return (
    <SidenavContext.Provider value={{ ...disclosure }} {...props}>
      {children}
    </SidenavContext.Provider>
  );
}

export default SidenavProvider;

This code is wrapping the SidenavContext.Provider with disclosure value and exports it. This is a common practice in React and also makes the code easy to test. The whole code for sidenav context will look like this,



import { useDisclosure } from "@chakra-ui/react";
import { createContext, useContext } from "react";

const SidenavContext = createContext<ReturnType<typeof useDisclosure> | null>(
  null
);

export function useSidenav() {
  const sidebar = useContext(SidenavContext);
  if (!sidebar) {
    throw new Error("Cannot use `sidebar context` outside SidebarProvider");
  }
  return { ...(sidebar as ReturnType<typeof useDisclosure>) };
}

export function SidenavProvider({
  children,
  ...props
}: {
  children: React.ReactNode;
}) {
  const disclosure = useDisclosure();
  return (
    <SidenavContext.Provider value={{ ...disclosure }} {...props}>
      {children}
    </SidenavContext.Provider>
  );
}

export default SidenavProvider;

Create a `<Sidenav />` Component

Create a sidenav/sidenav.tsx file. Within the file, we will create components and interfaces for our props.



import React from "react";
import {
  Drawer,
  DrawerContent,
  DrawerCloseButton,
  DrawerHeader,
  DrawerOverlay,
  VStack,
  DrawerBody,
  Icon
} from "@chakra-ui/react";
import { SiWwise } from "react-icons/si";
import { useSidenav } from "./sidenav-context/sidenav-context";
import SidenavItems, { SidenavItem } from "./sidenav-items/sidenav-items";

export interface SidenavProps {
  navItems: SidenavItem[];
}

export function Sidenav({ navItems }: SidenavProps) {
  const { isOpen, onClose } = useSidenav();
  return (
    <React.Fragment>
      <VStack spacing="5" as="nav" display={{ base: "none", md: "flex" }}>
        <Icon as={SiWwise} boxSize={8} /> {/*OR PUT YOUR LOGO HERE */}
        <SidenavItems navItems={navItems} />
      </VStack>
      <Drawer placement="left" onClose={onClose} isOpen={isOpen}>
        <DrawerOverlay />
        <DrawerContent>
          <DrawerCloseButton />
          <DrawerHeader>Weather Wise</DrawerHeader>
          <DrawerBody>
            <SidenavItems navItems={navItems} mode="over" />
          </DrawerBody>
        </DrawerContent>
      </Drawer>
    </React.Fragment>
  );
}

export default Sidenav;

The SidenavProps interface is straightforward. It has a single property navItems. Let’s look at the Sidenav component. We are using our custom hook useSidenav coming from our sidenav context. After that, we have our JSX which contains two siblings that wrap our component in different components. The first one is VStack and the other one is Drawer. Let’s look at the first one,



<VStack spacing="5" as="nav" display={{ base: "none", md: "flex" }}>
  <Icon as={SiWwise} boxSize={8} /> {/*OR PUT YOUR LOGO HERE */}
  <SidenavItems navItems={navItems} />
</VStack>

VStack will render the items vertically. Internally, it’s a flexbox with a flex-direction column. As we discussed earlier, HTML semantics are crucial for accessibility (a11y). Therefore, we will once again use the as prop to render the VStack as a nav element instead of a div. The VStack is visible on large screens but hidden on mobile devices. To achieve this, we use display prop with the value of {{ base: "none", md: "flex" }}. In Chakra UI, the breakpoints are designed with a mobile-first approach, so base refers to mobile devices. After the VStack, we have the logo (or in its absence, an Icon can be placed) and the SidenavItems.The SidenavItems component is set to semi mode by default, eliminating the need to provide it explicitly.

Now let's look at the other code snippet,



<Drawer placement="left" onClose={onClose} isOpen={isOpen}>
    <DrawerOverlay />
    <DrawerContent>
      <DrawerCloseButton />
      <DrawerHeader>Sidenav Header</DrawerHeader>
      <DrawerBody>
        <SidenavItems navItems={navItems} mode="over" />
      </DrawerBody>
    </DrawerContent>
  </Drawer>

We are utilizing the Drawer component from Chakra UI, which represents a panel that slides out from the screen edge. The Drawer component requires an onClose callback, obtained from the Sidenav context. The isOpen prop determines whether the drawer is open or closed. By default, our useSidenav hook provides a false value for isOpen, resulting in the drawer being closed. Our sidenav will always be rendered on the left side, we need to set the placement to left.

Next, we have the DrawerOverlay component, responsible for rendering the backdrop with a gray background. The DrawerCloseButton is an icon placed at the top to allow the closing of the drawer. The DrawerHeader contains the header text, wrapped inside a header tag.

Inside the DrawerBody, we have our SidenavItems component. This code snippet does not include breakpoints because our drawer is always closed by default. To show the drawer, we need to set isOpen to true through an external button that is visible only on mobile devices. It is worth noting that we are providing the over mode to the SidenavItems component, which renders the navigation items differently from the default semi mode.

The whole code for sidenav component will look like this,



import React from "react";
import {
  Drawer,
  DrawerContent,
  DrawerCloseButton,
  DrawerHeader,
  DrawerOverlay,
  VStack,
  DrawerBody,
  Icon
} from "@chakra-ui/react";
import { SiWwise } from "react-icons/si";
import { useSidenav } from "./sidenav-context/sidenav-context";
import SidenavItems, { SidenavItem } from "./sidenav-items/sidenav-items";

export interface SidenavProps {
  navItems: SidenavItem[];
}

export function Sidenav({ navItems }: SidenavProps) {
  const { isOpen, onClose } = useSidenav();
  return (
    <React.Fragment>
      <VStack spacing="5" as="nav" display={{ base: "none", md: "flex" }}>
        <Icon as={SiWwise} boxSize={8} /> {/*OR PUT YOUR LOGO HERE */}
        <SidenavItems navItems={navItems} />
      </VStack>
      <Drawer placement="left" onClose={onClose} isOpen={isOpen}>
        <DrawerOverlay />
        <DrawerContent>
          <DrawerCloseButton />
          <DrawerHeader>Sidenav Header</DrawerHeader>
          <DrawerBody>
            <SidenavItems navItems={navItems} mode="over" />
          </DrawerBody>
        </DrawerContent>
      </Drawer>
    </React.Fragment>
  );
}

export default Sidenav;

SidenavContainer

Why do we need `<SidenavContainer />`?

With the above sidenav component, we have completed its implementation. You are free to use it as you see fit. However, from my perspective, it is only partially implemented. If I were to utilize it in an application, I would likely create a layout component and incorporate our sidenav within it. The sidenav is an integral part of our layout, and layout components bring together all the core components that remain unchanged regardless of the routes. If you wish to take it a step further, we can begin by creating our <SidenavContainer /> component.

Create `<SidenavContainer />` component

Create a sidenav/sidenav-container.tsx file. Within the file, we will create an interface for our props.



import { ReactNode, ReactElement } from "react";

export interface SidenavContainerProps {
  children: ReactNode;
  sidenav: ReactElement;
}

There are two props for our SidenavContainer component: children and sidenav. Children are the react nodes that are passed by React. Sidenav is the component that we created above.



import { Box, Grid, GridItem } from "@chakra-ui/react";

export function SidenavContainer({ children, sidenav }: SidenavContainerProps) {
  return (
    <Grid templateAreas={`'sidebar main'`} templateColumns="auto 1fr">
      <GridItem area="sidebar" as="aside" w="full" p={0}>
        <Box
          pos="sticky"
          top={0}
          w={{ base: 0, md: "72px" }}
          borderRight="1px solid"
          borderColor="gray.100"
          p={{ base: 0, md: 2 }}
          paddingTop={8}
          height="100vh"
          overflow="auto"
          css={{
            "&::-webkit-scrollbar": {
              height: "var(--chakra-sizes-1)",
              width: "var(--chakra-sizes-1)"
            },
            "&::-webkit-scrollbar-thumb": {
              backgroundColor: "var(--chakra-colors-gray-400)"
            }
          }}
        >
          {sidenav}
        </Box>
      </GridItem>
      <GridItem as="main" area="main" p={{ base: 6, md: 8 }}>
        {children}
      </GridItem>
    </Grid>
  );
}

export default SidenavContainer;

CSS grid is an ideal choice for creating two-dimensional layouts, and our case is no exception. Chakra UI conveniently provides us with a grid component out of the box, so we have opted to utilize it. If you would like to learn more about grids, you can refer to the MDN docs

Tip: To conveniently organize and position elements on the grid, consider using the templateAreas property.

In our grid, we have two items. The first item is our sidenav, and there are a few important details to note. We utilize the as prop to instruct Chakra UI to render the grid item as an aside element, which is crucial for accessibility reasons as mentioned earlier. Additionally, we make the sidenav sticky, ensuring it remains fixed when the user scrolls through the main content.

The second aspect to notice is w={{ base: 0, md: "72px" }}. By default, our sidenav has a semi mode, so we assign a width of 72px to make it visible on the screen. For mobile devices, we transition from a two-dimensional layout to a one-dimensional layout, hiding the sidenav with {base: 0}. Similarly, we use the code p={{ base: 0, md: 2 }} to dynamically add or remove padding based on the device.

The third important detail is the inclusion of overflow="auto". This ensures that if we have an overflow of nav items, the sidenav won't break; instead, a scrollbar will be displayed, allowing users to access the additional items. We can apply custom styles to the scrollbar using the css prop, but for now, we won't delve into that since it can be modified according to your requirements.

The second item in our grid is the main content, which occupies the remaining space. Similar to the sidenav, we use the as prop to render it as a main element for accessibility reasons, as mentioned earlier. Furthermore, we adjust the padding based on different devices.

Let’s try it out

Now we are done with the implementation. Let’s try it out in our React app. In your App.tsx, add the below code,



import { BsBarChart } from "react-icons/bs";
import { BiMap, BiChalkboard } from "react-icons/bi";
import { FiSettings, FiMenu } from "react-icons/fi";
import { Outlet } from "react-router-dom";
import {
  SidenavProvider,
  SidenavContainer,
    SidenavItem,
  Sidenav,
    useSidenav,
} from "./components/sidenav";
import { Navbar } from "./components/navbar/navbar";

export default function App() {
  const navItems: SidenavItem[] = [
    { icon: BsBarChart, label: "Dashboard", to: "" },
    { icon: BiChalkboard, label: "Forecast", to: "forecast" },
    { icon: BiMap, label: "Location", to: "location" },
    { icon: FiSettings, label: "Settings", to: "settings" }
  ];
    const { onOpen } = useSidenav();
  return (
    <SidenavProvider>
      <SidenavContainer sidenav={<Sidenav navItems={navItems} />}>
        <main>
          <div className="App">
            <h1>Hello CodeSandbox!</h1>
            <h2>Start editing to see some magic happen!</h2>
            <Outlet />
          </div>
        </main>
    <IconButton
       aria-label="menu"
       display={{ base: "flex", md: "none" }}
       onClick={onOpen}
       icon={<FiMenu />}
    />
      </SidenavContainer>
    </SidenavProvider>
  );
}

We have created an array of navigation items to define our navigation menu. To enable navigation between these items, you will need to set up the corresponding routes. Although I won't provide the code for creating routes here, I have prepared a codesandbox with the complete implementation, which is attached at the end.

Our entire app is wrapped in the SidenavProvider, allowing us to access the SidenavContext through the useSidenav hook. To demonstrate how to use the useSidenav hook, I have utilized an <IconButton /> component, which is visible on mobile devices. When the user clicks on this button, it triggers the onOpen function from our hook, which opens the sidenav as a drawer.

Closing Remarks

Remember, the possibilities for customization and enhancement are endless. Feel free to explore and adapt the code according to your specific requirements and design preferences. With the tools and concepts discussed in this blog, you can create intuitive navigation solutions that elevate the usability and accessibility of your web applications.

Don't forget to check out the attached codesandbox for a full implementation example. If you have any questions or need further assistance, feel free to reach out. Happy coding and may your navigation journeys be smooth and delightful!.

Inspirations:

https://chakra-ui.com/

https://material.angular.io/components/sidenav/overview https://web.dev/building-a-sidenav-component/

https://web.dev/building-a-sidenav-component/

https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/general-principles.html

Removing boilerplate code in Ngrx component store

Gaurav Soni — Sun, 13 Mar 2022 21:59:00 +0000

Introduction

Ngrx component store is a great package for state management at component level in angular. For small applications and applications having isolated component trees, which require their own state and that do not need to be shared, it is a great fit. It comes with the power of a push based mechanism but at the level of service. In this article, I will assume you have basic understanding about the @ngrx/component-store. So, we will not focus on discussing the basics of component store. Instead, we will talk about removing duplicate code while using the component store. We will write a lot of code. So, let’s get started.

App structure

Below is the structure of our demo application:-

├── src/
│   ├── app/
│   │    ├── albums/
│   │    │     ├── albums.component.ts
│   │    │     ├── albums.component.html
│   │    │     ├── albums.component.css
│   │    │     ├── albums.store.ts
│   │    ├── users/
│   │    │     ├── users.component.ts
│   │    │     ├── users.component.html
│   │    │     ├── users.component.css
│   │    │     ├── users.store.ts
│   │    │── app.component.html
│   │    │── app.component.css
│   │    │── app.component.ts
│   │    │── app.module.ts
│   │    │── base-component.store.ts
│   │    │── count.component.ts
│   │
│   ├── assets/
│   ├── environments/
│   ├── favicon.ico
│   ├── index.html
│   ├── main.ts
│   ├── polyfills.ts
│   ├── styles.css
│   └── test.ts
├── .browserslistrc
├── karma.conf.js
├── tsconfig.json

We have two components:- Users and Albums. Both have their own component stores. We also have one base component store. We will talk about it later in the article. Also we have one count compnent to show the total number of items loaded.
Let’s start first with creating a generic state interface.

Generic State interface

This interface represents the state that each component store will have whenever we create a new state. Below is the code snippet for this,

export type LOADING = 'IDLE' | 'LOADING';
type CallState = LOADING | HttpErrorResponse;

export interface GenericState<T> {
  data: T;
  callState: CallState;
  totalCount: number;
}

The GenericState interface accepts a generic type <T> which represents the structure of our data property. Out data can either be a collection of itmes or a single item. Then we have callState which will be either of type LOADING or HttpErrorResponse. We can also create them separately as loading and error. But I would prefer to have them in a single property. Then we have the totalCount which will be the length of total items if our data is a collection of items, otherwise(if data is an object or single item) we can set it to 0 in order to ignore it.

BaseComponentStore

Now let's move to the next step and create a BaseComponentStore which will be extended by albums and users component store. The basic idea behind creating this is to provide boilerplate code for our both stores.

@Injectable()
export class BaseComponentStore<
  T extends GenericState<unknown>
> extends ComponentStore<T> {
  baseSelector = this.select(({ callState, totalCount }) => ({
    totalCount,
    loading: callState === 'LOADING',
    error: callState instanceof HttpErrorResponse ? callState : undefined,
  }));
  protected updateError = this.updater((state, error: CallState) => ({
    ...state,
    callState: error,
  }));

  protected setLoading = this.updater((state) => ({
    ...state,
    data: undefined,
    callState: 'LOADING',
  }));

  protected updateSuccess = this.updater((state, data: T['data']) => ({
    ...state,
    data,
    totalCount: Array.isArray(data) ? data.length : 0,
    callState: 'IDLE',
  }));
}

Our BaseComponentStore accepts the generic type T which by default extends the GenericState of unknown. We are using unknown here because we don't’ know the type of data here. But we are sure about the types of other properties such as callState and totalCount. This BaseComponentStore extends the ComponentStore in order to have access to state and other methods.
Next we are creating the baseSelector. This will be used to get all other properties required by the component. Error, loading and totalCount are common properties that are required by the components. So, it's a good idea to have them in the base selector. We can add more properties to this selector based on our requirement.

Next we have the updateError method. Again, most of the time the errors are handled in the common way. So, we can have this method in our base component store.
Similarly, we have setLoading method to update the loading state.
Then we have updateSuccess method to update the data in the component store. We are assuming here that the data is simply the new list or new item. So it's easy to set. So we are updating the data, setting up the totalCount with the length of items and updating the callState back to IDLE.

Now with this we have our boilerplate/duplicate code inside the BaseComponentStore which gives benefit to all other stores which will extend it.

Implementing AlbumsStore

Now that our base component store is ready, let’s start with creating an AlbumsStore which we will use in AlbumsComponent.
Let’s first create required interfaces,

interface Album {
  id: number;
  userId: number;
  title: string;
}

interface AlbumViewModel {
  albums: Album[];
  loading: boolean;
  totalCount: number;
  error: HttpErrorResponse;
}

We have the Album interface which has id, userId and title properties. Then we are creating a AlbumViewModel interface which is used to build the viewModel. A viewModel is the pattern used to expose the single observable instead of multiple observables which will be used by the component.

Let’s move to the next step of creating AlbumsStore.

@Injectable()
export class AlbumsStore extends BaseComponentStore<GenericState<Album[]>> {
  readonly albums$ = this.select((state) => state.data);
  readonly vm$: Observable<AlbumViewModel> = this.select(
    this.baseSelector,
    this.albums$,
    (state, albums) => ({ ...state, albums })
  );
  constructor(private readonly http: HttpClient) {
    super({
      data: [],
      callState: 'IDLE',
      totalCount: 0,
    });
  }

  readonly getAlbums = this.effect((params$: Observable<unknown>) => {
    return params$.pipe(
      tap((_) => this.setLoading()),
      switchMap((_) =>
        this.http
          .get<Album[]>('https://jsonplaceholder.typicode.com/albums')
          .pipe(
            tapResponse(
              (users: Album[]) => this.updateSuccess(users),
              (error: HttpErrorResponse) => this.updateError(error)
            )
          )
      )
    );
  });
}

Our AlbumsStore extends the BaseComponentStore by providing the Album[] as a type for the GenericState<T>. Now the first thing we can notice here is that we are not creating a new interface for the state(something like AlbumsState). All the common properties, totalCount and callState are always there in the BaseComponentStore via GenericState. So we don’t need that. Next we are creating albums$. This is just a mapping of data to the albums. In our component, instead of data, using the album as property might be the better naming convention.

After that we have our vm$ which is the single observable exposing multiple properties. Now again we can notice the benefit of creating the boilerplate code. We are not adding the loading, error and totaCount here since they will be always coming from baseSelector.

Now we have our selectors done, let’s start with initializing the state. We are initializing it via calling the parent constructor(as per component store convention) with our default state.

Next we have the effect which will fetch the albums from the server. Notice that we are using the setLoading method from our BaseComponentStore to update the callState to LOADING. This will be used in the component to show the loader. Similarly, we are also using the updateSuccess and updateError to set the data and error in the state. Also, ngrx component store provides tapResponse operator to gracefully handle the errors. So we are using it.

Using AlbumsStore in the component

We are ready to use the AlbumStore inside our AlbumsComponent. Let’s have a look into album.component.ts,

@Component({
  selector: 'app-albums',
  templateUrl: './albums.component.html',
  styleUrls: ['./albums.component.css'],
  providers: [AlbumsStore],
})
export class AlbumsComponent implements OnInit {
  vm$ = this.store.vm$;
  constructor(private store: AlbumsStore) {}

  ngOnInit() {
    this.store.getAlbums({});
  }

  fetch() {
    this.store.getAlbums({});
  }
}

Our AlbumsComponent is simple. It has vm$ observable as property. We are calling our effect on ngOnInit to fetch the albums. After this we have one method fetch which we can call whenever we want to re-fetch our data.

Let's look at the album.component.html file as well.

<ng-container *ngIf="vm$ | async as vm">
  <button (click)="fetch()">Fetch Albums</button>
  <ng-container *ngIf="!vm.loading; else loading">
    <count [count]="vm.totalCount"></count>
    <ng-container *ngFor="let album of vm.albums">
      <pre>ID: {{ album.id }}</pre>
      <pre>UserId: {{ album.userId }}</pre>
      <pre>title: {{ album.title }}</pre>
    </ng-container>
  </ng-container>
</ng-container>
<ng-template #loading>
  <div>Loading...</div>
</ng-template>

In the html file, we are using an async pipe to subscribe for the vm$ property. async pipe will automatically update our view whenever our vm$ changes. We have a button(Fetch Albums) to re-fetch the albums. Then we are showing the albums if we have the albums available otherwise we are showing the loading text. We are also showing the count of the albums via count component and then showing the album info via *ngFor. <count> is a simple component which accepts count as @Input and then showing them with message Total count: {{count}},

@Component({
  selector: 'count',
  template: `<h1>Total Count: {{count}}!</h1>`,
  styles: [`h1 { font-family: Lato; }`],
})
export class CountComponent {
  @Input() count: number;
}

Implementing UsersStore

Next we can have the UsersStore and UsersComponent. The code snippet is identical to the album's feature. I am just adding the snippet for the UsersStore and the rest of the code can be seen at stackblitz.

interface User {
  id: number;
  name: string;
  username: string;
}

interface UserViewModel {
  users: User[];
  loading: boolean;
  totalCount: number;
  error: HttpErrorResponse;
}

@Injectable()
export class UsersStore extends BaseComponentStore<GenericState<User[]>> {
  readonly users$ = this.select((state) => state.data);
  readonly vm$: Observable<UserViewModel> = this.select(
    this.baseSelector,
    this.users$,
    (state, users) => ({ ...state, users })
  );
  constructor(private readonly http: HttpClient) {
    super({
      data: [],
      callState: 'IDLE',
      totalCount: 0,
    });
  }

  readonly getUsers = this.effect((params$: Observable<unknown>) => {
    return params$.pipe(
      tap((_) => this.setLoading()),
      switchMap((_) =>
        this.http
          .get<User[]>('https://jsonplaceholder.typicode.com/users')
          .pipe(
            delay(300),
            tapResponse(
              (users: User[]) => this.updateSuccess(users),
              (error: HttpErrorResponse) => this.updateError(error)
            )
          )
      )
    );
  });
}

Everything is identical to the AlbumsStore. Instead of albums we have users here. Below is the gif of the working example,

With the help of our BaseComponentStore, we are able to remove a lot of duplicate code. Hence we need to write less code every time we create new component store and we will still get the same results.

Full code example can be found on below stackblitz link:-
https://stackblitz.com/edit/angular-ivy-rgps6q?file=src%2Fapp%2Fbase-component.store.ts

Enhance a11y using :focus-visible pseudo-class

Gaurav Soni — Sun, 09 May 2021 13:13:56 +0000

Accessibility is one of the important aspects of the applications. Building the accessible applications will make sure your application will be used by all people(irrespective of their disabilities). According to W3C,

The Web is fundamentally designed to work for all people, whatever their hardware, software, language, location, or ability. When the Web meets this goal, it is accessible to people with a diverse range of hearing, movement, sight, and cognitive ability.

Problem Statement

In order to make our web pages accessible, sometimes we need to explicitly set the focus on some non-interactive elements(headings, table, main etc) so that it will be read out by screen-readers. But by doing so we might also annoy our regular users(users who will not use screen readers). Normal users can read the text easily. It would be good if there is a way to make the non-interactive elements focusable only for keyboard users or screen-readers.

:focus-visible is the rescue

From MDN,

The :focus-visible pseudo-class applies while an element matches the :focus pseudo-class and the UA (User Agent) determines via heuristics that the focus should be made evident on the element. (Many browsers show a “focus ring” by default in this case.)
This selector is useful to provide a different focus indicator based on the user’s input modality (mouse vs. keyboard).

I hope this will make sense now. The syntax to use it looks like:-

.element:focus-visible {
  /* Add some styles to get the user's attention */
}

With this, we can add styles to focus on keyboard input. But this is not enough for what we want. For mouse users, we need to remove the focus styles from non-interactive elements,

.element:focus {
  outline: none;
}

Now when the user tab on the element(make sure to add tabindex on non interactive elements), the element will get the focus but if we mouse click to the element, the element will not get the focus. You can check this very basic example.

Now we have the :focus-visible pseudo-class. But there is again an issue. This selector is supported by chrome, firefox, and edge but not by safari. But thanks to the polyfill.
With this polyfill, it will be supported by all major browsers. But we need to slightly update the code.

/*
  This will hide the focus indicator if the element receives focus via the mouse,
  but it will still show up on keyboard focus.
*/
.element:focus:not(.focus-visible) {
  outline: none;
}

.element.focus-visible {
 /* Add some styles to get the user's attention */
}

You may have noticed that instead of using the pseudo-class, we are using the class .focus-visible that is provided by the polyfill. With this change, we are all set to use this browser feature.

Learn more:-

Power of conditional types in Typescript

Gaurav Soni — Sun, 28 Feb 2021 18:39:54 +0000

One of the most loved type system in the javascript world is the typescript type system. It comes with a lot of features. One of the features that we are discussing today is called conditional types.

Conditional types are a lot like a javascript's ternary operator. Based on the condition, Typescript will decide which type can be assigned to the variable. Conditional types mostly work with generics.

A few words about generics

Generics are created to work over a variety of types. Consider the example from typescript website,

function identity<T>(arg: T): T {
 return arg;
}

Here the T is representing the generic type. Typescript decides the value of T dynamically either by type inferencing or we can tell typescript specifically the type. For example,

const output = identity('myString'); // typeof output is string
Const output =  identity<string>('myString'); // type is string

Back to conditional types

Now let's discuss the conditional types. As we said earlier, conditional types are more like a ternary operator in javascript, below is the example,

type IamString<T> = T extends string ? 'I am string': 'I am not string';
type str = IamString<string>; // "I am string"
type notStr = IamString<number>; // "I am not string"

As we can see in the above example, if we pass a string to the type IamString, we will get "I am string", otherwise it's giving "I am not string". On the other way, you can also think of conditional types as adding constraints to the generic types. T is extending the string is a constraint here.

Error handling example

In this article, we will take an example of error handling. Consider we are handling the errors in our application. Let say we have two types of errors in the application. 1) Application Error - Error specific to application 2) Error - normal javascript error.
Let say we abstract the ApplicationError class,

abstract class ApplicationError {
    abstract status: number;
    abstract message: string;
}

Our custom errors will extend this abstract class and add their implementation. For example,

class ServerError extends ApplicationError {
    status = 500;
    constructor(public message: string) {
        super();
    }
}

Let us create a conditional type to identify the error type,

type ErrorType<T extends {error: ApplicationError | Error}> = T['error'] extends ApplicationError ? ApplicationError : Error;

Now if you try to pass an object which has an error that extends ApplicationError, we will get the type ApplicationError otherwise we will get the Error type,
server error example
error example

We can also use this type(ErrorType) as a return type of function. Consider a function that extracts an error from the object and returns that error. The one way to implement that function is to use function overloading,

function getError(response: {error: ApplicationError}): ApplicationError;
function getError(response: {error: Error}): Error;
function getError(response: {error: ApplicationError | Error}): ApplicationError | Error {
    if (response.error instanceof ApplicationError) {
        return response.error;
    }
    return response.error;    
}

function overloading getError method
getError example with error screenshot

In the screenshots, Typescript can identify the type of error for us. But consider in future you are having four types of error in the application. Then you need to overload the getError function two more times which might be annoying.

Now Let's implement the same thing with the condition types,

type ErrorType<T extends {error: ApplicationError | Error}> = T['error'] extends ApplicationError ? ApplicationError : Error;

function getError<T extends { error: ApplicationError | Error }>(response: T): ErrorType<T> {
    if (response.error instanceof ApplicationError) {
        return <ErrorType<T>>response.error;
    }
    return <ErrorType<T>>response.error;
}

You can see that we have the same results but without doing overloading. The only thing is we need to tell the typescript compiler the return type of function explicitly by doing >. You can also use any type and typescript will give the same result.
Now consider you are going to add one error type to the application, you can simply nest the ternary operator to accommodate it.

type MyCustomError = "CustomError";

type ErrorType<
  T extends { error: ApplicationError | MyCustomError | Error }
> = T["error"] extends ApplicationError
  ? ApplicationError
  : T["error"] extends MyCustomError
  ? MyCustomError
  : Error;

Summary

The conditional types might look difficult to understand the first time but it's worth putting effort into exploring the usage of conditional types and using it.
Further Reading:-
https://medium.com/r/?url=https%3A%2F%2Fwww.typescriptlang.org%2Fdocs%2Fhandbook%2F2%2Fconditional-types.html
https://artsy.github.io/blog/2018/11/21/conditional-types-in-typescript/

How to override ngx-charts tooltip styles with angular-material theme?

Gaurav Soni — Mon, 02 Nov 2020 19:52:20 +0000

In this article, we will see how we can use angular material with ngx-charts.

What is ngx-charts?

ngx-charts is the charting library built with angular and D3. It is used for data visualizations. It is using Angular to render and animate the SVG elements with all of its binding and speed goodness and uses d3 for the excellent math functions, scales, axis, and shape generators.

ngx-charts come with some default styles for the tooltip, labels, legends, etc.

In this article, we will override the tooltip styles to make it look like as in the material data-visualization guidelines.

Let’s start by creating a new material theme. We are assuming that angular material is already installed. We can create our custom angular theme as follow:-

As a next step, we will create scss mixin which will accept the angular material theme and override the tooltip style for us.
The mixin is like below:-

We are assuming here the tooltip is consistent throughout the application. So we are good to override the style with !important.
As you can see, we have access to angular material typography, mixins variables, etc. A couple of points to notice:-

We are targetting the .ngx-charts-tooltip directly. But we can wrap it in our custom class wrapper to avoid collision with some other components in case we are writing a library. * As the tooltip caret is separate from the tooltip box so we need to override the background color for carets separately(.tooltip-caret.position-right etc). * We are using mat-elevation mixin from angular material to provide the box-shadow to the tooltip. You can read more about it here. * We are also using the secondary-text color from the material theme to make the sub-label looks like the secondary. * We are also getting the font-size from the material typography and making the sub-label as per the material data-visualization guidelines. Although we can also apply the mat-body-2 class in HTML(on span tag in below HTML file) as well I believe it's better to put the related code in the same class as have access to it. We can also override the other things axis labels, legend labels, etc with the material typography and theme.

The basic idea is to have the charts consistent with the material theme. So that if we implement multiple themes, then we can have our ngx-charts styles according to the other themes as well.

Our HTML file will look like:-

The end result will look like below:-

Stackblitz example:-