@asphalt-react/sidebar

Sidebar

Sidebar is used to display vertical primary navigation. It contains a list of links that can either take the user to another page or to another section on the same page. You can nest and categorize navigation links (a.k.a nav items). Sidebar is responsive and adapts to small, medium & large screens. You can also create a custom Sidebar through a family of unit components exported by Sidebar.

Usage

import { Sidebar, Nav, NavItem, NavLink } from "@asphalt-react/sidebar"

function App () {

  return (
    <Sidebar>
      <Nav>
        <NavItem>
          <NavLink active asProps={{ href: "example.com" }}>Home</NavLink>
        </NavItem>
        <NavItem>
          <NavLink asProps={{ href: "example.com/dashboard" }}>Dashboard</NavLink>
        </NavItem>
      </Nav>
    </Sidebar>
  );
}

export default App;

Anatomy

Sidebar has 3 sections:

• Head: Add items in the head section such as Logo using the head prop.
• Body: Contains the list of navigation items. This is the children.
• Tail: Add items in the tail section such as user Avatar or logout button using the tail prop.

Navigation items

Sidebar exports a family of unit components to create the nav items:

• Nav
• NavItem
• NavLink
• NavItemCaption
• NavItemIcon
• NavItemAction
• NavMenu
• NavCategory

Using these components, you can create nav items, nested nav items (or nav menus) and even categorize them.

<Sidebar>
  <Nav>
    <NavItem>
      <NavLink asProps={{ href: "example.com" }}>Home</NavLink>
    </NavItem>
    <NavItem>
      <NavLink asProps={{ href: "example.com" }}>Orders</NavLink>
    </NavItem>
    <NavCategory>Settings</NavCategory>
    <NavItem>
      <NavLink asProps={{ href: "example.com" }}>Profile</NavLink>
    </NavItem>
    <NavItem>
      <NavLink asProps={{ href: "example.com" }}>Address</NavLink>
    </NavItem>
  </Nav>
</Sidebar>

Find more details about these components below.

Screen size adaptability

Sidebar adapts to smaller screens (below 600px) and renders the head section at the top of Sidebar's container. The body and tail sections are hidden under a hamburger button that appears in the head section.

Activating the hamburger button shows the hidden sections in a container (or drawer) that covers the complete screen. The hamburger button is replaced by a cross button to close the drawer. Sidebar also exposes a close() function that to close the drawer. It can be useful if you want to close the drawer on selecting a nav item. For example:

import { Sidebar, Nav, NavItem, NavLink } from "@asphalt-react/sidebar"

function App () {
  const close = () => Sidebar.close

  return (
    <Sidebar>
      <Nav>
        <NavItem>
          <NavLink onClick={close} asProps={{ href: "example.com" }}>Dashboard</NavLink>
        </NavItem>
      </Nav>
    </Sidebar>
  )
}

Accessibility

Sidebar adapts to smaller screens (below 600px) with the following accessibility features,

• Sidebar accepts Esc to close the drawer.
• Sidebar also traps focus in the drawer. Press Tab or Shift + Tab to toggle through the focusable elements.

Creating a custom Sidebar

Sidebar exports layout unit components using which you can create a custom implementation of Sidebar:

• BaseSidebar
• SidebarHead
• SidebarBody
• SidebarTail

These layout components do not respond to different screen sizes. You can wrap them in containers with media queries for the custom Sidebar to adapt to screen sizes. For example:

@media only screen and (max-width: 600px) {
  .container {
    /* some styles */
  }

  .content {
    /* some styles */
  }
}

const CustomSidebar = () => {
  return (
    <div className="container">
      <BaseSidebar>
        <div className="content">
          <SidebarBody>
            // NavItems
          </SidebarBody>
        </div>
      </BaseSidebar>
    </div>
  )
}

Find details about these components below.

Hooks

Sidebar exports a useSidebar hook to help you create custom functionality.

useSidebar

React hook to implement the ability to open/close the Sidebar drawer in smaller screens. Let's look at the usage:

import { BaseSidebar, useSidebar } from "@asphalt-react/sidebar"

const CustomSidebar = () => {
  const { visible, open, close } = useSidebar({ defaultVisible: true })

  return (
      <BaseSidebar>
        <div className={visible ? "show" : "hide"}>
          {visible ? (
            <Button onClick={close}>close</Button>
          ) : (
            <Button onClick={open}>open</Button>
          )}
        </div>
      </BaseSidebar>
  )
}

useSidebar returns an object with:

• visible: A stateful boolean value to control the (open/close) state.
• open: A function to open the drawer.
• close: A function to close the drawer.

useSidebar accepts the defaultVisible prop as the argument.

Props

children

React node to render in the Sidebar content.

type	required	default
node	true	N/A

head

Content to display in the Sidebar head.

<Sidebar head={<Logo />}>
   // children
</Sidebar>

type	required	default
node	false	null

tail

Content to display in the Sidebar tail.

<Sidebar tail={<Button>Logout</Button>}>
   // children
</Sidebar>

type	required	default
node	false	null

dismissLabel

"aria-label" for the button to hide the body section in smaller screens.

type	required	default
string	false	"close sidebar navigation"

menuLabel

"aria-label" for the button to show the body section in smaller screens.

type	required	default
string	false	"open sidebar navigation"

defaultVisible

Sidebar shows the body section in the initial state.

type	required	default
bool	false	false

Nav

The Nav component renders a <ul> tag to render the list of NavItem components.

Props

children

React nodes to render in the Nav content.

type	required	default
node	true	N/A

NavItem

NavItem is the container for a navigation item. It renders an <li> tag and should be the direct child of the Nav component.

Props

children

Content for a nav item.

type	required	default
node	true	N/A

NavItemCaption

Renders the caption for a nav item.

Props

children

React node to render the caption of the nav item.

type	required	default
node	true	N/A

NavItemIcon

Use NavItemIcon to render icon for the nav items. It only accepts SVG. Use "@asphalt-react/iconpack" to get all Asphalt React icons.

Props

children

Icon to enhance the nav item's caption. Accepts SVG.

type	required	default
node	true	N/A

NavItemAction

Accepts elements for custom actions in a NavItem.

Props

children

React node to render action elements for a nav item.

type	required	default
node	true	N/A

propagateEvent

Allow events to propagate to the parent element. It's false by default to prevent events on action elements to bubble up to the parent element. It comes in handy when you want to prevent navigation but still allow the action.

<NavLink asProps={{ href: "example.com" }}>
   <NavItemCaption>Home</NavItemCaption>
   <NavItemAction>
     <Button onClick={clickHandler}>action</Button>
   </NavItemAction>
</NavLink>

type	required	default
bool	false	false

NavLink

Renders the link element (defaults to <a>) for a NavItem. The NavLinks accepts an active prop to let users know which item is currently selected.

Active styles

NavLinks accept 2 active styles:

• Prominent (default)
• Highlight

If you use both the active styles together on a NavLink, it logs a warning in the developer console and falls back to the default active style.

/* Logs a warning and falls back to "prominent" active style */
<NavLink active prominent highlight>Home<NavLink>

Props

children

React node to render link content.

type	required	default
node	true	N/A

as

Html element/React component to replace the default element. Using this prop, you can use your router's link element, such as "react-router-dom"'s Link element.

type	required	default
elementType	false	"a"

asProps

Pass the props such as "href", "id" for the custom link element passed in as prop.

type	required	default
object	false	{}

active

Marks the nav item as active.

type	required	default
bool	false	false

prominent

The default active style. Adds an indicator to accent the active nav item.

type	required	default
bool	false	false

highlight

A subtle active style. Highlights the surface of the nav item.

type	required	default
bool	false	false

bezel

Adds padding on all sides.

type	required	default
bool	false	true

NavMenu

NavMenu creates nested nav items. NavMenu renders a <ul> tag and should be the direct child of Nav component. For example:

<Sidebar>
  <Nav>
    <NavItem>Settings</NavItem>
    <NavMenu>
      <NavItem>Profile</NavItem>
      <NavItem>Notification</NavItem>
    </NavMenu>
  </Nav>
<Sidebar>

The "Profile" and "Notification" NavItems will be indented from the rest of the NavItems.

Props

children

React node to render nested NavItems.

type	required	default
node	true	N/A

hide

Hides the content of the NavMenu. Use this prop to toggle NavMenu items.

type	required	default
bool	false	false

NavCategory

Using NavCategory component, you can group a list of nav items based on related category.

Props

children

Divide nav items into categories.

type	required	default
node	true	N/A

bezel

Adds padding on all sides.

type	required	default
bool	false	true

BaseSidebar

The base container unit component.

Props

children

Container for the Sidebar content.

type	required	default
node	true	N/A

SidebarHead

The unit component for rendering the head section.

Props

children

React node to render content in the head section.

type	required	default
node	true	N/A

bezel

Adds padding on all sides.

type	required	default
bool	false	true

SidebarBody

The unit component to render the main content or body.

Props

children

Container to render the nav items.

type	required	default
node	true	N/A

bezel

Adds padding on all sides.

type	required	default
bool	false	true

SidebarTail

The unit component for rendering the tail section.

Props

children

React node to render content in the tail section.

type	required	default
node	true	N/A

bezel

Adds padding on all sides.

type	required	default
bool	false	true