App Layout

Introduction

The AppLayout component is designed for page layouts, providing a complete layout framework that includes sidebar navigation, header, main content area, and footer. It’s particularly suitable for documentation sites, blogs, knowledge bases, and other scenarios that require navigation and content display.

Example

欢迎使用应用布局

这是一个包含侧边栏、头部和页脚的完整布局示例。

应用布局适合用于文档站点、管理后台等场景。

欢迎使用应用布局

这是一个包含侧边栏、头部和页脚的完整布局示例。

应用布局适合用于文档站点、管理后台等场景。

---



import * as astroI18n from "astro:i18n";
import type { ISidebarItem } from "@coffic/cosy-ui";
import { AppLayout, Container, Heading } from "@coffic/cosy-ui";

const sidebarItems: ISidebarItem[] = [
	{
		text: "入门",
		href: "/docs/getting-started",
		items: [
			{ href: "/docs/getting-started", text: "快速开始" },
			{ href: "/docs/installation", text: "安装" },
		],
	},
	{
		text: "组件",
		href: "/docs/components",
		items: [
			{ href: "/docs/components/button", text: "Button 按钮" },
			{ href: "/docs/components/card", text: "Card 卡片" },
		],
	},
];
---

<AppLayout
  bodyOnly={true}
  metaConfig={{
    title: '应用布局示例',
    description: '这是一个应用布局的示例页面',
    keywords: '布局,示例,应用布局',
    author: 'CofficLab',
    robots: 'noindex,nofollow',
    background: 'primary/20',
  }}
  sidebarConfig={{
    sidebarItems: sidebarItems,
  }}
  headerConfig={{
    height: 'md',
    sticky: false,
    astroI18n: astroI18n,
  }}
  footerConfig={{
    siteName: '我的文档站点',
    homeLink: '/',
    slogan: '简单而强大的组件库',
    company: 'CofficLab',
    inspirationalSlogan: '让开发更加愉悦',
  }}
  mainContentConfig={{
    padding: 'md',
    verticalPadding: '4xl',
  }}
  bodyOnly={true}>
  <Container width="lg">
    <Heading level={1} margin="none">欢迎使用应用布局</Heading>
    <p>这是一个包含侧边栏、头部和页脚的完整布局示例。</p>
    <p>应用布局适合用于文档站点、管理后台等场景。</p>
  </Container>
</AppLayout>

---



import * as astroI18n from 'astro:i18n';
import type { ISidebarItem } from '@coffic/cosy-ui';
import { AppLayout, appLayoutProps, Container, Heading } from '@coffic/cosy-ui';

const sidebarItems: ISidebarItem[] = [
    {
        text: '入门',
        href: '/docs/getting-started',
        items: [
            { href: '/docs/getting-started', text: '快速开始' },
            { href: '/docs/installation', text: '安装' },
        ],
    },
    {
        text: '组件',
        href: '/docs/components',
        items: [
            { href: '/docs/components/button', text: 'Button 按钮' },
            { href: '/docs/components/card', text: 'Card 卡片' },
        ],
    },
];

const layout = appLayoutProps()
    .bodyOnly(true)
    .metaConfig({
        title: '应用布局示例',
        description: '这是一个应用布局的示例页面',
        keywords: '布局,示例,应用布局',
        author: 'CofficLab',
        robots: 'noindex,nofollow',
        background: 'primary/20',
    })
    .sidebarConfig({ sidebarItems })
    .headerConfig({ height: 'md', sticky: false, astroI18n })
    .footerConfig({
        siteName: '我的文档站点',
        homeLink: '/',
        slogan: '简单而强大的组件库',
        company: 'CofficLab',
        inspirationalSlogan: '让开发更加愉悦',
    })
    .mainContentConfig({ padding: 'md', verticalPadding: '4xl' })
    .build();
---

<AppLayout {...layout}>
    <Container width="lg">
        <Heading level={1} margin="none">欢迎使用应用布局</Heading>
        <p>这是一个包含侧边栏、头部和页脚的完整布局示例。</p>
        <p>应用布局适合用于文档站点、管理后台等场景。</p>
    </Container>
</AppLayout>

Props

enableClientRouter

Controls whether to enable Astro’s ClientRouter for SPA-like page transitions.

Default: true
Set to false to use full page navigation instead of client-side routing.

footerConfig

Footer configuration, including site information, social media links, etc. For detailed configuration options, please refer to the Footer component documentation.

headerConfig

Header configuration, passed to the AppHeader component. For detailed configuration options, please refer to the Header component documentation.

loadingDelay

The delay time (ms) for displaying the loading interface to avoid flicker (default 100).

mainContentConfig

Main content area configuration:

padding: content padding
verticalPadding: vertical padding
fullWidth: full-width content

metaConfig

Metadata configuration:

title: page title
description: page description
keywords: page keywords
author: author
robots: robots policy
favicon: site icon
basePath: base path (for subdirectory deployments)
siteName: site name
lang: page language (default zh-CN)
viewport: include viewport meta (default true)
customStyles: custom styles injected into head
head: custom head HTML
background: preset background color

showFooter

Whether to show the footer (true/false).

showHeader

Whether to show the header (true/false).

showSidebar

Whether to show the sidebar (true/false).

sidebarConfig

Sidebar configuration, including navigation items, etc.

---



import type { ISidebarItem } from "@coffic/cosy-ui";
import { Heading, Sidebar } from "@coffic/cosy-ui";

const sidebarItems: ISidebarItem[] = [
	{
		text: "侧边栏配置",
		href: "/sidebar",
		items: [
			{ href: "/sidebar/basic", text: "基础侧边栏" },
			{ href: "/sidebar/nested", text: "嵌套菜单" },
			{ href: "/sidebar/custom", text: "自定义样式" },
		],
	},
	{
		text: "组件库",
		href: "/components",
		items: [
			{ href: "/components/buttons", text: "按钮组件" },
			{ href: "/components/forms", text: "表单组件" },
			{ href: "/components/layout", text: "布局组件" },
			{ href: "/components/navigation", text: "导航组件" },
		],
	},
	{
		text: "文档",
		href: "/docs",
		items: [
			{ href: "/docs/getting-started", text: "快速开始" },
			{ href: "/docs/installation", text: "安装指南" },
			{ href: "/docs/tutorial", text: "教程" },
			{ href: "/docs/api", text: "API参考" },
		],
	},
];
---

<Sidebar sidebarItems={sidebarItems} />

theme

Sets the theme for the layout. Supported themes include:

light
dark
corporate
lemonade
nord
business
luxury

The default value is default.

Slots

background

Custom background layer (lowest layer, z-index: 0). Used to create full-screen background effects such as gradients, images, decorative elements, etc. The background layer is fixed to the viewport and does not scroll with content.

💡 View Live Demo - Experience the complete custom background feature

Use Cases:

Gradient Backgrounds: Create eye-catching gradient effects
Background Images: Add brand-related background images
Decorative Elements: Add blur circles, geometric patterns, etc.
Animated Backgrounds: Canvas animations, particle effects, etc.
Video Backgrounds: Full-screen video backgrounds

Example:

<AppLayout
  metaConfig={{ title: "My App" }}
  showHeader={false}
  showSidebar={false}
>
  <!-- Custom background layer -->
  <div slot="background" class="cosy:fixed cosy:inset-0 cosy:bg-gradient-to-br cosy:from-blue-600 cosy:to-purple-800">
    <!-- Decorative blur elements -->
    <div class="cosy:absolute cosy:top-10 cosy:left-10 cosy:w-96 cosy:h-96 cosy:bg-white/10 cosy:rounded-full cosy:blur-3xl"></div>
    <div class="cosy:absolute cosy:bottom-10 cosy:right-10 cosy:w-96 cosy:h-96 cosy:bg-white/10 cosy:rounded-full cosy:blur-3xl"></div>
  </div>

  <!-- Main content (requires proper background opacity) -->
  <div class="cosy:bg-white/80 cosy:backdrop-blur cosy:p-8 cosy:rounded-lg">
    <h1>Page Content</h1>
    <p>Background layer renders below all content</p>
  </div>
</AppLayout>

Technical Features:

Fixed positioning (position: fixed), does not scroll with content
Lowest z-index (z-index: 0), below all content
Default pointer-events: none, does not affect user interactions
Fully customizable, supports any HTML/CSS/Canvas

Notes:

Background layer covers the entire viewport (inset: 0)
Main content needs appropriate background color and opacity for readability
CSS gradients are preferred over images (better performance)
Avoid excessive shadows and blur effects (affects performance)
If interactive elements are needed, set pointer-events: auto in the background slot content

default

Main content area for placing the main content of the page.

默认插槽示例

这是通过默认插槽放置的主要内容。

内容区域

你可以在这里放置任何内容，包括文本、图片、组件等。

功能特性

• 响应式布局
• 侧边栏导航
• 头部导航

使用场景

• 文档站点
• 博客系统
• 知识库

---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "默认插槽示例",
	description: "展示如何使用默认插槽放置主要内容",
	keywords: "AppLayout, 默认插槽, default slot",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div class="cosy:p-6">
    <h1 class="cosy:text-3xl cosy:font-bold cosy:mb-6">默认插槽示例</h1>
    <div class="cosy:space-y-4">
      <p class="cosy:text-lg cosy:text-gray-700">
        这是通过默认插槽放置的主要内容。
      </p>
      <div class="cosy:bg-gray-100 cosy:p-4 cosy:rounded-lg">
        <h2 class="cosy:text-xl cosy:font-semibold cosy:mb-2">内容区域</h2>
        <p class="cosy:text-gray-600">
          你可以在这里放置任何内容，包括文本、图片、组件等。
        </p>
      </div>
      <div class="cosy:grid cosy:grid-cols-2 cosy:gap-4 cosy:mt-6">
        <div class="cosy:bg-blue-50 cosy:p-4 cosy:rounded-lg">
          <h3 class="cosy:font-semibold cosy:mb-2">功能特性</h3>
          <ul class="cosy:text-sm cosy:space-y-1">
            <li>• 响应式布局</li>
            <li>• 侧边栏导航</li>
            <li>• 头部导航</li>
          </ul>
        </div>
        <div class="cosy:bg-green-50 cosy:p-4 cosy:rounded-lg">
          <h3 class="cosy:font-semibold cosy:mb-2">使用场景</h3>
          <ul class="cosy:text-sm cosy:space-y-1">
            <li>• 文档站点</li>
            <li>• 博客系统</li>
            <li>• 知识库</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</AppLayout>

Custom global header (highest priority). When this slot is provided, it replaces the built-in AppHeader and spans the full page width (not constrained by the sidebar).

💡 View Live Demo - Experience the complete custom header feature

Use Cases:

Brand Customization: Fully custom header design without AppHeader limitations
Special Interactions: Implement effects like transparent gradients, scroll-based changes, etc.
Complex Layouts: Special layout structures in the header
Third-party Integration: Integrate third-party header components

Example:

<AppLayout
  metaConfig={{ title: "My App" }}
  sidebarConfig={{ sidebarItems: [] }}
>
  <!-- Custom header that spans full page width -->
  <header slot="header" class="cosy:bg-primary cosy:text-white cosy:p-4">
    <div class="cosy:container cosy:mx-auto cosy:flex cosy:items-center cosy:justify-between">
      <h1 class="cosy:text-xl cosy:font-bold">My Brand</h1>
      <nav class="cosy:flex cosy:gap-4">
        <a href="/" class="cosy:hover:underline">Home</a>
        <a href="/docs" class="cosy:hover:underline">Docs</a>
      </nav>
    </div>
  </header>

  <!-- Main content -->
  <h1>Page Content</h1>
</AppLayout>

Notes:

Custom header has the highest priority and will override showHeader and headerConfig settings
Recommended to use container classes (e.g., cosy:container cosy:mx-auto) to constrain content width
Handle responsive layout and styling yourself
Recommended z-index range: 40-50

Custom global footer (highest priority). When this slot is provided, it replaces the built-in Footer and spans the full page width (not constrained by the sidebar).

💡 View Live Demo - Experience the complete custom footer feature

Use Cases:

Brand Customization: Fully custom footer design without Footer limitations
Special Interactions: Implement complex layout structures
Multi-column Layouts: Create multi-column content in the footer
Third-party Integration: Integrate third-party footer components

Example:

<AppLayout
  metaConfig={{ title: "My App" }}
  sidebarConfig={{ sidebarItems: [] }}
>
  <!-- Main content -->
  <h1>Page Content</h1>

  <!-- Custom footer that spans full page width -->
  <footer slot="footer" class="cosy:bg-base-200 cosy:p-8">
    <div class="cosy:container cosy:mx-auto">
      <div class="cosy:grid cosy:grid-cols-1 cosy:md:grid-cols-3 cosy:gap-8">
        <div>
          <h3 class="cosy:font-bold cosy:text-lg cosy:mb-4">About Us</h3>
          <p class="cosy:text-sm">We are committed to providing the best products and services</p>
        </div>
        <div>
          <h3 class="cosy:font-bold cosy:text-lg cosy:mb-4">Quick Links</h3>
          <ul class="cosy:space-y-2">
            <li><a href="/docs" class="cosy:link cosy:link-hover">Documentation</a></li>
            <li><a href="/blog" class="cosy:link cosy:link-hover">Blog</a></li>
          </ul>
        </div>
        <div>
          <h3 class="cosy:font-bold cosy:text-lg cosy:mb-4">Contact</h3>
          <p class="cosy:text-sm">email@example.com</p>
        </div>
      </div>
      <div class="cosy:mt-8 cosy:pt-8 cosy:border-t cosy:text-center cosy:text-sm">
        <p>&copy; 2025 My Company. All rights reserved.</p>
      </div>
    </div>
  </footer>
</AppLayout>

Notes:

Custom footer has the highest priority and will override showFooter and footerConfig settings
Recommended to use container classes (e.g., cosy:container cosy:mx-auto) to constrain content width
Handle responsive layout and styling yourself
Follows the same design pattern as the header slot

Content for the start position of the navigation bar, passed to the AppHeader component.

导航栏开始位置插槽示例

导航栏开始位置插槽

这个示例展示了如何使用 navbar-start 插槽在导航栏开始位置添加自定义内容。

可以看到导航栏左侧显示了自定义的 Logo 和标题。

---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "导航栏开始位置插槽示例",
	description: "展示如何使用 navbar-start 插槽自定义导航栏开始位置的内容",
	keywords: "AppLayout, navbar-start, 插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="navbar-start" class="cosy:flex cosy:items-center cosy:gap-2">
    <div
      class="cosy:w-8 cosy:h-8 cosy:bg-primary cosy:rounded-lg cosy:flex cosy:items-center cosy:justify-center">
      <span class="cosy:text-white cosy:font-bold">C</span>
    </div>
    <h1 class="cosy:text-xl cosy:font-bold cosy:text-primary">Cosy UI</h1>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">导航栏开始位置插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 navbar-start 插槽在导航栏开始位置添加自定义内容。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      可以看到导航栏左侧显示了自定义的 Logo 和标题。
    </p>
  </div>
</AppLayout>

Content for the center position of the navigation bar, passed to the AppHeader component.

导航栏中间位置插槽示例

导航栏中间位置插槽

这个示例展示了如何使用 navbar-center 插槽在导航栏中间位置添加自定义内容。

可以看到导航栏中间显示了自定义的导航链接。

---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "导航栏中间位置插槽示例",
	description: "展示如何使用 navbar-center 插槽自定义导航栏中间位置的内容",
	keywords: "AppLayout, navbar-center, 插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="navbar-center" class="cosy:flex cosy:gap-6">
    <a href="/docs" class="cosy:link cosy:link-hover cosy:font-medium">文档</a>
    <a href="/components" class="cosy:link cosy:link-hover cosy:font-medium"
      >组件</a
    >
    <a href="/examples" class="cosy:link cosy:link-hover cosy:font-medium"
      >示例</a
    >
    <a href="/blog" class="cosy:link cosy:link-hover cosy:font-medium">博客</a>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">导航栏中间位置插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 navbar-center 插槽在导航栏中间位置添加自定义内容。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      可以看到导航栏中间显示了自定义的导航链接。
    </p>
  </div>
</AppLayout>

Content for the end position of the navigation bar, passed to the AppHeader component.

导航栏结束位置插槽示例

导航栏结束位置插槽

这个示例展示了如何使用 navbar-end 插槽在导航栏结束位置添加自定义内容。

可以看到导航栏右侧显示了自定义的按钮组。

---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "导航栏结束位置插槽示例",
	description: "展示如何使用 navbar-end 插槽自定义导航栏结束位置的内容",
	keywords: "AppLayout, navbar-end, 插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="navbar-end" class="cosy:flex cosy:items-center cosy:gap-3">
    <button class="cosy:btn cosy:btn-ghost cosy:btn-sm">登录</button>
    <button class="cosy:btn cosy:btn-primary cosy:btn-sm">注册</button>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">导航栏结束位置插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 navbar-end 插槽在导航栏结束位置添加自定义内容。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      可以看到导航栏右侧显示了自定义的按钮组。
    </p>
  </div>
</AppLayout>

Search modal content, when this slot is provided, a search button will be displayed, passed to the AppHeader component.

搜索模态框插槽示例

搜索模态框插槽

这个示例展示了如何使用 modal-search 插槽添加搜索功能。

当提供此插槽时，导航栏会自动显示搜索按钮，点击后打开搜索模态框。

提示：点击导航栏右侧的搜索图标可以打开搜索模态框。

---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "搜索模态框插槽示例",
	description: "展示如何使用 modal-search 插槽添加搜索功能",
	keywords: "AppLayout, modal-search, 搜索插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="modal-search" class="cosy:space-y-4">
    <div class="cosy:form-control">
      <input
        type="text"
        placeholder="搜索文档..."
        class="cosy:input cosy:input-bordered cosy:w-full"
      />
    </div>
    <div class="cosy:flex cosy:gap-2">
      <button class="cosy:btn cosy:btn-primary cosy:btn-sm">搜索</button>
      <button class="cosy:btn cosy:btn-ghost cosy:btn-sm">清除</button>
    </div>
    <div class="cosy:divider"></div>
    <div class="cosy:space-y-2">
      <h3 class="cosy:font-semibold cosy:text-sm">热门搜索</h3>
      <div class="cosy:flex cosy:flex-wrap cosy:gap-2">
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Button</span>
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Card</span>
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Layout</span>
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Form</span>
      </div>
    </div>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">搜索模态框插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 modal-search 插槽添加搜索功能。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      当提供此插槽时，导航栏会自动显示搜索按钮，点击后打开搜索模态框。
    </p>
    <div class="cosy:mt-4 cosy:p-4 cosy:bg-blue-50 cosy:rounded-lg">
      <p class="cosy:text-sm cosy:text-blue-700">
        <strong>提示：</strong>点击导航栏右侧的搜索图标可以打开搜索模态框。
      </p>
    </div>
  </div>
</AppLayout>