@talltydev/layout

A comprehensive layout component library for admin dashboards and applications, built with React, Next.js, and Tailwind CSS.

Features

• 🎨 Modern Admin Layout - Complete dashboard layout with sidebar, header, and content area
• 📱 Responsive Design - Mobile-first approach with collapsible sidebar
• 🌙 Theme Support - Built-in light/dark theme toggle with next-themes
• 🔍 Search Integration - Debounced search input component
• 🧭 Smart Navigation - Dynamic breadcrumbs and active nav detection
• 👤 User Management - User navigation with profile, settings, and auth
• 🏢 Multi-org Support - Organization switcher for multi-tenant apps
• 🎯 TypeScript First - Full type safety and IntelliSense support
• 📦 Flexible Usage - Use as library or copy components locally

Installation

As a Package

npm install @talltydev/layout
# or
pnpm add @talltydev/layout
# or
yarn add @talltydev/layout

Via tallty-kit CLI

# Add specific components
npx tallty-kit layout add admin-layout

# Add all layout components
npx tallty-kit layout add-all

# List available components
npx tallty-kit layout list

Direct CLI Usage

# Add specific components
npx @talltydev/layout add admin-layout

# Add all layout components
npx @talltydev/layout add-all

# List available components
npx @talltydev/layout list

Quick Start

Basic Admin Layout

import { AdminLayout, createNavConfig } from '@talltydev/layout'
import { Home, Users, Settings } from 'lucide-react'

const navConfig = createNavConfig([
  {
    title: 'Dashboard',
    url: '/dashboard',
    icon: Home
  },
  {
    title: 'Users',
    url: '/users',
    icon: Users
  },
  {
    title: 'Settings',
    url: '/settings',
    icon: Settings
  }
])

export default function DashboardLayout({ children }) {
  return (
    <AdminLayout
      navConfig={navConfig}
      user={{ name: 'John Doe', email: '[email protected]' }}
      onSignOut={() => console.log('Sign out')}
    >
      {children}
    </AdminLayout>
  )
}

Client-side Usage

'use client'

import { AdminLayoutClient } from '@talltydev/layout'

export default function ClientLayout({ children }) {
  return (
    <AdminLayoutClient
      navConfig={navConfig}
      user={user}
      onSignOut={handleSignOut}
    >
      {children}
    </AdminLayoutClient>
  )
}

Usage Modes

Direct Import

1. 安装 @talltydev/layout 以及 README 中列出的 peer 依赖。
2. 在应用入口引入 @talltydev/layout/styles/layout.css 并确保 Tailwind content 中包含 node_modules/@talltydev/layout。
3. 直接从包内导入组件或 hooks，例如 import { AdminLayout } from '@talltydev/layout'。

Copy Components（仿 shadcn/ui）

1. 使用 CLI：npx tallty-kit layout add admin-layout 或 npx tallty-kit layout add-all --include-styles。
2. 确保你的项目配置了 @/* 别名指向 src 或根目录，特别是 @/components、@/hooks、@/lib、@/types。
3. 按提示安装缺失依赖，并根据项目需求微调认证、导航或主题逻辑。

复制模式会同时同步共享的类型与工具函数，保证本地修改能完全脱离包体。

Components

AdminLayout

Complete admin dashboard layout with sidebar, header, and content area.

<AdminLayout
  navConfig={navConfig}
  user={user}
  organizations={orgs}
  activeOrganization={activeOrg}
  onOrganizationSwitch={handleOrgSwitch}
  onSignOut={handleSignOut}
  onSearch={handleSearch}
  userActions={customActions}
  config={{
    sidebar: { collapsible: true },
    header: { showSearch: true }
  }}
>
  {children}
</AdminLayout>

AppSidebar

Collapsible sidebar with navigation and organization switcher.

<SidebarProvider>
  <AppSidebar
    navConfig={navConfig}
    user={user}
    organizations={organizations}
    onOrganizationSwitch={handleOrgSwitch}
  />
  <SidebarInset>
    {/* Main content */}
  </SidebarInset>
</SidebarProvider>

Header

Application header with breadcrumbs, search, and user navigation.

<Header
  navConfig={navConfig}
  user={user}
  onSearch={handleSearch}
  onSignOut={handleSignOut}
  config={{
    showBreadcrumbs: true,
    showSearch: true,
    showThemeToggle: true
  }}
/>

UserNav

User navigation dropdown with customizable actions.

<UserNav
  user={user}
  onSignOut={handleSignOut}
  actions={[
    {
      label: 'Profile',
      icon: User,
      href: '/profile'
    },
    {
      label: 'Custom Action',
      onClick: () => console.log('clicked')
    }
  ]}
/>

ThemeToggle

Theme toggle button for light/dark/system modes.

<ThemeToggle variant="outline" size="icon" />

KBar

Command palette wrapper powered by kbar with built-in theme actions.

import KBar from '@talltydev/layout/kbar'

export default function LayoutWithCommandPalette({ children }) {
  return <KBar>{children}</KBar>
}

复制模式下，可在 components/kbar/index.tsx 中自定义快捷键、导航树与结果渲染逻辑。

Hooks

useSidebar

Access sidebar state and controls.

import { useSidebar } from '@talltydev/layout'

function MyComponent() {
  const { state, open, toggleSidebar } = useSidebar()

  return (
    <button onClick={toggleSidebar}>
      {open ? 'Close' : 'Open'} Sidebar
    </button>
  )
}

useLayout

Layout utilities for breadcrumbs and navigation.

import { useLayout } from '@talltydev/layout'

function MyComponent() {
  const { breadcrumbs, activeNavItem } = useLayout(navConfig)

  return (
    <div>
      <p>Current page: {activeNavItem?.title}</p>
      <p>Breadcrumbs: {breadcrumbs.length}</p>
    </div>
  )
}

Configuration

Navigation Config

import { NavConfig } from '@talltydev/layout'

const navConfig: NavConfig = {
  label: 'Main Navigation',
  items: [
    {
      title: 'Dashboard',
      url: '/dashboard',
      icon: Home
    },
    {
      title: 'Management',
      url: '/management',
      icon: Settings,
      items: [
        {
          title: 'Users',
          url: '/management/users',
          icon: Users
        },
        {
          title: 'Roles',
          url: '/management/roles',
          icon: Shield
        }
      ]
    }
  ]
}

Layout Config

import { LayoutConfig } from '@talltydev/layout'

const config: LayoutConfig = {
  sidebar: {
    collapsible: true,
    defaultOpen: true,
    showToggle: true
  },
  header: {
    showBreadcrumbs: true,
    showSearch: true,
    showThemeToggle: true,
    showUserNav: true
  }
}

Styling

CSS Import

/* Import layout styles */
@import '@talltydev/layout/styles/layout.css';

Tailwind Configuration

Ensure you have the required Tailwind CSS configuration:

// tailwind.config.js
module.exports = {
  content: [
    // ... your content
    "./node_modules/@talltydev/layout/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      // CSS variables for theming
      colors: {
        sidebar: {
          background: 'hsl(var(--sidebar-background))',
          foreground: 'hsl(var(--sidebar-foreground))',
          // ... more variables
        }
      }
    }
  }
}

Dependencies

Peer Dependencies

• @talltydev/ui: UI component library
• react: >=18.0.0
• react-dom: >=18.0.0
• next: >=14.0.0
• next-themes: >=0.2.0
• lucide-react: >=0.400.0

Required Packages

When copying components locally, install these dependencies:

pnpm add @talltydev/ui next-themes lucide-react kbar @radix-ui/react-dropdown-menu @radix-ui/react-collapsible @radix-ui/react-avatar @radix-ui/react-separator @radix-ui/react-tooltip class-variance-authority tailwind-merge clsx

TypeScript

All components are fully typed. Import types as needed:

import type {
  NavConfig,
  User,
  Organization,
  UserMenuAction,
  LayoutConfig
} from '@talltydev/layout'

Examples

With Better Auth

import { AdminLayout } from '@talltydev/layout'
import { authClient } from '@/lib/auth-client'

export default function Layout({ children }) {
  const { data: session } = authClient.useSession()

  return (
    <AdminLayout
      navConfig={navConfig}
      user={session?.user}
      organizations={session?.organizations}
      activeOrganization={session?.activeOrganization}
      onOrganizationSwitch={(orgId) =>
        authClient.organization.setActive({ organizationId: orgId })
      }
      onSignOut={() => authClient.signOut()}
    >
      {children}
    </AdminLayout>
  )
}

Custom Theme Integration

import { ThemeProvider } from 'next-themes'
import { AdminLayout } from '@talltydev/layout'

export default function App({ children }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system">
      <AdminLayout navConfig={navConfig}>
        {children}
      </AdminLayout>
    </ThemeProvider>
  )
}

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Please see our contributing guidelines for more details.

Support

• GitHub Issues: tallty-kit/issues
• Documentation: docs.tallty.com