SecondaryNav | Mineral UI

SecondaryNav serves additional navigation needs for your app.

Examples #

Import Syntax #

import { SecondaryNav, NavItem } from 'mineral-ui/Navigation';

Basic Usage #

Use NavItem children to define the navigation options.

<SecondaryNav>
  <NavItem href="/malachite">Malachite</NavItem>
  <NavItem selected href="/fluorite">Fluorite</NavItem>
  <NavItem href="/magnetite">Magnetite</NavItem>
</SecondaryNav>

Data-Driven #

Instead of children, you can define your items and use the selectedIndex property to set which item is currently being viewed.

() => {
  const items = [
    {
      href: '/malachite',
      text: 'Malachite'
    },
    {
      href: '/fluorite',
      text: 'Fluorite'
    },
    {
      href: '/magnetite',
      text: 'Magnetite'
    }
  ];

  return <SecondaryNav items={items} selectedIndex={1} />;
}

Type #

SecondaryNav has two display types, 'pills' (default) and 'tabs'.

<SecondaryNav type="tabs">
  <NavItem href="/malachite">Malachite</NavItem>
  <NavItem selected href="/fluorite">Fluorite</NavItem>
  <NavItem href="/magnetite">Magnetite</NavItem>
</SecondaryNav>

Alignment #

Control the alignment of the list of NavItems with the align prop. Note that a value of 'justify' will force all NavItems to be equal width and maxItemWidth will not apply.

() => {
  const alignments = ['start', 'center', 'end', 'justify'];

  return (
    <DemoLayout>
      {alignments.map((alignment) => (
        <SecondaryNav align={alignment} key={alignment}>
          <NavItem href="/malachite">Malachite</NavItem>
          <NavItem href="/fluorite">Fluorite</NavItem>
          <NavItem href="/magnetite">Magnetite</NavItem>
        </SecondaryNav>
      ))}
    </DemoLayout>
  );
}

Use the maxItemWidth prop to constrain the width of each NavItem. Note that if the item's text is longer than the maximum width, it will be truncated but accessible via Tooltip. Also note that if the maxWidth property is set for an item, it will take precedence.

<SecondaryNav maxItemWidth="8em">
  <NavItem href="/malachite">Malachite</NavItem>
  <NavItem href="/fluorite">Fluorite will truncate</NavItem>
  <NavItem href="/magnetite">Magnetite</NavItem>
</SecondaryNav>

Overflow #

If there is not sufficient space to display all navigation items, e.g. when a media query dictates a narrow width, they can be overflowed into a Dropdown menu with the overflowAtIndex property.

() => {
  const items = [
    {
      href: '/malachite',
      text: 'Malachite'
    },
    {
      href: '/fluorite',
      text: 'Fluorite'
    },
    {
      href: '/magnetite',
      text: 'Magnetite'
    },
    {
      href: '/aragonite',
      text: 'Aragonite'
    }
  ];

  return (
    <DemoLayout style={{ width: '23em' }}>
      <SecondaryNav overflowAtIndex={2}>
        {items.map((item) => {
          return <NavItem key={item.href} {...item}>{item.text}</NavItem>
        })}
      </SecondaryNav>

      <SecondaryNav items={items} overflowAtIndex={2} />
    </DemoLayout>
  );
}

Item As #

Any component that renders an <a /> element may be used for NavItem by specifying the itemAs prop, such as a React Router Link.

<SecondaryNav itemAs={ReactRouterLink}>
  <NavItem to="/malachite">Malachite</NavItem>
  <NavItem to="/fluorite">Fluorite</NavItem>
  <NavItem to="/magnetite">Magnetite</NavItem>
</SecondaryNav>

Bidirectionality #

SecondaryNav supports right-to-left (RTL) languages. The alignment is reversed when the direction theme variable is set to 'rtl'. The messages prop allows customization of various messages — both those that are displayed, and those that are announced by assistive technologies.

() => {
  const messages = {
    moreLabel: 'المزيد من عناصر الملاحة',
    moreText: 'أكثر من'
  };

  return (
    <div dir="rtl">
      <ThemeProvider theme={{direction: 'rtl'}}>
        <SecondaryNav messages={messages} align="start">
          <NavItem href="/page-1">علامة التبويب 1</NavItem>
          <NavItem href="/page-2">علامة التبويب 2</NavItem>
          <NavItem href="/page-3">علامة التبويب 3</NavItem>
        </SecondaryNav>
      </ThemeProvider>
    </div>
  );
}

API & Theme #

SecondaryNav Props #

The SecondaryNav component takes the following React props.

Name	Type	Default	Description
align	'start' \| 'center' \| 'end' \| 'justify'	'start'	Horizontal alignment of items
children	React$Node		NavItems (see example)
itemAs	React$Element<*> \| string	'a'	React element used for items (see example)
items	Items		Navigational items (see example)
maxItemWidth	number \| string	'8.5em'	Maximum width of each item
messages			Various messages and labels used by SecondaryNav (see example for more details)
onChange			Called when an item is selected
overflowAtIndex	number		Index at which NavItems overflow into a "More" Dropdown menu
selectedIndex	number		Index of the selected item
type	'pills' \| 'tabs'	'pills'	Available display types

Undocumented properties, including as and css, will be applied to the root element.

SecondaryNav Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
SecondaryNav_backgroundColor_pills	theme.backgroundColor
SecondaryNav_backgroundColor_tabs	theme.color_gray_20
SecondaryNav_border	1px solid color_gray_30
SecondaryNav_gutter	theme.space_inline_xxs
SecondaryNav_paddingHorizontal	0.75em
SecondaryNav_paddingVertical	theme.space_stack_sm
SecondaryNavItem_backgroundColor_pills	transparent
SecondaryNavItem_backgroundColor_pills_active	theme.color_gray_10
SecondaryNavItem_backgroundColor_pills_focus	transparent
SecondaryNavItem_backgroundColor_pills_hover	transparent
SecondaryNavItem_backgroundColor_pills_selected	theme.backgroundColor_themePrimary
SecondaryNavItem_backgroundColor_tabs	transparent
SecondaryNavItem_backgroundColor_tabs_active	theme.color_gray_10
SecondaryNavItem_backgroundColor_tabs_focus	transparent
SecondaryNavItem_backgroundColor_tabs_hover	transparent
SecondaryNavItem_backgroundColor_tabs_selected	theme.backgroundColor
SecondaryNavItem_borderColor_pills	transparent
SecondaryNavItem_borderColor_pills_active	transparent
SecondaryNavItem_borderColor_pills_focus	theme.color_theme_40
SecondaryNavItem_borderColor_pills_hover	transparent
SecondaryNavItem_borderColor_pills_selected	theme.backgroundColor_themePrimary
SecondaryNavItem_borderColor_tabs	transparent
SecondaryNavItem_borderColor_tabs_active	transparent
SecondaryNavItem_borderColor_tabs_focus	theme.color_theme_40
SecondaryNavItem_borderColor_tabs_hover	transparent
SecondaryNavItem_borderColor_tabs_selected	theme.color_theme_40
SecondaryNavItem_color_pills	theme.color_gray_80
SecondaryNavItem_color_pills_hover	theme.color_theme_60
SecondaryNavItem_color_pills_selected	theme.color_themePrimary
SecondaryNavItem_color_tabs	theme.color_gray_80
SecondaryNavItem_color_tabs_hover	theme.color_theme_60
SecondaryNavItem_color_tabs_selected	theme.color_theme_70
SecondaryNavItem_paddingHorizontal	theme.space_inset_md
SecondaryNavItemIcon_color	inherit

Usage #

When/How to Use #

Mineral supports several different types of navigation. The correct navigation component should be selected based on your application’s information architecture.

SecondaryNav is for second or third level lateral navigation, where the user would be moving between two or more destinations at the same level of the application hierarchy. This component should allow the user to navigate within a section of the application hierarchy. It can be used in conjunction with all other navigation types.

SecondaryNav has two display types: pills and tabs. Use pills to represent view navigation where the number of items does not change for a given section. Use tabs type to represent document-based navigation, where the number of navigation items could vary for a given section.

Best Practices #

Choose the correct type of SecondaryNav to represent the content. Use the tabs type for document-based navigation, and the pills type for page/view navigation.

Use SecondaryNav in conjunction with PrimaryNav for applications that have two or more levels of hierarchy.

Choose SecondaryNav when there are few items in a section. If you have many items, prioritize the navigation items so the most important items are first, so they are less likely to overflow into the menu.

SecondaryNav items should be immediately recognizable. Use short words or phrases for text labels, which consistently start with nouns or verbs. Include icons if they assist the user in quick recognition of the functionality.

Avoid long titles which would force truncation.

Don't mix content types for NavItem titles. Be consistent with icon usage; either all or no NavItems should contain an icon.

Don't use SecondaryNav when there is only one NavItem.