VerticalNavigation

Navigation enables users to move through an app to complete tasks.

It is recommended to use vertical navigation when your application requires global navigation that is displayed on the left. While vertical navigation menus generally consume more space than their horizontal counterparts, they have become more popular as desktop monitors move to wide-screen formats.

Although both the hierarchically organized data and the visual style resemble a treeview-like structure, the Treeview Design Pattern isn't necessarily the most appropriate.

The tree role provides complex functionality that is not needed for typical site navigation, and changes the most common keyboard navigation using TAB.

The Disclosure Design Pattern is more suited for typical site navigation, with expandable groups of links. However it can be tedious to TAB through all navigation items to reach the actions panel.

Both modes are available via the mode property and each app should choose the most appropriate.

Source Code

uikit-react-core

Usage

The sample below illustrates a common use of the HvVerticalNavigation component. The HvVerticalNavigationTree component is used to render the navigation tree. The HvVerticalNavigationActions component is used to render the actions at the bottom of the navigation.

import { useState } from "react";


export default function Demo() {
  const [value, setValue] = useState("00");


  return (
    <HvVerticalNavigation>
      <HvVerticalNavigationTree
        aria-label="Example 1 navigation"
        selected={value}
        onChange={(event, data) => {
          if (data.id === "02-01-01") {
            event.preventDefault();
            event.stopPropagation();
          }
          setValue(data.id);
        }}
        data={navigationData}
      />
      <HvVerticalNavigationActions>
        <HvVerticalNavigationAction label="Profile" icon={<User />} />
        <HvVerticalNavigationAction label="Logout" icon={<LogOut />} />
      </HvVerticalNavigationActions>
    </HvVerticalNavigation>
  );
}


const navigationData = [
  { id: "00", label: "Overview" },
  { id: "01", label: "Analytics" },
  {
    id: "02",
    label: "Storage",
    data: [
      {
        id: "02-01",
        label: "Cloud",
        data: [
          {
            id: "02-01-01",
            label: "Servers",
            href: "https://www.hitachivantara.com/en-us/news.html",
          },
          {
            id: "02-01-02",
            label: "HCP Anywhere",
          },
          {
            id: "02-01-03",
            label: "This Computer",
            disabled: true,
          },
        ],
      },
    ],
  },
  {
    id: "03",
    label: "Administration",
    href: "#admin",
    data: [
      {
        id: "03-01",
        label: "Rest API",
        href: "#admin-rest",
        data: [
          {
            id: "03-01-01",
            label: "Log Bundle",
            href: "#admin-rest-logs",
          },
        ],
      },
    ],
  },
];

import { useState } from "react";

export default function Demo() {
  const [value, setValue] = useState("00");

  return (
    <HvVerticalNavigation>
      <HvVerticalNavigationTree
        aria-label="Example 1 navigation"
        selected={value}
        onChange={(event, data) => {
          if (data.id === "02-01-01") {
            event.preventDefault();
            event.stopPropagation();
          }
          setValue(data.id);
        }}
        data={navigationData}
      />
      <HvVerticalNavigationActions>
        <HvVerticalNavigationAction label="Profile" icon={<User />} />
        <HvVerticalNavigationAction label="Logout" icon={<LogOut />} />
      </HvVerticalNavigationActions>
    </HvVerticalNavigation>
  );
}

const navigationData = [
  { id: "00", label: "Overview" },
  { id: "01", label: "Analytics" },
  {
    id: "02",
    label: "Storage",
    data: [
      {
        id: "02-01",
        label: "Cloud",
        data: [
          {
            id: "02-01-01",
            label: "Servers",
            href: "https://www.hitachivantara.com/en-us/news.html",
          },
          {
            id: "02-01-02",
            label: "HCP Anywhere",
          },
          {
            id: "02-01-03",
            label: "This Computer",
            disabled: true,
          },
        ],
      },
    ],
  },
  {
    id: "03",
    label: "Administration",
    href: "#admin",
    data: [
      {
        id: "03-01",
        label: "Rest API",
        href: "#admin-rest",
        data: [
          {
            id: "03-01-01",
            label: "Log Bundle",
            href: "#admin-rest-logs",
          },
        ],
      },
    ],
  },
];

Tree view

Usage of the Treeview Design Pattern to build a navigation tree for a set of hierarchically organized web pages. Instead of TAB, use the arrow keys to navigate through items. Enter performs its default action (i.e. open/close parent nodes, select otherwise).

Set the mode prop to treeview to enable the tree view and set collpasible to true to enable collpasing non-leaf items.

import { useState } from "react";


export default function Demo() {
  const [value, setValue] = useState("01-01");


  return (
    <HvVerticalNavigation>
      <HvVerticalNavigationTree
        mode="treeview"
        collpasible
        defaultExpanded
        aria-label="Example 3 navigation"
        selected={value}
        onChange={(event, data) => setValue(data.id)}
        data={navigationData}
      />
      <HvVerticalNavigationActions>
        <HvVerticalNavigationAction label="Profile" icon={<User />} />
        <HvVerticalNavigationAction label="Logout" icon={<LogOut />} />
      </HvVerticalNavigationActions>
    </HvVerticalNavigation>
  );
}


const navigationData = [
  { id: "00", label: "Installation Overview" },
  {
    id: "01",
    label: "Hardware",
    data: [
      {
        id: "01-01",
        label: "Ambient Monitoring",
      },
      {
        id: "01-02",
        label: "Server Status Summary",
      },
    ],
  },
  {
    id: "02",
    label: "System",
    data: [
      {
        id: "02-01",
        label: "Buckets",
      },
      {
        id: "02-02",
        label: "Admin Users",
      },
      {
        id: "02-03",
        label: "Log Bundle",
        data: [
          {
            id: "02-03-01",
            label: "Rest API",
          },
          {
            id: "02-03-02",
            label: "License",
          },
        ],
      },
    ],
  },
];

import { useState } from "react";

export default function Demo() {
  const [value, setValue] = useState("01-01");

  return (
    <HvVerticalNavigation>
      <HvVerticalNavigationTree
        mode="treeview"
        collpasible
        defaultExpanded
        aria-label="Example 3 navigation"
        selected={value}
        onChange={(event, data) => setValue(data.id)}
        data={navigationData}
      />
      <HvVerticalNavigationActions>
        <HvVerticalNavigationAction label="Profile" icon={<User />} />
        <HvVerticalNavigationAction label="Logout" icon={<LogOut />} />
      </HvVerticalNavigationActions>
    </HvVerticalNavigation>
  );
}

const navigationData = [
  { id: "00", label: "Installation Overview" },
  {
    id: "01",
    label: "Hardware",
    data: [
      {
        id: "01-01",
        label: "Ambient Monitoring",
      },
      {
        id: "01-02",
        label: "Server Status Summary",
      },
    ],
  },
  {
    id: "02",
    label: "System",
    data: [
      {
        id: "02-01",
        label: "Buckets",
      },
      {
        id: "02-02",
        label: "Admin Users",
      },
      {
        id: "02-03",
        label: "Log Bundle",
        data: [
          {
            id: "02-03-01",
            label: "Rest API",
          },
          {
            id: "02-03-02",
            label: "License",
          },
        ],
      },
    ],
  },
];

Collapsible

If you want the navigation to be collapsible, you can use the HvVerticalNavigationHeader component to add a collapse button to the navigation. You’ll have to manage the open state of the navigation yourself and pass it to the open prop of the HvVerticalNavigation component. The collapse button will show if you pass a handler function to the onCollapseButtonClick prop.

You can also use the useIcons prop to show icons in the navigation when collapsed, if an icon is not provided one will be generated based on the first letter of the label.

Show Icons

import { useState } from "react";


export default function Demo() {
  const [value, setValue] = useState("01-01");
  const [show, setShow] = useState(false);
  const [icons, setIcons] = useState(false);


  const handleIsExpanded = () => {
    setShow(!show);
  };


  return (
    <div className="flex gap-xs" style={{ height: 400 }}>
      <HvCheckBox
        label="Show Icons"
        checked={icons}
        onChange={() => setIcons(!icons)}
      />
      <HvVerticalNavigation open={show} useIcons={icons}>
        <HvVerticalNavigationHeader
          title="Menu"
          onCollapseButtonClick={handleIsExpanded}
          collapseButtonProps={{
            "aria-label": "collapseButton",
            "aria-expanded": show,
          }}
        />
        <HvVerticalNavigationTree
          collapsible
          defaultExpanded
          aria-label="Example 3 navigation"
          selected={value}
          onChange={(event, data) => setValue(data.id)}
          data={navigationData}
        />
      </HvVerticalNavigation>
    </div>
  );
}


const navigationData = [
  { id: "00", label: "Installation Overview", icon: <Open /> },
  {
    id: "01",
    label: "Hardware",
    icon: <BarChart />,
    data: [
      { id: "01-01", label: "Ambient Monitoring", icon: <BarChart /> },
      { id: "01-02", label: "Server Status Summary" },
    ],
  },
  {
    id: "02",
    label: "System",
    icon: <Deploy />,
    data: [
      { id: "02-01", label: "Buckets", icon: <Deploy /> },
      { id: "02-02", label: "Admin Users" },
      {
        id: "02-03",
        label: "Log Bundle",
        data: [
          { id: "02-03-01", label: "Rest API" },
          { id: "02-03-02", label: "License" },
        ],
      },
    ],
  },
  {
    id: "03",
    label: "System 2",
    data: [
      { id: "03-01", label: "Buckets" },
      { id: "03-02", label: "Admin Users" },
      {
        id: "03-03",
        label: "Log Bundle",
        data: [
          { id: "03-03-01", label: "Rest API" },
          { id: "03-03-02", label: "License" },
        ],
      },
    ],
  },
];

import { useState } from "react";

export default function Demo() {
  const [value, setValue] = useState("01-01");
  const [show, setShow] = useState(false);
  const [icons, setIcons] = useState(false);

  const handleIsExpanded = () => {
    setShow(!show);
  };

  return (
    <div className="flex gap-xs" style={{ height: 400 }}>
      <HvCheckBox
        label="Show Icons"
        checked={icons}
        onChange={() => setIcons(!icons)}
      />
      <HvVerticalNavigation open={show} useIcons={icons}>
        <HvVerticalNavigationHeader
          title="Menu"
          onCollapseButtonClick={handleIsExpanded}
          collapseButtonProps={{
            "aria-label": "collapseButton",
            "aria-expanded": show,
          }}
        />
        <HvVerticalNavigationTree
          collapsible
          defaultExpanded
          aria-label="Example 3 navigation"
          selected={value}
          onChange={(event, data) => setValue(data.id)}
          data={navigationData}
        />
      </HvVerticalNavigation>
    </div>
  );
}

const navigationData = [
  { id: "00", label: "Installation Overview", icon: <Open /> },
  {
    id: "01",
    label: "Hardware",
    icon: <BarChart />,
    data: [
      { id: "01-01", label: "Ambient Monitoring", icon: <BarChart /> },
      { id: "01-02", label: "Server Status Summary" },
    ],
  },
  {
    id: "02",
    label: "System",
    icon: <Deploy />,
    data: [
      { id: "02-01", label: "Buckets", icon: <Deploy /> },
      { id: "02-02", label: "Admin Users" },
      {
        id: "02-03",
        label: "Log Bundle",
        data: [
          { id: "02-03-01", label: "Rest API" },
          { id: "02-03-02", label: "License" },
        ],
      },
    ],
  },
  {
    id: "03",
    label: "System 2",
    data: [
      { id: "03-01", label: "Buckets" },
      { id: "03-02", label: "Admin Users" },
      {
        id: "03-03",
        label: "Log Bundle",
        data: [
          { id: "03-03-01", label: "Rest API" },
          { id: "03-03-02", label: "License" },
        ],
      },
    ],
  },
];

Slider

If you set the slider prop to true, the navigation will be displayed as a slider instead of a tree. When the user selects an item that contains children, the content of the navigation will be replaced with the children of the selected item.

You can use this functionality to display the navigation in regular tree view mode and switch to slider mode when the screen size is lower that a certain threshold.

import { useState } from "react";


export default function Demo() {
  const [value, setValue] = useState("menu1-3");


  return (
    <HvVerticalNavigation open slider>
      <HvVerticalNavigationHeader title="Menu" />
      <HvVerticalNavigationTree
        collapsible
        defaultExpanded
        aria-label="Example 4 Slider Mode"
        selected={value}
        onChange={(event, data) => setValue(data.id)}
        data={navigationData}
      />
    </HvVerticalNavigation>
  );
}


const navigationData = [
  {
    id: "menu1",
    label: "Menu 1",
    path: "",
    icon: <Open />,
    data: [
      {
        id: "menu1-1",
        label: "Menu 1-1",
        path: "",
        icon: <Open />,
        parent: null,
      },
      {
        id: "menu1-2",
        label: "Menu 1-2",
        path: "",
        icon: <BarChart />,
        data: [
          {
            id: "menu1-2-1",
            label: "Menu 1-2-1",
            path: "",
            icon: <Open />,
            parent: null,
          },
          {
            id: "menu1-2-2",
            label: "Menu 1-2-2",
            path: "",
            icon: <BarChart />,
            parent: null,
          },
          {
            id: "menu1-2-3",
            label: "Menu 1-2-3",
            path: "",
            icon: <Deploy />,
            parent: null,
          },
        ],
        parent: null,
      },
      {
        id: "menu1-3",
        label: "Menu 1-3",
        path: "",
        icon: <Deploy />,
        parent: null,
      },
    ],
    parent: null,
  },
  {
    id: "menu2",
    label: "Menu 2 with a very big name that should be truncated",
    path: "",
    icon: <BarChart />,
    parent: null,
  },
  {
    id: "menu3",
    label: "Menu 3",
    path: "",
    icon: <Deploy />,
    parent: null,
  },
];

import { useState } from "react";

export default function Demo() {
  const [value, setValue] = useState("menu1-3");

  return (
    <HvVerticalNavigation open slider>
      <HvVerticalNavigationHeader title="Menu" />
      <HvVerticalNavigationTree
        collapsible
        defaultExpanded
        aria-label="Example 4 Slider Mode"
        selected={value}
        onChange={(event, data) => setValue(data.id)}
        data={navigationData}
      />
    </HvVerticalNavigation>
  );
}

const navigationData = [
  {
    id: "menu1",
    label: "Menu 1",
    path: "",
    icon: <Open />,
    data: [
      {
        id: "menu1-1",
        label: "Menu 1-1",
        path: "",
        icon: <Open />,
        parent: null,
      },
      {
        id: "menu1-2",
        label: "Menu 1-2",
        path: "",
        icon: <BarChart />,
        data: [
          {
            id: "menu1-2-1",
            label: "Menu 1-2-1",
            path: "",
            icon: <Open />,
            parent: null,
          },
          {
            id: "menu1-2-2",
            label: "Menu 1-2-2",
            path: "",
            icon: <BarChart />,
            parent: null,
          },
          {
            id: "menu1-2-3",
            label: "Menu 1-2-3",
            path: "",
            icon: <Deploy />,
            parent: null,
          },
        ],
        parent: null,
      },
      {
        id: "menu1-3",
        label: "Menu 1-3",
        path: "",
        icon: <Deploy />,
        parent: null,
      },
    ],
    parent: null,
  },
  {
    id: "menu2",
    label: "Menu 2 with a very big name that should be truncated",
    path: "",
    icon: <BarChart />,
    parent: null,
  },
  {
    id: "menu3",
    label: "Menu 3",
    path: "",
    icon: <Deploy />,
    parent: null,
  },
];

Custom content

Custom App

import { useState } from "react";


export default function Demo() {
  const [collapsed, setCollapsed] = useState(false);


  return (
    <HvVerticalNavigation open={!collapsed} useIcons>
      <div
        className="flex flex-col gap-md"
        style={{ alignItems: collapsed ? "center" : "stretch" }}
      >
        {collapsed ? (
          <Favorite />
        ) : (
          <div className="flex items-center">
            <Favorite style={{ "--color-0": "inherit" }} />
            <HvTypography variant="label" style={{ color: "inherit" }}>
              Custom App
            </HvTypography>
          </div>
        )}
        <CollapsibleButton
          collapsed={collapsed}
          variant="primary"
          icon={<Add />}
          label="Create"
        />
      </div>
      <HvVerticalNavigationTree data={data} />
      <HvVerticalNavigationActions>
        <div className="relative">
          {!collapsed && (
            <Backwards
              color="currentcolor"
              className="absolute pointer-events-none top-0px right-0px"
            />
          )}
          <HvVerticalNavigationAction
            label={collapsed ? "Expand menu" : "Collapse menu"}
            icon={collapsed ? <Forwards /> : undefined}
            onClick={() => setCollapsed((prev) => !prev)}
          />
        </div>
      </HvVerticalNavigationActions>
    </HvVerticalNavigation>
  );
}


const CollapsibleButton = ({
  collapsed,
  label,
  icon,
  ...others
}: CollapsibleButtonProps) => {
  const props = collapsed
    ? { "aria-label": String(label), children: icon, icon: true }
    : { startIcon: icon, children: label };


  return <HvButton {...props} {...others} />;
};


const data = [
  { id: "00", label: "Jobs", icon: <Job /> },
  { id: "01", label: "Charts", icon: <BarChart /> },
  { id: "02", label: "Deployment", icon: <Deploy /> },
  { id: "03", label: "Cloud", icon: <Cloud /> },
];

import { useState } from "react";

export default function Demo() {
  const [collapsed, setCollapsed] = useState(false);

  return (
    <HvVerticalNavigation open={!collapsed} useIcons>
      <div
        className="flex flex-col gap-md"
        style={{ alignItems: collapsed ? "center" : "stretch" }}
      >
        {collapsed ? (
          <Favorite />
        ) : (
          <div className="flex items-center">
            <Favorite style={{ "--color-0": "inherit" }} />
            <HvTypography variant="label" style={{ color: "inherit" }}>
              Custom App
            </HvTypography>
          </div>
        )}
        <CollapsibleButton
          collapsed={collapsed}
          variant="primary"
          icon={<Add />}
          label="Create"
        />
      </div>
      <HvVerticalNavigationTree data={data} />
      <HvVerticalNavigationActions>
        <div className="relative">
          {!collapsed && (
            <Backwards
              color="currentcolor"
              className="absolute pointer-events-none top-0px right-0px"
            />
          )}
          <HvVerticalNavigationAction
            label={collapsed ? "Expand menu" : "Collapse menu"}
            icon={collapsed ? <Forwards /> : undefined}
            onClick={() => setCollapsed((prev) => !prev)}
          />
        </div>
      </HvVerticalNavigationActions>
    </HvVerticalNavigation>
  );
}

const CollapsibleButton = ({
  collapsed,
  label,
  icon,
  ...others
}: CollapsibleButtonProps) => {
  const props = collapsed
    ? { "aria-label": String(label), children: icon, icon: true }
    : { startIcon: icon, children: label };

  return <HvButton {...props} {...others} />;
};

const data = [
  { id: "00", label: "Jobs", icon: <Job /> },
  { id: "01", label: "Charts", icon: <BarChart /> },
  { id: "02", label: "Deployment", icon: <Deploy /> },
  { id: "03", label: "Cloud", icon: <Cloud /> },
];

Tree View Wizard