Components

SecondaryNav

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>
  );
}

Maximum Item Width #

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.

NameTypeDefaultDescription
align'start' | 'center' | 'end' | 'justify''start'

Horizontal alignment of items

childrenReact$Node
itemAsReact$Element<*> | string'a'

React element used for items (see example)

itemsItems

Navigational items (see example)

maxItemWidthnumber | 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

overflowAtIndexnumber

Index at which NavItems overflow into a "More" Dropdown menu

selectedIndexnumber

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.

VariableValue
SecondaryNav_backgroundColor_pillstheme.backgroundColor
SecondaryNav_backgroundColor_tabstheme.color_gray_20
SecondaryNav_border1px solid color_gray_30
SecondaryNav_guttertheme.space_inline_xxs
SecondaryNav_paddingHorizontal0.75em
SecondaryNav_paddingVerticaltheme.space_stack_sm
SecondaryNavItem_backgroundColor_pillstransparent
SecondaryNavItem_backgroundColor_pills_activetheme.color_gray_10
SecondaryNavItem_backgroundColor_pills_focustransparent
SecondaryNavItem_backgroundColor_pills_hovertransparent
SecondaryNavItem_backgroundColor_pills_selectedtheme.backgroundColor_themePrimary
SecondaryNavItem_backgroundColor_tabstransparent
SecondaryNavItem_backgroundColor_tabs_activetheme.color_gray_10
SecondaryNavItem_backgroundColor_tabs_focustransparent
SecondaryNavItem_backgroundColor_tabs_hovertransparent
SecondaryNavItem_backgroundColor_tabs_selectedtheme.backgroundColor
SecondaryNavItem_borderColor_pillstransparent
SecondaryNavItem_borderColor_pills_activetransparent
SecondaryNavItem_borderColor_pills_focustheme.color_theme_40
SecondaryNavItem_borderColor_pills_hovertransparent
SecondaryNavItem_borderColor_pills_selectedtheme.backgroundColor_themePrimary
SecondaryNavItem_borderColor_tabstransparent
SecondaryNavItem_borderColor_tabs_activetransparent
SecondaryNavItem_borderColor_tabs_focustheme.color_theme_40
SecondaryNavItem_borderColor_tabs_hovertransparent
SecondaryNavItem_borderColor_tabs_selectedtheme.color_theme_40
SecondaryNavItem_color_pillstheme.color_gray_80
SecondaryNavItem_color_pills_hovertheme.color_theme_60
SecondaryNavItem_color_pills_selectedtheme.color_themePrimary
SecondaryNavItem_color_tabstheme.color_gray_80
SecondaryNavItem_color_tabs_hovertheme.color_theme_60
SecondaryNavItem_color_tabs_selectedtheme.color_theme_70
SecondaryNavItem_paddingHorizontaltheme.space_inset_md
SecondaryNavItemIcon_colorinherit

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.