PrimaryNav | Mineral UI

PrimaryNav provides the main, top-level navigation for an app, usually in the page header.

Examples #

Import Syntax #

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

Basic Usage #

Use NavItem children to define the navigation options.

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

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 <PrimaryNav items={items} selectedIndex={1} />;
}

Minimal #

Use the minimal property to display PrimaryNav in a more minimal appearance.

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

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) => (
        <PrimaryNav align={alignment} key={alignment}>
          <NavItem href="/malachite">Malachite</NavItem>
          <NavItem href="/fluorite">Fluorite</NavItem>
          <NavItem href="/magnetite">Magnetite</NavItem>
        </PrimaryNav>
      ))}
    </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.

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

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'
    }
  ];

  const onChange = (selectedIndex, event) => {
    event.preventDefault();
    console.log(selectedIndex + ' clicked')
  }

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

      <PrimaryNav items={items} overflowAtIndex={2} onChange={onChange} />
    </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.

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

Bidirectionality #

PrimaryNav 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'}}>
        <PrimaryNav messages={messages} align="start">
          <NavItem href="/page-1">علامة التبويب 1</NavItem>
          <NavItem href="/page-2">علامة التبويب 2</NavItem>
          <NavItem href="/page-3">علامة التبويب 3</NavItem>
        </PrimaryNav>
      </ThemeProvider>
    </div>
  );
}

API & Theme #

PrimaryNav Props #

The PrimaryNav component takes the following React props.

Name	Type	Default	Description
align	'start' \| 'center' \| 'end' \| 'justify'	'center'	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 PrimaryNav (see example for more details)
minimal	boolean		Display PrimaryNav with 'minimal' styles
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

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

PrimaryNav 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
PrimaryNav_backgroundColor	theme.backgroundColor_themePrimary
PrimaryNav_backgroundColor_minimal	theme.backgroundColor
PrimaryNav_gutter	theme.space_inline_xs
PrimaryNav_paddingHorizontal	theme.space_inline_xl
PrimaryNav_paddingVertical	theme.space_stack_sm
PrimaryNavItem_backgroundColor	transparent
PrimaryNavItem_backgroundColor_active	theme.color_theme_80
PrimaryNavItem_backgroundColor_focus	transparent
PrimaryNavItem_backgroundColor_hover	theme.color_theme_70
PrimaryNavItem_backgroundColor_selected	theme.color_theme_80
PrimaryNavItem_backgroundColor_minimal	transparent
PrimaryNavItem_backgroundColor_minimal_active	theme.color_gray_10
PrimaryNavItem_backgroundColor_minimal_focus	transparent
PrimaryNavItem_backgroundColor_minimal_hover	transparent
PrimaryNavItem_backgroundColor_minimal_selected	theme.color_gray_10
PrimaryNavItem_borderColor	transparent
PrimaryNavItem_borderColor_active	transparent
PrimaryNavItem_borderColor_focus	theme.color_theme_20
PrimaryNavItem_borderColor_hover	transparent
PrimaryNavItem_borderColor_selected	theme.color_theme_80
PrimaryNavItem_borderColor_minimal	transparent
PrimaryNavItem_borderColor_minimal_active	transparent
PrimaryNavItem_borderColor_minimal_focus	theme.color_theme_40
PrimaryNavItem_borderColor_minimal_hover	transparent
PrimaryNavItem_borderColor_minimal_selected	theme.color_theme_40
PrimaryNavItem_color	theme.color_themePrimary
PrimaryNavItem_color_disabled	theme.color_theme_40
PrimaryNavItem_color_hover	theme.color_themePrimary
PrimaryNavItem_color_selected	theme.color_themePrimary
PrimaryNavItem_color_minimal	theme.color_gray_80
PrimaryNavItem_color_minimal_hover	theme.color_theme_60
PrimaryNavItem_color_minimal_selected	theme.color_theme_70
PrimaryNavItem_paddingHorizontal	theme.space_inset_sm
PrimaryNavItemIcon_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.

PrimaryNav is for top-level lateral navigation, where the user would be moving between two or more destinations at the top level of the application hierarchy. This component should allow the user to navigate to all of the main sections within the application. It can be used in conjunction with all other navigation types.

PrimaryNav can also be used to navigate between suites of products, if another in-app navigation method is also present in each of the individual products.

Best Practices #

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

PrimaryNav 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 PrimaryNav when there is only one NavItem.