Sidebar 側欄

Skies.ui Sidebar：導航側欄，展開與 icon-only、Context 狀態；Root、Group、Item、Trigger 說明。

Sidebar 是複合元件，提供完整的應用程式左側導航結構。內建展開 / 收合（icon-only） 兩種模式，狀態由 Context 統一管理，並可受控或非受控使用。

基本用法

主要內容區域

import {
  SidebarRoot,
  SidebarHeader,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarItem,
} from "@skies-ui/ui";

export function AppLayout({ children }) {
  return (
    <div className="flex h-screen">
      <SidebarRoot>
        <SidebarHeader>
          <span className="font-semibold text-sm">Sky UI</span>
        </SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>主選單</SidebarGroupLabel>
            <SidebarItem active icon={<HomeIcon />} tooltip="總覽">
              總覽
            </SidebarItem>
            <SidebarItem icon={<UsersIcon />} tooltip="使用者">
              使用者
            </SidebarItem>
          </SidebarGroup>
        </SidebarContent>
      </SidebarRoot>
      <main className="flex-1">{children}</main>
    </div>
  );
}

收合模式

點擊 SidebarTrigger 可切換收合，收合後只顯示圖示。設定 tooltip prop 讓 icon-only 模式仍能提示用途（title 屬性）。

主要內容區域

import { SidebarRoot, SidebarHeader, SidebarTrigger } from "@skies-ui/ui";

<SidebarRoot>
  <SidebarHeader>
    <span className="truncate text-sm font-semibold group-data-[collapsed=true]/sidebar:hidden">Sky UI</span>
    <SidebarTrigger className="ms-auto group-data-[collapsed=true]/sidebar:ms-0" />
  </SidebarHeader>
  {/* ... */}
</SidebarRoot>

受控模式

透過 collapsed + onCollapsedChange 將狀態提升到外部：

"use client";

import { useState } from "react";
import { SidebarRoot } from "@skies-ui/ui";

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

  return (
    <SidebarRoot collapsed={collapsed} onCollapsedChange={setCollapsed}>
      {/* ... */}
    </SidebarRoot>
  );
}

useSidebar hook

子元件可透過 useSidebar() 取得目前狀態：

"use client";

import { useSidebar } from "@skies-ui/ui";

export function MyCustomItem() {
  const { collapsed, setCollapsed } = useSidebar();
  return <span>{collapsed ? "收合中" : "展開中"}</span>;
}

useSidebar 必須在 SidebarRoot 以內使用，否則會拋出錯誤。

將次要操作（登出、設定連結等）放進 Sidebar.Footer：

import { SidebarRoot, SidebarHeader, SidebarContent, SidebarFooter, SidebarItem } from "@skies-ui/ui";

<SidebarRoot>
  <SidebarHeader>...</SidebarHeader>
  <SidebarContent>...</SidebarContent>
  <SidebarFooter>
    <SidebarItem icon={<LogOutIcon />} tooltip="登出">
      登出
    </SidebarItem>
  </SidebarFooter>
</SidebarRoot>

API 摘要

Sidebar.Root

Prop	型別	說明
`defaultCollapsed`	`boolean`	非受控預設值，預設 `false`
`collapsed`	`boolean`	受控模式下的目前狀態
`onCollapsedChange`	`(v: boolean) => void`	狀態改變回呼
`className`	`string`	額外 class（會覆寫寬度等）

Sidebar.Item

Prop	型別	說明
`icon`	`ReactNode`	顯示在文字左側的圖示（建議 16×16）
`active`	`boolean`	啟用高亮樣式
`tooltip`	`string`	收合時作為 `title` / `aria-label`

Sidebar.Trigger

Prop	型別	說明
`collapseIcon`	`ReactNode`	展開狀態下的圖示（預設 ChevronLeft）
`expandIcon`	`ReactNode`	收合狀態下的圖示（預設 ChevronRight）

所有子元件均支援 className 與對應 HTML 元素的原生屬性。

Sidebar 側欄

Sidebar 側欄

基本用法

收合模式

受控模式

useSidebar hook

Footer 用法

API 摘要

Sidebar.Root

Sidebar.Item

Sidebar.Trigger

On this page