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.
Name | Type | Default | Description |
---|---|---|---|
align | 'start' | 'center' | 'end' | 'justify' | 'start' | Horizontal alignment of items |
children | React$Node | ||
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 |
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 title
s.
Be consistent with icon usage; either all or no NavItems should contain an icon.
Don't use SecondaryNav when there is only one NavItem.