侧边栏

用途

Sidebar uses a native <aside> next to your page content. A3S UI owns the fixed positioning, overlay behavior, active states, nested lists, and details submenu styling. Your app still owns the navigation data and current route.

Include CSS

导入 Tailwind 和一个完整的 A3S UI 样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

或者只导入基本CSS、侧边栏组件CSS和一个样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/sidebar.css";
@import "@a3s-lab/ui/styles/a3s.css";

使用CDN或批量程序导入？请参见安装页。

Include JavaScript

复制或提供完整的 A3S UI JavaScript 包。

<script src="/assets/js/all.min.js" defer></script>

或者复制或提供A3S UI运行时和侧边栏脚本。

<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/sidebar.min.js" defer></script>

使用CDN或批量程序导入？请参见安装页。

Add your sidebar HTML

<aside id="sidebar" class="sidebar" data-side="left">
  <nav aria-label="Sidebar navigation">
    <section class="scrollbar-sm">
      <div role="group" aria-labelledby="group-label-content-1">
        <h3 id="group-label-content-1">Getting started</h3>
        <ul>
          <li>
            <a href="#">
              <svg class="lucide lucide-square-terminal" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m7 11 2-2-2-2" /><path d="M11 13h4" /><rect width="18" height="18" x="3" y="3" rx="2" ry="2" /></svg>
              <span>Playground</span>
            </a>
          </li>
          <li>
            <a href="#">
              <svg class="lucide lucide-bot" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8" /><rect width="16" height="12" x="4" y="8" rx="2" /><path d="M2 14h2" /><path d="M20 14h2" /><path d="M15 13v2" /><path d="M9 13v2" /></svg>
              <span>Models</span>
            </a>
          </li>
          <li>
            <details id="submenu-content-1-3">
              <summary aria-controls="submenu-content-1-3-content"><svg class="lucide lucide-settings" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915" /><circle cx="12" cy="12" r="3" /></svg>
                <span>Settings</span>
              </summary>
              <ul id="submenu-content-1-3-content">
                <li><a href="#"><span>General</span></a></li>
                <li><a href="#"><span>Team</span></a></li>
                <li><a href="#"><span>Billing</span></a></li>
                <li><a href="#"><span>Limits</span></a></li>
              </ul>
            </details>
          </li>
        </ul>
      </div>
    </section>
  </nav>
</aside>
<main>
  <button type="button" onclick="document.getElementById('sidebar')?.toggle()">Toggle sidebar</button>
  <h1>Content</h1>
</main>

RTL

在侧边栏或父元素上设置 dir="rtl"。逻辑间距、嵌套边框和项目内容遵循文档方向。 data-side 是物理的：left 和 right 指的是视口侧面。

HTML 结构

A3S UI maps shadcn/ui's sidebar composition to regular navigation HTML: an <aside> root, one <nav>, optional header/footer regions, grouped lists, item controls, and native <details> for nested menus.

<aside class="sidebar">

Sidebar root. Supports id, data-side="left|right", data-initial-open="false", data-initial-mobile-open="true", and data-breakpoint. JavaScript manages aria-hidden, inert, and the internal data-sidebar-initialized flag.

<nav aria-label="...">

Navigation landmark inside the sidebar.

<header>

Optional header for branding, workspace controls, user controls, or persistent actions.

<section>

Scrollable content region between the optional header and footer.

<div role="group" aria-labelledby="...">

Named navigation group. Use a heading element as the group label.

<ul> + <li>

Menu and menu item structure. Top-level lists and nested submenu lists receive different spacing and borders.

<a> / <button>: Menu item control. Use links for navigation and buttons for actions. Supports data-variant="default|outline", data-size="default|sm|lg", data-active="true", disabled on buttons, and aria-disabled="true" on custom-disabled controls. For links, prefer <a aria-current="page"> for the current page. Add data-keep-mobile-sidebar-open on a clicked link, button, or ancestor when that control should not close the mobile sidebar.
<details> / <summary>: Native disclosure for collapsible submenus. Put the nested <ul> directly after <summary>. The <summary> supports the same active, variant, and size attributes as menu item controls. Add id and aria-controls when the relationship is not obvious from nearby markup.
<hr role="separator">: Optional separator between groups or menu sections.

<footer>

Optional footer for account controls, status, or persistent actions.

<main>

Sibling content wrapper. The desktop margin applies to the sibling immediately after the sidebar.

在 :root 或侧边栏根上设置 --sidebar-width 和 --sidebar-mobile-width 以覆盖默认的 16rem 桌面宽度和 18rem 移动设备宽度。

桌面端和移动端的打开状态会在 data-breakpoint 两侧独立保存。打开移动抽屉时，焦点会进入第一个导航控件；按 Escape 或点击遮罩会关闭抽屉，并把焦点返回触发控件。普通的移动导航操作会关闭抽屉，但不会把焦点移回之前的页面位置。

JavaScript API

应用程序编程接口	类型	描述
`sidebar.open()`	方法	打开侧边栏。
`sidebar.close()`	方法	关闭侧边栏。
`sidebar.toggle()`	方法	切换侧边栏。

#侧边栏

限定在画布内的产品导航

#用途

Include CSS

Include JavaScript

Add your sidebar HTML

#RTL

#HTML 结构

#JavaScript API

侧边栏

用途

RTL

HTML 结构

JavaScript API