Skip to content
n3wth docs

Page Layouts and Site Components

@n3wth/ui/site exports layout components, a theme provider, and scroll helpers. Your application supplies content, route links, and active state. Complete the Quickstart first. The examples here assume an ancestor N3wthProvider and an imported site.css.

Page frame

Section titled “Page frame”

This example assembles a full page with navigation, header, sections, and footer:

import {
  PageHeader,
  SiteContainer,
  SiteFooter,
  SiteHeading,
  SiteNavigation,
  SiteSection,
  SiteText,
} from '@n3wth/ui/site'


export function ReferencePage() {
  return (
    <>
      <SiteNavigation
        brand={<a href="/ui/quickstart">UI</a>}
        links={<a href="/ui/layouts" aria-current="page">Layouts</a>}
        actions={<a href="https://github.com/n3wth/n3wth">Source</a>}
      />
      <SiteContainer as="main" className="n3wth-site-main">
        <PageHeader
          title="Reference"
          description="Shared page structure for a React application."
          actions={<a href="#layout">Read the layout notes</a>}
        />
        <SiteSection id="layout">
          <SiteHeading>Layout</SiteHeading>
          <SiteText>Use one container to align the page content.</SiteText>
        </SiteSection>
      </SiteContainer>
      <SiteFooter
        brand={<a href="/ui/quickstart">UI documentation</a>}
        links={<a href="https://github.com/n3wth/n3wth">Source</a>}
      />
    </>
  )
}

n3wth-site-main adds the top spacing used with site navigation. SiteSection adds vertical spacing. It does not add the container’s horizontal constraints. Put sections inside a container, or put a container inside a full-width section when the section needs its own background.

Available site components

Section titled “Available site components”

SiteContainer

Constrain and align content. Accepts as: div (default), main, section, or article.

SiteSection

Separate page regions vertically with native section props.

SiteSectionLinks

In-flow links to sections or documents. Sticky navigation owns active state separately.

SiteHeading

Choose visual role (page, section, item) and semantic heading level (1 through 6).

SiteText

Body text with shared typography. Variants: body (default), supporting, lede.

SiteDocSection

Group long-form content with an optional title and level (2 or 3).

SiteDocList

Render a document list from a required items array of React nodes.

PageHeader

Introduce a page or major region with title, optional description, actions, aside, and alignment.

SiteNavigation

Responsive navigation with brand, links, actions, and a mobile disclosure.

SiteSignup

One-line email capture for footers. The app owns delivery through onSubmit(email).

SiteFooter

Shared footer with brand, links, optional signup, and metadata slots.

N3wthProvider

Theme provider that supplies the Newth theme context. Accepts mode: dark, light, or system.

ReadingOutline

Scroll-spy outline for long-form pages. Accepts items, label, and collapsible.

Hooks and helpers

Section titled “Hooks and helpers”
Export Purpose
useRouteScrollReset Reset scroll to top after qualifying anchor clicks to a new pathname
n3wthTheme Theme object for programmatic access to Newth tokens
Section titled “Navigation behavior”

SiteNavigation requires brand and links, both React nodes. Optional props are actions, navigationLabel (default Primary), navigationId, and menuLabel (default Open menu). It accepts HTML attributes but does not take a children slot.

Pass anchors or your router’s link components. The current UI docs app passes React Router NavLink elements. The composition does not resolve routes or calculate which link is active.

The mobile disclosure focuses the first link when opened. It closes on link selection, outside pointer interaction, Escape, or a transition to the desktop media query. Escape restores focus to the menu button. Keep navigation links as actual anchors so the click and focus behavior can find them.

Section titled “Customize the footer”

SiteFooter defaults to an Oliver Newth brand link and Library, Skills, r3, Docs, Contact, and GitHub links. For another product, pass your own brand and links as in the frame example. The optional signup slot renders above the identity row. Pair it with SiteSignup, which takes an onSubmit(email) handler so the app decides where addresses go.

Prop Behavior
brand React node; null omits the brand
links Replaces the complete default link group
sourceHref Changes the default GitHub link; defaults to the monorepo URL
legalLinks Appended only when using the default link group
children Additional footer metadata below the link row

If you supply links, legalLinks and sourceHref no longer construct that group. Include those links yourself when you replace it.

Section titled “Related”
Reading OutlineAdd a scroll-spy outline to long-form pages.
Scroll ResetReset scroll to top on route change.