Jump Links

Overview

Jump links act as persistent navigation that consists of a list of anchor links. Selecting a link moves a user to content that corresponds with the link selected. A link is displayed as active when the content it links to is visible in the browser window.

Installation

npm install @patternfly/pfe-jump-links

Usage

This component is focused on reading content inside the and updating a sidebar or horizontal nav with to indicate the section of the document currently being viewed. As a developer, you have the choice of whether you bring your own markup to the nav, or have the nav build a DOM tree for you. Please note the shape of the DOM tree below. In order to support sub-section highlighting jump links must be very opinionated about the DOM tree.

Inside of add the class .pfe-jump-links-panel__section to tell the component to watch for when that section crosses the scroll threshold. If this section has sub-sections you add the class .has-sub-section to the section parent (i.e. section 8) and add .sub-section to the child sections (i.e. 8.1). Make sure to add an id to each section, this id will match to the href attribute of the corresponding tag.

Wiring up the nav

The panel and nav are wired up by a scrolltarget and id. On the panel add an attribute scrolltarget="foo". This will correspond to the nav's #id. Add the corresponding id to your nav like so id="foo". The last step is to match the tag's href attribute to specific sections (just like we would with same page anchor links). See below for a simple example with three sections where section two has two sub-sections:

<pfe-jump-links id="jumplinks1">
  <h4 slot="heading">Jump to section</h4>
  <ul>
    <li>
      <a href="#section1">Section 1</a>
    </li>
    <li class="has-sub-section">
      <a href="#section2">Section 2</a>
      <ul class="sub-nav">
        <li class="sub-section">
          <a href="#section2.1">Section 2.1</a>
        </li>
        <li class="sub-section">
          <a href="#section2.2">Section 2.2</a>
        </li>
      </ul>
    </li>
    <li>
      <a href="#section3">Section 3</a>
    </li>
  </ul>
</pfe-jump-links>
...
<pfe-jump-links-panel>
  <h2 id="section1">Section 1</h2>
  <p>Some content...</p>
  <h2 class="has-sub-section" id="section2">Section 2</h2>
  <p>Some content...</p>
  <h2 class="sub-section" id="section2.1">Section 2.1</h2>
  <p>Some content...</p>
  <h2 class="sub-section" id="section2.2">Section 2.2</h2>
  <p>Some content...</p>
  <h2 id="section3">Section 3</h2>
  <p>Some content...</p>
</pfe-jump-links-panel>

Slots

Slots on pfe-jump-links-nav

Default Slot

The component creates a mirror shadowRoot based on the light DOM markup provided in the default slot.

heading

The label displayed above the navigation element describing it's function. Defaults to "Jump to section".

logo

Optionally add a logo that can appear in the horizontal layout mode.

cta

Optionally add a call-to-action element at the bottom of the nav.

Slots on pfe-jump-links-panel

Default Slot

Panel content

Attributes

autobuild

Flips the switch on the component to create its own markup for the navigation. You can add pfe-jump-links-panel__section to each section that should show in the nav. If you want to use sub-sections add has-sub-section to the parent section that should always show and the sub-section class to the children of that section. If you use this attribute, keep in mind that non-JavaScript environments (some search engines, browsers with JS disabled) will not see the proper markup.

DOM Property

autobuild

Type

boolean

Default

false

horizontal

Horizontal

DOM Property

horizontal

Type

boolean

Default

false

stuck

Stickiness state

DOM Property

stuck

Type

boolean

Default

false

no-header

Opt-out of the header region

DOM Property

noHeader

Type

boolean

Default

false

sr-text

This attribute is read when the component upgrades to provide the innerText of the heading. If there is no sr-text attribute then the component defaults to "JUMP TO SECTION". This attribute is to enable translations and internationalization.

DOM Property

srText

Type

string

Default

'Jump to section'

color-palette

Sets color palette, which affects the element's styles as well as descendants' color theme. Overrides parent color context. Your theme will influence these colors so check there first if you are seeing inconsistencies. See CSS Custom Properties for default values

Card always resets its context to base, unless explicitly provided with a color-palette.

DOM Property

colorPalette

Type

ColorPalette | undefined

Default

unknown

on

Sets color theme based on parent context

DOM Property

on

Type

ColorTheme | undefined

Default

unknown

offset

This attribute determines the distance from the top of the browser window to trigger a switch from one link being active to the next. For instance offset="600" would mean that threshold flips at 600px from the top. The default is set at 200, and if you desire 200px then you can leave this attribute off. The offset attribute should be placed on pfe-jump-links-panel. There is a css solution to control the offset, however the attribute value takes precedence over css. To read more about a css solution see below.

DOM Property

offset

Type

number | undefined

Default

unknown

mobile-breakpoint

Mobile breakpoint (max-width)

DOM Property

mobileBreakpoint

Type

string | undefined

Default

unknown

accordion-collapse-timing

Number of ms to wait before collapsing the accordion on click

DOM Property

accordionCollapseTiming

Type

number

Default

750

DOM Properties

container

Container element from the shadow DOM for the nav list

Type

HTMLElement|null | undefined

Default

unknown

isMobile

Type

boolean | '991px'

Default

unknown

header

Slot assigned to heading

Type

Element

Default

unknown

cta

Slot assigned to cta

Type

Element

Default

unknown

logo

Slot assigned to logo

Type

Element

Default

unknown

panel

This getter returns the panel for the navigation item; if a custom pointer was set it will return that, otherwise, it tries to find the panel

Type

PfeJumpLinksPanel|null

Default

unknown

sections

Capture the sections from inside the "panel"; default to this._sections first then fallback to grepping the sections from the panel

Type

NodeListOf<HTMLElement>|null

Default

unknown

links

Type

HTMLAnchorElement[]

Default

unknown

items

Type

HTMLLIElement[]

Default

unknown

offsetValue

Type

number

Default

unknown

Methods

scrollToSection(idx: number, Index: Number)

This handles scrolling to a section in the panel on click

build(_sections: NodeListOf<HTMLElement>|null, sections: unknown)

Builds the navigation based on the provided data or the defined sections

closeAccordion()

Close the mobile accordion

rebuild()

Rebuild the navigation if the sections or panels are updated

active(item: )

getActive()

inactive(item: number|Element)

clearActive()

updateItem(item: HTMLLIElement, nested: unknown)

updateLightDOM()

Events

change

when the current active item changes.

Event Type:

ChangeEvent

stuck

when the nav sticks or un-sticks from the top of its container.

Event Type:

NavStuckEvent

CSS Custom Properties

CSS Shadow Parts

None