Skip to content

Sidebar ​

The primary navigation. Menu schema, states, keyboard model, and the accessibility details most templates get wrong.


Markup ​

The shipped tree, from html/_partials/sidebar.html. The same tree serves all ten data-av-layout arrangements — see Layout Modes — so nothing here is specific to the vertical rail.

html
<aside class="av-sidebar" id="avSidebar">

  <div class="av-sidebar__brand">
    <a href="/" class="av-brand">
      <img class="av-brand__mark" src="/src/img/logo-mark.svg" alt="" width="32" height="32">
      <span class="av-brand__text">AdminVora</span>
    </a>
    <button class="av-btn av-btn--ghost av-btn--icon av-sidebar-collapse" type="button"
            data-av-sidebar-toggle
            aria-label="Collapse sidebar" aria-expanded="true" aria-controls="avSidebar">
      <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
        <path d="M15 6l-6 6 6 6"/>
      </svg>
    </button>
  </div>

  <nav class="av-sidebar__nav" aria-label="Main">
    <ul class="av-menu">

      <li class="av-menu__group">
        <details class="av-menu__disclosure" open>
          <summary class="av-menu__title" id="avGroupCommerce">
            <span class="av-menu__title-text">Commerce</span>
            <svg class="av-icon av-menu__caret" aria-hidden="true" viewBox="0 0 24 24"
                 fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
          </summary>

          <ul class="av-menu__group-list" aria-labelledby="avGroupCommerce">
            <li class="av-menu__item av-menu__item--active">
              <a class="av-menu__link" href="/orders" aria-current="page">
                <svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
                  <path d="M6 7h12l-1 13H7L6 7z"/><path d="M9 7a3 3 0 0 1 6 0"/>
                </svg>
                <span class="av-menu__label">Orders</span>
                <span class="av-menu__badge">12</span>
              </a>
            </li>
            <li class="av-menu__item">
              <a class="av-menu__link" href="/products">
                <svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
                  <path d="M12 3l8 4.5v9L12 21l-8-4.5v-9L12 3z"/>
                </svg>
                <span class="av-menu__label">Products</span>
              </a>
            </li>
          </ul>
        </details>
      </li>

    </ul>
  </nav>

  <div class="av-sidebar__footer">
    <p class="av-field-line__hint">You have used <strong>82%</strong> of your plan.</p>
    <div class="av-progress" role="progressbar" aria-valuenow="82" aria-valuemin="0"
         aria-valuemax="100" aria-label="Plan usage">
      <div class="av-progress__bar" style="inline-size: 82%"></div>
    </div>
    <a class="av-btn av-btn--primary av-btn--block" href="/billing">Upgrade</a>
  </div>

</aside>

<details>/<summary>, not a button and a class ​

This is the decision the rest of the page follows from, and it replaces what an earlier revision specified — <button aria-expanded> plus .av-menu__item--has-children, .av-menu__item--open and .av-menu__sub. None of those exists, and the platform element is better on every axis that matters:

What you would have writtenWhat <details> gives you
aria-expanded toggled in JavaScriptOwned by the element, and correct before any script runs
aria-controls pointing at the <ul>Implicit in the parent/child relationship
A click handler, and a keyboard handler beside itEnter and Space on the <summary>, from the platform
A --open class kept in step with the stateThe [open] attribute, which is the state
An is-open style hook.av-menu__disclosure[open], which cannot disagree with itself

The group heading is a <summary class="av-menu__title">, so it is focusable, announced with its expanded state, and operable with no JavaScript at all. A menu that works with the runtime removed is the property this buys, and it is why the six bar layouts can re-lay-out the same markup without re-implementing any of it.

The list carries aria-labelledby pointing at the summary's id, so the group of links is named by its heading rather than being an anonymous <ul>.

There is one level of grouping. Depth beyond two levels is what the two-column layout exists for.

The collapse control is .av-btn.av-btn--ghost.av-btn--icon.av-sidebar-collapse. Its chevron is drawn pointing the right way and the rail's own rules handle RTL.

The sidebar is found by class, and the nav scrolls natively — there is no custom scrollbar library.

Critical details ​

DetailWhy
Parents are <button>, not <a href="#">They perform an action, not navigation. A # link puts a junk entry in history and is announced as a link.
aria-expanded on the parent buttonThe only way a screen reader knows the submenu state
aria-controls pointing at the <ul> idAssociates the button with what it controls
aria-current="page" on the active linkAnnounced as "current page"; .is-active alone is invisible to AT
alt="" on the logo imageThe adjacent text is the accessible name; a duplicate would be announced twice
av-menu__title with aria-hidden="true"Visual grouping label; it is not a heading and should not be announced as content
Badge inside the linkAnnounced as part of the link name: "Orders 12"

States ​

StateAttribute / classEffect
Expandeddata-av-sidebar="expanded"264px, labels visible
Collapseddata-av-sidebar="collapsed"72px, icons only, flyout on hover/focus
Hiddendata-av-sidebar="hidden"0px, off-canvas
Mobile opendata-av-sidebar="mobile-open"Overlays with a backdrop, below lg
Item active.av-menu__item--active + aria-current="page"Highlighted
Group open.av-menu__item--open + aria-expanded="true"Submenu visible
Hovered:hoverBackground tint
scss
.av-menu__link {
  display: flex;
  align-items: center;
  gap: var(--av-space-3);
  min-block-size: var(--av-menu-item-height, 42px);
  padding-inline: var(--av-space-3);
  border-radius: var(--av-radius-md);
  color: var(--av-text-secondary);
  font-size: var(--av-font-size-sm);
  font-weight: var(--av-font-weight-medium);
  text-decoration: none;
  inline-size: 100%;
  text-align: start;
  background: none;
  border: 0;
  position: relative;

  transition: background-color var(--av-duration-fast) var(--av-ease-standard),
              color var(--av-duration-fast) var(--av-ease-standard);

  &:hover { background: var(--av-surface-sunken); color: var(--av-text-primary); }
}

.av-menu__item--active > .av-menu__link {
  background: var(--av-color-primary-subtle);
  color: var(--av-color-primary-text);
  font-weight: var(--av-font-weight-semibold);

  /* The active indicator bar */
  &::before {
    content: '';
    position: absolute;
    inset-inline-start: calc(var(--av-space-3) * -1);
    inset-block: 25%;
    inline-size: 3px;
    border-radius: 0 var(--av-radius-full) var(--av-radius-full) 0;
    background: var(--av-color-primary);
  }
}

[dir="rtl"] .av-menu__item--active > .av-menu__link::before {
  border-radius: var(--av-radius-full) 0 0 var(--av-radius-full);
}

Opening and closing a group ​

There is no animation, and display is the whole mechanism.

scss
.av-menu__disclosure[open] > .av-menu__group-list { display: flex; }
.av-menu__disclosure[open] .av-menu__caret { rotate: 180deg; }

/* Everything that is not `display` stays unconditional — it costs nothing while
   the list is hidden and keeps the two rules from drifting. */
.av-menu__group-list {
  flex-direction: column;
  gap: 2px;
  padding: 0;
  margin: 0;
  list-style: none;
}

Setting display only on the open state is not tidiness — it is the trap this rule was written around. A browser hides the contents of a closed <details> with its own display: none, and an author display declaration beats a UA one at any specificity. An unconditional display: flex left every group rendered and the whole feature silently inert: all 52 links visible with five of six groups shut. It is the same shape as [hidden] losing to an author display, which this codebase fixed globally in @layer utilities.


Keyboard model — the platform's ​

There is no sidebar module. What you get is what <summary> gives you, which is the reason the element was chosen:

KeyAction
TabMove to the next focusable item — every group heading and every visible link
Enter / SpaceFollow a link, or toggle the group under focus
EscClose the off-canvas sidebar and return focus to the toggle

Arrow-key roving, type-ahead and Home/End are not implemented. That is a gap rather than a decision, and it is worth being precise about its size: the navigation is fully operable by keyboard without them, because every control is in the tab order and announced with its state. What is missing is the faster path through a long menu.

Adding it means owning aria-expanded and the roving tabindex in JavaScript, which is what the platform is currently doing for free. Weigh that before starting.


Collapse behaviour ​

Every [data-av-sidebar-toggle] button does one of two things, decided at click time:

  • Off-canvas (below 992px, or data-av-layout="overlay" at any width): opens or closes the drawer by toggling is-mobile-open on .av-sidebar, shows [data-av-sidebar-backdrop], and moves focus to the first menu link. Esc or a click on the backdrop closes it.
  • Otherwise: flips the persisted sidebar preference between expanded and collapsed through AdminVora.theme.set('sidebar', …), which writes data-av-sidebar on <html>, and emits av:sidebar:toggle with { collapsed, source }.

Crossing the breakpoint always closes the drawer and never touches the desktop preference, so a visitor who collapsed the sidebar on desktop still finds it collapsed when they return to a wide window.


Collapsed rail, and the group that must not close with it ​

scss
[data-av-sidebar="collapsed"] .av-menu__label,
[data-av-sidebar="collapsed"] .av-menu__title-text,
[data-av-sidebar="collapsed"] .av-menu__caret,
[data-av-sidebar="collapsed"] .av-brand__text { display: none; }

[data-av-sidebar="collapsed"] .av-menu__link { justify-content: center; padding-inline: 0; }

The interaction worth knowing. The collapsed rail hides every section heading, and a closed <details> hides its own list — so a group the visitor had shut would take its icons with it and leave a gap where half the navigation used to be. initShell forces every group open while the rail is showing and restores what the visitor had on the way out. Neither half is optional: forcing open without saving loses their arrangement, and saving without forcing open loses the icons.

For labels that fly out of the rail on hover and focus, use data-av-layout="rail" — a different axis, described in Layout Modes. data-av-sidebar="collapsed" simply drops the labels; rail keeps them reachable.


Off-canvas, and the two routes into it ​

The rail goes off-canvas below 992px or whenever data-av-layout="overlay" is set, at any width.

js
const offCanvas = () =>
  !mq.matches || document.documentElement.getAttribute('data-av-layout') === 'overlay';

Both routes have to be asked about at click time, and this is a bug that shipped once. The toggle originally checked the media query alone, so in overlay at desktop width its only navigation control silently wrote the collapse preference instead of opening the drawer. The layout also changes under a live page, so the check cannot be made at bind time.

The off-canvas state is the is-mobile-open class on .av-sidebar — not a data-av-sidebar value. Opening it moves focus to the first menu link; Esc and the backdrop both close it and return focus to the toggle. Leaving mobile clears the state and leaves the desktop preference untouched, and switching layouts clears it too — otherwise leaving overlay while the drawer is showing strands a rail above the content with its backdrop still up.

The off-canvas breakpoint, 992px, is a constant.


Events ​

EventDetail
av:sidebar:toggle{ collapsed, source }
av:sidebar:group-toggle{ item, open }

There are no sidebar open/close events. The off-canvas rail is the is-mobile-open class; observe it, or listen for av:theme:change.


Checklist ​

  • [ ] Group headings are <summary>, so aria-expanded and the keyboard model come from the platform
  • [ ] The group list carries aria-labelledby pointing at its summary
  • [ ] display on .av-menu__group-list is set only under [open] — an unconditional one beats the UA rule and renders every group
  • [ ] The active link has aria-current="page", in the HTML the server sent
  • [ ] <nav> has aria-label="Main", and the logo <img> has alt=""
  • [ ] Every page source declares nav, sub or navUnlisted, and the build fails if the value reads nothing
  • [ ] No two sidebar rows share a label
  • [ ] The collapsed rail forces groups open and restores what the visitor had
  • [ ] The toggle asks about both routes to off-canvas — narrow viewport and overlay layout — at click time
  • [ ] Works at 320px; backdrop click and Esc close it and restore focus

Read next: Topbar.

Documentation for @creativeigniter/adminvora