Layouts

Start with LayoutHeader, LayoutMain, and LayoutFooter for a single content column. Add the holy-grail layout only when navigation or a table of contents needs its own column.

Blogs and documentation sites usually share a header, main content area, and footer. Blackwork layout components give these areas consistent spacing, with a sticky header by default. Add sidebars when an article needs navigation or a table of contents.

Note

Blackwork’s RootLayout renders html and body, so it cannot be nested inside an existing Next.js App Router layout. Configure ThemeScript and ThemeProvider in the app’s root layout, then add the header, main content, and footer as shown below.

When to use

Blogs, documentation, or other content pages with consistent spacing
A sticky header with brand on the left and site actions on the right
An article with a nav column and a table of contents

See Theme for ThemeProvider and ThemeToggle. See Widgets for LanguageToggle and SocialLinks.

Next.js page layout

Server components

LayoutMain and LayoutFooter can render on the server from blackwork/rsc. LayoutHeader comes from blackwork because it hosts client actions.

src/app/layout.tsx

TSX

import { LayoutHeader, ThemeProvider, ThemeToggle } from 'blackwork'
import { LayoutFooter, LayoutMain, ThemeScript } from 'blackwork/rsc'

const RootLayout = ({ children }: React.PropsWithChildren) => {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body className="flex min-h-dvh flex-col">
        <ThemeProvider>
          <LayoutHeader themeToggle={<ThemeToggle />}>Blackwork</LayoutHeader>
          <LayoutMain>{children}</LayoutMain>
          <LayoutFooter>© Blackwork</LayoutFooter>
        </ThemeProvider>
      </body>
    </html>
  )
}

export default RootLayout

Pass the brand and primary navigation as children to display on the left. Separate props place social links, language controls, and the theme toggle on the right.

Header

Blackwork

LayoutHeader

Prop	Type	Default	Description
`socialLinks`	`SocialLinkProps[]`	—	Icon buttons rendered on the right of the header.
`socialLinksVisible`	`boolean`	`true`	Set to false to hide social links, even when the array has items.
`languageToggle`	`ReactNode`	—	Slot for LanguageToggle or a custom locale control.
`themeToggle`	`ReactNode`	—	Slot for ThemeToggle.
`children`required	`ReactNode`	—	Brand and primary navigation on the left.

Main

The main content has consistent spacing on both sides.

LayoutMain

Prop	Type	Default	Description
`fullscreen`	`boolean`	`false`	Remove horizontal and vertical padding so content can fill the page.
`asChild`	`boolean`	`false`	Apply layout classes to the child without rendering an extra main element.

Footer

Holy grail

A holy-grail layout places the main content between sidebars for navigation and a table of contents. Arrange HolyGrailAside and HolyGrailContent in a flex row. Sidebars are hidden below the lg breakpoint.

Holy grail

Article

HolyGrailAside

Prop	Type	Default	Description
`smaller`	`boolean`	`false`	Narrower column. Typical for a left nav. The default width fits a table of contents.
`asChild`	`boolean`	`false`	Merge column classes onto the child.

RootLayout

RootLayout is for apps that render the entire HTML document directly. It includes html, a head with ThemeScript, and a body with ThemeProvider. For Next.js, use the page layout example above.

RootLayout

Prop	Type	Default	Description
`lang`	`string`	`"en"`	html lang. Use a BCP 47 tag such as en or zh-CN.
`metadata`	`ReactNode`	—	Extra nodes rendered inside head, after ThemeScript.
`className`	`string`	—	Classes for body.

Notes

LayoutHeader is sticky by default. Override its positioning with className for a nested preview or a header that scrolls with the page.
LayoutMain fullscreen removes the shared padding so content can extend to the edges of the page.
HolyGrailAside smaller uses a narrower width for navigation. The default width suits a table of contents.

Glass appearance

Set appearance="glass" on LayoutHeader when the header should sit over the page background. See Liquid glass for the shared theme configuration.