Layouts

These pieces are the Blackwork page chrome. Compose a sticky header, a content gutter, and a short footer. Add holy-grail columns when a page needs a sidebar or a table of contents.

Note

Do not use RootLayout inside a Next.js App Router tree. That component renders its own html and body. In Next.js, put ThemeScript in head, wrap the tree with ThemeProvider, then compose the chrome below.

When to use

A blog, docs site, or other content page that should share one gutter
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 shell

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 brand and nav as children. Social links, a language toggle, and the theme toggle sit on the right.

Header

Blackwork

LayoutHeader

Prop	Type	Default	Description
`socialLinks`	`SocialLinkProps[]`	—	Icon buttons rendered on the right of the header.
`socialLinksVisible`	`boolean`	`true`	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

Page content uses the shared content gutter.

LayoutMain

Prop	Type	Default	Description
`fullscreen`	`boolean`	`false`	Drop the content gutter and vertical padding. Use for full-bleed pages.
`asChild`	`boolean`	`false`	Merge layout classes onto the child instead of a main.

Footer

Holy grail

There is no wrapper component. Place HolyGrailAside and HolyGrailContent in a flex row. Asides stay 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 a full document shell: html, head with ThemeScript, and body with ThemeProvider.

Note

Use it only when you own the entire document, not inside an existing App Router layout.

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. Override with className if you need it in a nested preview or a non-sticky bar.
LayoutMain fullscreen drops the shared gutter. Use it for a landing page that paints edge to edge.
HolyGrailAside smaller is the narrow nav column. The default width fits a table of contents.