# Navigation

Create menu links, bind a menu to the website, and keep destinations working as content changes.

GroCMS 0.1.0 · Website design · Administrators and designers · Reviewed 15 September 2026

## The menu and the navigation component

Navigation contains menu resources: ordered lists of link labels and destinations. The Site navigation component displays one of those menus together with the site's brand name or logo. Editing the menu changes its data; placing or binding Site navigation determines where that data appears. Creating a new menu does not automatically replace every navigation area.

The public header uses a default Site navigation component unless a designated shared header supplies another layout. A Site navigation component may bind a particular published menu. With no menu selected, it uses the site's default resolved menu; if no menu exists, the public renderer can fall back to links for public content archives.

Sources: Resource editor and design resource fields (repository: `apps/cms/src/components/admin/resource-editor.tsx`); Configured website components (repository: `apps/cms/src/cms/components/config.tsx`); Public page selection and resource resolution (repository: `apps/cms/src/cms/services/public.ts`).

## Add and arrange links

1. Open Navigation and select the existing menu you intend to change. Give a newly created menu a descriptive resource title so it is easy to distinguish from its individual link labels.
2. Select Add navigation link. Enter a short, meaningful Label such as Journal, About, or Gatherings.
3. For a CMS entry, use Choose linked content, search for the destination, and confirm the selection. For an archive or external website, leave Linked content empty and enter its address in Link.
4. Use each row's Move link down control to change order, or Remove to delete the row. To move an item upward, move the preceding row down until the desired order is reached.
5. Wait for saving, inspect the labels and destinations, then publish the menu.

Selecting Linked content hides the free-form Link input because the resource binding becomes the destination. Remove the selected entry to return to a typed address. The current interface is a flat list; it does not offer nested submenus, dropdown groups, per-link icons, or an open-in-new-tab setting. A menu may contain at most 100 items, though a short primary menu is easier to use.

Sources: Resource editor and design resource fields (repository: `apps/cms/src/components/admin/resource-editor.tsx`); Searchable reference selection (repository: `apps/cms/src/components/admin/reference-picker.tsx`); Content and composition validation (repository: `apps/cms/src/cms/validation.ts`).

## Choose a resource link or a typed address

| Destination | Recommended entry |
| --- | --- |
| A specific Page or post | Choose Linked content so the menu resolves its current public route. |
| The homepage | Enter / in Link when the destination is the front page itself. |
| The post archive | Enter the configured archive path, for example /journal. The exact path depends on your content configuration. |
| Search | Enter /search. |
| An external website | Enter its complete safe URL, such as https://example.com. |

A resource link follows the target's current non-redirect public route. A typed path remains the text you entered and may need maintenance after a route change. If a resource has no public route, its bound link is omitted from the public menu. Selecting a draft or later withdrawing its destination does not make that destination publicly available through navigation.

Use labels that explain the destination without relying on nearby decoration. The validator rejects unsafe links, but it does not prove that a typed external page exists or that an archive path is spelled correctly. Open each important destination during your review.

Sources: Public page selection and resource resolution (repository: `apps/cms/src/cms/services/public.ts`); Resource editor and design resource fields (repository: `apps/cms/src/components/admin/resource-editor.tsx`); Content and composition validation (repository: `apps/cms/src/cms/validation.ts`); Revision and publication service (repository: `apps/cms/src/cms/services/content.ts`).

## Use a particular menu in a layout

1. Publish the menu so it is available to the navigation picker.
2. Open the relevant shared header or composition in Visual editor and select Site navigation.
3. In its Navigation field, choose the published menu. Save and publish the receiving resource after checking Preview.
4. For subsequent label or ordering changes, publish the menu itself. The bound component will resolve its current published version.

A bound menu is a required dependency of its receiving composition. Publish it first. The site default is not controlled by a visible active-menu switch: the resolver selects a published default resource using a stable stored order. Where multiple menus exist, bind the intended one explicitly instead of assuming the newest menu wins. The global header role itself is documented under Shared sections.

Sources: Puck integration and editor configuration (repository: `apps/cms/src/cms/editor/composition-editor.tsx`); Configured website components (repository: `apps/cms/src/cms/components/config.tsx`); Public page selection and resource resolution (repository: `apps/cms/src/cms/services/public.ts`); Revision and publication service (repository: `apps/cms/src/cms/services/content.ts`).

## Branding and mobile layout

Site navigation reads the published brand's Logo display choice: the official GroCMS logo, a custom image, or the site name as plain text. The shared Site logo component uses the same choice in footer and body layouts. Change identity in Brand & theme rather than adding a logo row to the menu. Authored text elsewhere remains ordinary content and is not automatically rewritten.

Navigation links wrap responsively on small screens. This website component does not provide a visitor-facing hamburger-menu editor. Preview phone widths after adding labels, especially long organization names or translated text. The content order in the menu remains the reading order when links wrap.

Sources: Configured website components (repository: `apps/cms/src/cms/components/config.tsx`); Public website frame and theme application (repository: `apps/cms/src/app/site-view.tsx`); Website component styles (repository: `apps/cms/src/app/globals.css`); Brand foundations form (repository: `apps/cms/src/components/admin/brand-fields.tsx`).

## Permissions and common fixes

Administrators and designers manage Navigation resources. Editors, authors, and contributors do not manage menus under the current design-resource policy. A saved draft is not the public menu until it is published. Revision history can restore an earlier menu as a working draft; inspect and publish it to reverse a live change.

- Wrong menu visible: inspect the Site navigation binding rather than repeatedly publishing a different menu.
- A single link is missing: check whether its linked entry has an available public route and has been published.
- A typed link is wrong: correct the Link field and publish the menu; changing a Page title will not rewrite literal URLs.
- Two menus appear: check whether navigation exists both in the global header and in the Page's main composition.

Sources: Role and resource permissions (repository: `apps/cms/src/cms/policy/index.ts`); Resource editor and design resource fields (repository: `apps/cms/src/components/admin/resource-editor.tsx`); Public page selection and resource resolution (repository: `apps/cms/src/cms/services/public.ts`); Editor browser verification (repository: `apps/cms/tests/editor-browser.ts`).

## References

- Resource editor and design resource fields — repository path: `apps/cms/src/components/admin/resource-editor.tsx`. Native controls, autosave, publication actions, permissions, template keys, homepage settings, and navigation link editing.

- Configured website components — repository path: `apps/cms/src/cms/components/config.tsx`. The actual component labels, editable fields, slot definitions, and rendering behavior.

- Public page selection and resource resolution — repository path: `apps/cms/src/cms/services/public.ts`. Homepage and template precedence, published resource selection, connected collections, menus, and shared dependencies.

- Searchable reference selection — repository path: `apps/cms/src/components/admin/reference-picker.tsx`. Remote search, pagination, selected entry resolution, and published-only choices.

- Content and composition validation — repository path: `apps/cms/src/cms/validation.ts`. Layout size, nesting, supported components, safe links, menu limits, color validation, and resource references.

- Revision and publication service — repository path: `apps/cms/src/cms/services/content.ts`. Immutable revisions, required published dependencies, cycle checks, preview selection, and publication actions.

- Puck integration and editor configuration — repository path: `apps/cms/src/cms/editor/composition-editor.tsx`. Available canvas sizes, native rich text, remote resource pickers, patterns, and read-only behavior.

- Public website frame and theme application — repository path: `apps/cms/src/app/site-view.tsx`. Header, footer, default layouts, archive listings, brand colors, and WOFF2 font application.

- Website component styles — repository path: `apps/cms/src/app/globals.css`. Responsive columns, typography, public theme variables, section tones and hero decoration.

- Brand foundations form — repository path: `apps/cms/src/components/admin/brand-fields.tsx`. Color and font controls, logo selection, and validated brand token import/export.

- Role and resource permissions — repository path: `apps/cms/src/cms/policy/index.ts`. Design resources belong to administrator and designer capabilities; content permissions differ.

- Editor browser verification — repository path: `apps/cms/tests/editor-browser.ts`. Save/reload evidence for canonical rich text, slots, copied layouts, brand tokens, menus, and remote selection.

## Related guides

- [Shared sections](https://grocms.com/docs/shared-sections)

- [Brand & theme](https://grocms.com/docs/brand-and-theme)

- [Pages](https://grocms.com/docs/pages)

- [Homepage](https://grocms.com/docs/homepage)

- [Visual editor](https://grocms.com/docs/visual-editor)

- [Settings](https://grocms.com/docs/settings)

- [Troubleshooting](https://grocms.com/docs/troubleshooting)