Blocks / Outline

Outline

The table of contents of a document, nested by level, that follows your reading.

import { Outline, structureHeadingsFrom, structureActiveHeading } from "@forgeron/ui";
/01 → Default

Goals

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Scope

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Out of scope

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Plan

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

First quarter

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Hiring

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Second quarter

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Risks

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

// A list of headings, with the one you are reading marked. Scroll the pane, or click a heading.
import { Outline } from "@forgeron/ui";

const headings = [
  { id: "ol-goals", text: "Goals", level: 1 },
  { id: "ol-scope", text: "Scope", level: 2 },
  { id: "ol-out", text: "Out of scope", level: 2 },
  { id: "ol-plan", text: "Plan", level: 1 },
  { id: "ol-q1", text: "First quarter", level: 2 },
  { id: "ol-q1a", text: "Hiring", level: 3 },
  { id: "ol-q2", text: "Second quarter", level: 2 },
  { id: "ol-risks", text: "Risks", level: 1 },
];

const filler = (n: number) => (
  <p style={{ margin: "0 0 12px", color: "var(--ink-muted)" }}>
    {"Lorem ipsum dolor sit amet, consectetur adipiscing elit. ".repeat(n)}
  </p>
);

export default function Default() {
  return (
    <div
      style={{
        display: "grid",
        gridTemplateColumns: "minmax(0,1fr) 200px",
        gap: 24,
        width: "100%",
      }}
    >
      <div
        id="ol-pane"
        tabIndex={0}
        aria-label="Document"
        style={{
          height: 280,
          overflow: "auto",
          paddingRight: 12,
          font: "400 14px/20px var(--font-sans)",
        }}
      >
        {headings.map((h) => {
          const Tag = `h${h.level}` as "h1";
          return (
            <section key={h.id}>
              <Tag
                id={h.id}
                style={{
                  margin: "0 0 8px",
                  font: "500 16px/22px var(--font-sans)",
                  color: "var(--ink)",
                }}
              >
                {h.text}
              </Tag>
              {filler(3)}
            </section>
          );
        })}
      </div>
      <Outline headings={headings} scrollRoot="#ol-pane" offset={24} />
    </div>
  );
}
/02 → From the page

Overview

The first section.

Details

Its details.

Summary

The end.

// No list: the outline reads the headings of the element and follows it as you edit.
import { Outline } from "@forgeron/ui";
import { useState } from "react";

export default function FromThePage() {
  const [extra, setExtra] = useState(false);
  return (
    <div
      style={{
        display: "grid",
        gridTemplateColumns: "minmax(0,1fr) 200px",
        gap: 24,
        width: "100%",
      }}
    >
      <article
        id="ol-article"
        style={{
          height: 260,
          overflow: "auto",
          paddingRight: 12,
          font: "400 14px/20px var(--font-sans)",
          color: "var(--ink-muted)",
        }}
      >
        <h2 style={{ color: "var(--ink)", font: "500 16px/22px var(--font-sans)" }}>Overview</h2>
        <p style={{ height: 120 }}>The first section.</p>
        <h3 style={{ color: "var(--ink)", font: "500 14px/20px var(--font-sans)" }}>Details</h3>
        <p style={{ height: 120 }}>Its details.</p>
        {extra ? (
          <>
            <h2 style={{ color: "var(--ink)", font: "500 16px/22px var(--font-sans)" }}>
              Appendix
            </h2>
            <p style={{ height: 200 }}>Added a moment ago.</p>
          </>
        ) : null}
        <h2 style={{ color: "var(--ink)", font: "500 16px/22px var(--font-sans)" }}>Summary</h2>
        <p style={{ height: 160 }}>The end.</p>
      </article>
      <div style={{ display: "grid", gap: 12, alignContent: "start" }}>
        <Outline from="#ol-article" scrollRoot="#ol-article" offset={24} foldable />
        <button type="button" className="fg-btn fg-btn-sm" onClick={() => setExtra((v) => !v)}>
          {extra ? "Remove a section" : "Add a section"}
        </button>
      </div>
    </div>
  );
}
API → Props
PropTypeDefaultDescription
headings{ id, text, level }[]—In document order. The ids are the ones of the headings on the page.
fromstring | RefObject | HTMLElement—Instead of headings: the element whose h1 to h6 are read, again whenever it changes. A heading with no id is given one.
scrollRootstring | RefObject | HTMLElementthe pageThe element that scrolls.
offsetnumber96How far under the top a heading counts as reached.
minLevel / maxLevelnumber1 / 6Only these levels.
active / defaultActive / onActiveChangestring | null—The heading being read: set by scrolling, or by you.
onSelect(id, event) => void—A click. It scrolls and focuses the heading unless you call preventDefault.
collapsible / collapsed / defaultCollapsed / onCollapsedChangeboolean; string[]trueA branch folds.
foldable / open / defaultOpen / onOpenChangeboolean—The whole outline folds behind its title.
titlestring"On this page"Heading of the panel.
classNamestring—Extra classes.