SITE CONTEXT HOOKS

Apply only when the component genuinely needs live site context:

• The component reflects where the visitor is in the site — breadcrumbs, “you are here” indicators. Not navigation menus: the site owner authors those, and their items need not necessarily be site pages, so they take a MenuItems prop
• The component needs the page’s own URL — share buttons, copy-link, canonical links, QR codes
• Language direction drives JavaScript — keyboard navigation, transform or animation math, conditional rendering
• Behavior must differ inside the editor — suppressing autoplay, network calls, or timers while the site owner is designing

When behavior differs only in editor rendering, keep the main component’s live contract unchanged and add the editor-only gate to the generated component.preview.tsx while preserving its wrappers.

The test is whether the site owner authors the data. A hook reports state the owner cannot write — which page is being rendered, what the site’s URL is. Data the owner chooses belongs in props, even when it happens to point at site pages. Purely visual RTL needs no hook either; use logical CSS properties.

Contents

• Rules
• Read Values During Render
• Walking the Page Tree
• Building a Link to a Page
• Direction-Dependent Logic
• Avoid Direction Logic for Visual CSS
• Checklist

Rules

The Available Hooks

All import from the same place:

Each returns a plain value, so there is nothing to unwrap or guard. They are React hooks — call them at the top of the component or hook body, never at module scope, inside a callback, or conditionally.

Read Values During Render

Hook values are read on the server too, so their results are part of the server markup. Use the value directly.

✅ Correct:

❌ Wrong — empty on the server, then a hydration mismatch:

Patterns

Walking the Page Tree

usePages() returns a map keyed by page id. Three things to get right:

• The map key is the page id — the values carry no id field.
• parentPageId is absent for top-level pages — treat those as children of useMainPageId() when walking upward.
• popup: true pages are lightboxes, not navigable pages. Filter them out of breadcrumbs, menus, and page pickers.

The visited set is not optional — a misconfigured site can produce a parent cycle, and an unguarded walk hangs the render.

Building a Link to a Page

Join a page’s path onto useSiteUrl(). The base URL may or may not carry a trailing slash, so normalize before joining:

Direction-Dependent Logic

Resolve the component’s own direction prop first, then fall back to the site:

Use the resolved value for logic only — arrow-key handling, transform sign, scroll direction:

Avoid Direction Logic for Visual CSS

Do not call useLanguageDirection() to choose between physical CSS properties.

❌ Wrong:

✅ Correct:

Checklist

• Not done: A hook supplies live context that cannot be represented by authored props.
• Not done: Hooks are called unconditionally inside a component or custom hook.
• Not done: Hook values are read during render rather than copied through an effect.
• Not done: Page-tree traversal filters popups and guards parent cycles.
• Not done: Direction hooks affect JavaScript behavior, not visual CSS choices.