Navigation

cds-navigation

The Navigation provides a structured way for users to explore and access different sections of an application. It includes primary and secondary levels of navigation, allowing for clear organization and easy movement between features. This component enhances usability by offering a consistent and intuitive browsing experience across the interface.

---

• DIVIDER

<ul class="cds-navigation">
  <li class="cds-navigation__item">
      <button class="cds-navigation__button">
          <span class="cds-navigation__button__icon cds-ph-eye"></span>
          <span class="cds-navigation__button__text">Text</span>
      </button>
      <ul class="cds-subnavigation">
        <li class="cds-subnavigation__item">
            <button class="cds-subnavigation__button">
                <span class="cds-subnavigation__button__text">Default subitem</span>
            </button>
        </li>
        ...
      </ul>
  </li>
  ...
</ul>

---

Elements

Navigation

Element	Code	Parent	HTML tag	Required
Item	cds-navigation__item	Block: cds-navigation	<li>	required
└─ Button	cds-navigation__button	Element: cds-navigation__item	<button>	optional
└─ Divider	cds-navigation__divider	Element: cds-navigation__item	<span>	optional
└─ Subnavigation	cds-subnavigation	Element: cds-navigation__item	<ul>	optional

1st level Button

Element	Code	Parent	HTML tag	Required
Icon	cds-navigation__button__icon	Element: cds-navigation__button	<span>	optional
Avatar	Component: cds-avatar	Element: cds-navigation__button	cds-avatar	optional
Text	cds-navigation__button__text	Element: cds-navigation__button	<span>	required
Badge	Component: cds-badge	Element: cds-navigation__button	cds-badge	optional

Uses of icons and avatars

You can choose to display an icon or an avatar (or just text), but not more than one at the same time.
Avatars are typically used for user-related items or similar content.

---

Subnavigation

Element	Code	Parent	HTML tag	Required
Item	cds-subnavigation__item	Element: cds-subnavigation	<li>	optional
└─ Button	cds-subnavigation__button	Element: cds-subnavigation__item	<button>	optional
└─ Divider	cds-subnavigation__divider	Element: cds-subnavigation__item	<span>	optional

2nd level Button

Element	Code	Parent	HTML tag	Required
Text	cds-subnavigation__button__text	Element: cds-subnavigation__button	<span>	required
Icon	cds-subnavigation__button__icon	Element: cds-subnavigation__button	<span>	optional
Badge	Component: cds-badge	Element: cds-navigation__button	cds-badge	optional

Icon Placement and Usage

The icon on subnavigation items always should be placed after the text. It is only used for actions that open external links in a new tab or for logout functions, using apropiate icons.

---

---

States

This states affects only at the buttons of each navigation item.

Modifier	Options
States	is-active, is-disabled

Is Active

---

<li class="cds-navigation__item is-active">
<li class="cds-subnavigation__item is-active">

Is Disabled

---

<li class="cds-navigation__item is-disabled">
<li class="cds-subnavigation__item is-disabled">

Open direction

You can control the opening direction of the subnavigation relative to its parent. By default, it opens below the parent, but to open it above, simply swap the order of the button and the subnavigation <ul> in the markup.

<!-- Down open direction -->
<li class="cds-navigation__item">
    <button class="cds-navigation__button">...
    <ul class="cds-subnavigation">...
</li>

<!-- Up open direction -->
<li class="cds-navigation__item">
    <ul class="cds-subnavigation">...
    <button class="cds-navigation__button">...
</li>

---

---

JS Sample code

JS sample code - Open/Close sidebar items

let navItems = document.querySelectorAll(".cds-navigation__button");

for (let i = 0; i < navItems.length; i++) {
    navItems[i].addEventListener("click", (e) => {
        e.stopPropagation();

        let closestNavItem = e.target.closest(".cds-navigation__item");

        document.querySelectorAll('.cds-navigation__item.is-opened').forEach(item => {
            if (item !== closestNavItem) {
                item.classList.remove('is-opened');
            }
        });

        closestNavItem.classList.toggle("is-opened");
    });
}

JS sample code - Close subnavigation when clicking outside

document.addEventListener("click", (e) => {
    const isCompact = document.querySelector("[sidebar-style='compact']") !== null;
    if (isCompact && !e.target.closest(".cds-navigation__item")) {
        document.querySelectorAll('.cds-navigation__item.is-opened').forEach(item => {
            item.classList.remove('is-opened');
        });
    }
});