# Page Rails

> The column a page is laid out in: a vertical rail down each side, optionally with a patterned gutter.

- Category: Structure (Rails, rules and section grids that lay out a whole page.)
- Registry item: `page-rails`
- Live preview with controls: https://fancyborders.vercel.app/docs/components/page-rails

## Installation

```bash
npx shadcn@latest add https://fancyborders.vercel.app/r/page-rails.json
```

With the registry namespace: `npx shadcn@latest add @fancyborders/page-rails`.

The CLI also adds what `page-rails` is built on: `frame`.

Files it adds: `components/ui/frame.tsx`, `components/page-rails.tsx`, and its CSS goes into the global stylesheet after the Tailwind import.

## Usage

The code for the preview at its default settings:

```tsx
import { PageRails } from "@/components/page-rails";

<PageRails
  gutter={16}
  fill="hatch"
  bleed={24}
  className="mx-auto max-w-5xl"
>
  Your sections
</PageRails>
```

## Examples

### A whole page

Rails, section rules and a section grid together. The rules cross the rails, and the grid's lines stop at them.

```tsx
import { PageRails } from "@/components/page-rails";
import { SectionRule } from "@/components/section-rule";
import { SectionGrid } from "@/components/ui/section-grid";

const FEATURES = [
  ["Rails", "Two lines the page hangs from."],
  ["Rules", "Lines that cross the rails."],
  ["Grids", "Cells that share their lines."],
  ["Marks", "One on every crossing."],
];

export default function PageLayout() {
  return (
    <div className="w-full overflow-x-clip">
      <PageRails bleed={32} className="mx-auto w-full max-w-md">
        <header className="p-6">
          <p className="text-lg font-semibold tracking-tight">Acme</p>
          <p className="mt-1 text-sm text-foreground/60">
            A page laid out on its own lines.
          </p>
        </header>
        <SectionRule bleed={32} />
        <SectionGrid mark="plus" className="section-cols-2">
          {FEATURES.map(([name, text]) => (
            <div key={name} className="p-4">
              <p className="font-mono text-xs">{name}</p>
              <p className="mt-1 text-xs text-foreground/60">{text}</p>
            </div>
          ))}
        </SectionGrid>
        <SectionRule bleed={32} />
        <footer className="p-6 font-mono text-xs text-foreground/50">
          Free and open source
        </footer>
      </PageRails>
    </div>
  );
}
```

## Good to know

- Everything inside sits flush with the rails, so pad your sections rather than the column. That is what lets a rule, a divider or a grid meet the rails exactly.
- With bleed set to true the rails run a full viewport height past each end. The page then needs overflow-y: clip on an ancestor.

## API reference

### PageRails

```tsx
import { PageRails } from "@/components/page-rails";
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bleed` | `boolean \| number \| string` | `false` | How far the rails run past the top and bottom of the column. true runs them a full viewport height each way. |
| `gutter` | `number \| string` | – | Width of a gutter down each side. A second pair of rails is drawn this far inside the first, and the content sits between the inner pair. |
| `fill` | `"hatch" \| "cross" \| "dots" \| "grid"` | – | Pattern drawn in the gutters. |
| `dash` | `number \| string` | `4` | Dash length. Setting dash or gap makes the rails dashed. |
| `gap` | `number \| string` | `4` | Space between dashes. |

Also accepts every Frame prop and every div attribute.
