Skip to content

Latest commit

 

History

History
204 lines (146 loc) · 5.92 KB

side-navigation.md

File metadata and controls

204 lines (146 loc) · 5.92 KB
Raw

Side navigation (SideNavigation)

A list of navigational links that point to the pages within an application.

Properties

activeHref

Specifies the href of the currently active link. All items within the navigation with a matching href are highlighted. Sections and Expandable Page Groups that contain a highlighted item are automatically expanded, unless their definitions have the defaultExpanded property explicitly set to false.

Type: String

Required: No

className

Adds the specified classes to the root element of the component.

Type: String

Required: No

header

Controls the header that appears at the top of the navigation component. It contains the following:

  • text (string) - Specifies the header text.
  • href (string) - Specifies the href that the header links to.
  • logo (object) - Specifies a logo image.

Type:

SideNavigationProps.Header {
  href: string
  logo?: SideNavigationProps.Logo
  text?: string
}

Required: No

id

Adds the specified ID to the root element of the component.

Type: String

Required: No

items

Specifies the items to be displayed in the navigation. Allowed objects are: Link, Divider, Section, LinkGroup and ExpandableLinkGroup. You can inject extra properties (for example, an ID) in order to identify the item when it's used in an event detail (for more information, see the events section below).

Link

Object that represents an anchor in the navigation. Links are rendered as <a> tags.

  • type - 'link'.
  • text (string) - Specifies the link text.
  • href (string) - Specifies the href of the link.
  • external (boolean) - Determines whether to display an external link icon next to the link. If set to true, an external link icon appears next to the link. The anchor also has the attributes target="_blank" and rel="noopener". Additionally, the activeHref property won't be modified when a user chooses the link.
  • info (ReactNode) - Enables you to display content next to the link. Although it is technically possible to insert any content, our UX guidelines allow only to add a Badge and/or a "New" label.

Divider

Object that represents a horizontal divider between navigation content. It contains type: 'divider' only.

Section

Object that represents a section within the navigation.

  • type: 'section'.
  • text (string) - Specifies the text to display as a title of the section.
  • defaultExpanded (boolean) - Determines whether the section should be expanded by default. Default value is true.
  • items (array) - Specifies the content of the section. You can use any valid item from this list. Although there is no technical limitation to the nesting level, our UX recommendation is to use only one level.

LinkGroup

Object that represents a group of links.

  • type: 'link-group'.
  • text (string) - Specifies the text of the group link.
  • href (string) - Specifies the href of the group link.
  • items (array) - Specifies the content of the section. You can use any valid item from this list. Although there is no technical limitation to the nesting level, our UX recommendation is to use only one level.

ExpandableLinkGroup

Object that represents an expandable group of links.

  • type: 'expandable-link-group'.
  • text (string) - Specifies the text of the group link.
  • href (string) - Specifies the href of the group link.
  • defaultExpanded (boolean) - Specifies whether the group should be expanded by default. If not explicitly set, the group is collapsed by default, unless one of the nested links is active.
  • items (array) - Specifies the content of the section. You can use any valid item from this list. Although there is no technical limitation to the nesting level, our UX recommendation is to use only one level.

Type: ReadonlyArray<SideNavigationProps.Item>

Default: []

Required: No

Events

onChange

Fired when the expansion state of Section or ExpandablePageGroup items changes as a result of a user interaction. The event detail contains an object with information about the changed item.

  • item (object) - Specifies the item that was changed.
  • expanded (boolean) - Specifies whether the item is expanded or not.
  • expandableParents (array) - A list of parent items that have a type of Section or ExpandablePageGroup. Use this expandableParents array to set their expanded state to true if you want your data model to keep track of the current state of the navigation items.

Note: If the expansion is a result of the activation of a nested link upon changing the activeHref property, this event isn't raised.

Detail type:

SideNavigationProps.ChangeDetail {
  expandableParents: ReadonlyArray<
    | SideNavigationProps.ExpandableLinkGroup
    | SideNavigationProps.Section
  >
  expanded: boolean
  item:
    | SideNavigationProps.ExpandableLinkGroup
    | SideNavigationProps.Section
}

Cancelable: No

onFollow

Fired when an anchor is clicked without any modifier (that is, CTRL, ALT, SHIFT). The event detail contains a definition of the clicked item. Use this event to prevent default browser navigation (by calling preventDefault method) and branch your own routing. If the event is prevented the activeHref property won't be automatically set to the href of the clicked item so you'll have to do it yourself.

Detail type:

SideNavigationProps.FollowDetail {
  external?: false | true
  href: string
  info?: React.ReactNode
  target?: string
  text?: string
  type?:
    | "expandable-link-group"
    | "link"
    | "link-group"
}

Cancelable: Yes

License Summary

The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file.