Components

Page Navigation

A list-style navigation component for organizing and displaying page links.

Usage

The Page Navigation component is a list-style navigation component that organizes and displays page links. The links can be grouped under a common header, making it ideal for navigation menus, organized resource lists, or anywhere you need to group related links under a clear heading.

The component can automatically fetch child pages of a given page path, allowing you to create a dynamic navigation structure based on your Portal's page structure(s). Internally, the Page Navigation component utilizes the Link Group component, which allows for fully-customizable groups of links.

Auto-generated navigation

The Page Navigation component can be used to automatically generate a navigation structure based on the page hierarchy of your Dev Portal. This is accomplished by providing a top-level href prop to the component, which specifies the absolute path from the root of your Portal for which to begin rendering the page structure.

::page-navigation
---
header: "Auto-Generated Navigation"
href: "/guides" # Render pages beginning at "Guides" page
max-depth: 2
---
::

Customizable navigation groups

Alternatively, you can create a custom, grouped navigation structure by providing an array of groups with links to display. This allows for greater flexibility in organizing and displaying links, as well as the ability to include external links or links to other pages within your Portal.

When providing the groups prop, you may still include auto-generated links by specifying the link href absolute path (similar to above) as well as setting the children prop to true, provided that the link exists in your Dev Portal.

Notice in the example below, we are providing the groups prop with an array of links consisted of custom links, but we are also including a link to the Guides page with the children prop set to true. This will automatically fetch and render the links for the child pages of the /guides page.

This example only shows a single group of links for demonstration purposes, but you can provide multiple groups of links to display by providing multiple objects in the groups array.

::page-navigation
---
groups:
  - header: "Customizable Navigation Groups"
    links:
      - text: "Custom Link"
        href: "#"
        children:
          - text: "Custom Link Child"
            href: "#"
      - text: "Guides"
        href: "/guides"
        children: true
        max-depth: 2
---
::

Props

Auto-generated navigation

href

When provided, the absolute path from the root of your Portal of the Page for which to fetch child pages. As an example, to fetch the /guides page and its children, you would provide the string /guides.
  • Type: string
  • Default: ''
When providing the top-level href prop, optional text to display above the group of links.
  • Type: string
  • Default: ''
If a header is not provided, the group will automatically be expanded.

children

When providing the top-level href prop, pass a boolean to children indicating whether to automatically fetch and render links to the child pages of the given href page.
  • Type: boolean
  • Default: true
The children prop defaults to true when providing the top-level href prop as to always fetch and render child pages, but defaults to false when using the groups prop to give you full control on when to render child pages.

maxDepth

Define the maximum depth of links to render when utilizing the top-level href prop.
  • Type: number
  • Default: 5
Customizable navigation groups

groups

Rather than providing the href to a Page, you can provide an array of groups with links to display.
  • Type: PageNavigationGroup[]
  • Default: []
When defined, takes precedence over the top-level href prop.
When defining groups of links, you can specify the header text for each group, the maximum depth of links to render in that group, and an array of links to display.The maxDepth prop allows you to control how many levels of links are displayed within that group.The links prop is an array of objects that define the individual links within the group. Each link object can include the following properties:
  • text: The display text for the link.
  • href: The URL for the link, which can be either an absolute path relative to the portal domain (e.g., "/page/path") or a full URL (e.g., "https://example.com/page/path").
  • external: A boolean indicating whether the link should open in a new tab. Defaults to false.
  • children: An array of links to display as children of the current link, or a boolean indicating whether to automatically fetch and render child pages of the given link.href path.
The groups prop adheres to the following interfaces:
interface PageNavigationLink extends Omit<LinkGroupLink, 'children'> {
  /** The link display text. */
  text: string
  /**
   * The link URL that can be either:
   * - An absolute path relative to the portal domain (e.g. "/page/path")
   * - A full URL (e.g. "https://example.com/page/path")
   */
  href: string
  /** Whether the link should open in a new tab. Defaults to `false`.*/
  external?: boolean
  /**
   * An array of links to display as children of the current link,
   * or a boolean indicating whether to automatically fetch and render
   * child pages of the given `link.href` path.
   */
  children?: PageNavigationLink[] | boolean
}

interface PageNavigationGroup Array<{
  /** The optional group header text. */
  header?: string
  /** The maximum depth of links to render in the group. Defaults to `5`. */
  maxDepth?: number
  /** The array of links to display in the group. */
  links?: PageNavigationLink[]
}>

hideOnError

Rather than displaying an error in the UI, the component will be completely hidden if it encounters an error in fetching or parsing the generated page links (e.g. when the top-level children prop or link-level prop is true). The error will still be logged in the console. Set this prop to false to display the error in the UI.

  • Type: boolean
  • Default: true

Shared Props

This component also includes the shared props listed below:

  • border - default is initial.
  • borderRadius - default is 0px.
  • height - default is auto.
  • margin - default is 0px.
  • maxWidth - default is 100%.
  • padding - default is 20px.
  • styles - default is ''.

See here for more information on shared props.