Primer comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently.
This repository is a module of the full primer repository.
This repository is distributed with npm. After installing npm, you can install primer-navigation
with this command.
$ npm install --save primer-navigation
The source files included are written in Sass (scss
) You can simply point your sass include-path
at your node_modules
directory and import it like this.
@import "primer-navigation/index.scss";
You can also import specific portions of the module by importing those partials from the /lib/
folder. Make sure you import any requirements along with the modules.
For a compiled css version of this module, a npm script is included that will output a css version to build/build.css
The built css file is also included in the npm package.
$ npm run build
Primer comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently.
The menu is a vertical list of navigational links. A menu’s width and placement must be set by you. If you like, just use our grid columns as a parent. Otherwise, apply a custom width
.
```html title=”Menu”
There are a few subcomponents and add-ons that work well with the menu, including avatars, counters, and Octicons.
```erb title="Menu with octicons, avatars and counters"
<nav class="menu" aria-label="Person settings">
<a class="menu-item selected" href="#url" aria-current="page">
<%= octicon "tools" %>
Account
</a>
<a class="menu-item" href="#url">
<%= octicon "person" %>
Profile
</a>
<a class="menu-item" href="#url">
<%= octicon "mail" %>
Emails
</a>
<a class="menu-item" href="#url">
<%= octicon "radio-tower" %>
<span class="Counter">3</span>
Notifications
</a>
</nav>
You can also add optional headings to a menu. Feel free to use nearly any semantic element with the .menu-heading
class, including inline elements, headings, and more.
```html title=”Menu with heading”
## Underline nav
Use `.UnderlineNav` to style navigation with a minimal underlined selected state, typically used for navigation placed at the top of the page. This component comes with variations to accommodate icons, containers and other content.
```html title="UnderlineNav"
<nav class="UnderlineNav">
<div class="UnderlineNav-body">
<a href="#url" role="tab" title="Item 1" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" role="tab" title="Item 2" class="UnderlineNav-item">Item 2</a>
<a href="#url" role="tab" title="Item 3" class="UnderlineNav-item">Item 3</a>
<a href="#url" role="tab" title="Item 4" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
Use .UnderlineNav-actions
to place another element, such as a button, to the opposite side of the navigation items.
```html title=”UnderlineNav-actions”
Use `.UnderlineNav--right` to right align the navigation.
```html title="UnderlineNav--right"
<nav class="UnderlineNav UnderlineNav--right">
<div class="UnderlineNav-body">
<a href="#url" role="tab" title="Item 1" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" role="tab" title="Item 2" class="UnderlineNav-item">Item 2</a>
<a href="#url" role="tab" title="Item 3" class="UnderlineNav-item">Item 3</a>
<a href="#url" role="tab" title="Item 4" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
.UnderlineNav--right
also works with when used with .UnderlineNav-actions
.
```html title=”UnderlineNav–right with actions”
<!-- Update wording here -->
`.Counters` and `.octicons` can be used with navigation items. Use `.UnderlineNav-octicon` to add color and hover styles.
```erb title="UnderlineNav with Counter"
<nav class="UnderlineNav" aria-label="Foo bar">
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 1
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 2
<span class="Counter">10</span>
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 3
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 4
</a>
</div>
</nav>
Use .UnderlineNav--full
in combination with container styles and .UnderlineNav-container
to make navigation fill the width of the container.
```html title=”UnderlineNav–full”
## Tabnav
When you need to toggle between different views, consider using a tabnav. It'll given you a left-aligned horizontal row of... tabs!
```html title="tabnav"
<div class="tabnav">
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo tab</a>
<a href="#url" class="tabnav-tab">Bar tab</a>
</nav>
</div>
Use .float-right
to align additional elements in the .tabnav
:
```html title=”tabnav with buttons”
Additional bits of text and links can be styled for optimal placement with `.tabnav-extra`:
```html title="tabnav-extra"
<div class="tabnav">
<div class="tabnav-extra float-right">
Tabnav widget text here.
</div>
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo Tab</a>
<a href="#url" class="tabnav-tab">Bar Tab</a>
</nav>
</div>
```html title=”tabnav with everything”
## Filter list
A vertical list of filters. Grey text on white background. Selecting a filter from the list will fill its background with blue and make the text white.
```html title="filter-list"
<ul class="filter-list">
<li>
<a href="#url" class="filter-item selected" aria-current="page">
<span class="count" title="results">21</span>
First filter
</a>
</li>
<li>
<a href="#url" class="filter-item">
<span class="count" title="results">3</span>
Second filter
</a>
</li>
<li>
<a href="#url" class="filter-item">
Third filter
</a>
</li>
</ul>
.subnav
is navigation that is typically used when on a dashboard type interface with another set of navigation above it. This helps distinguish navigation hierarchy.
```html title=”subnav”
You can have `subnav-search` in the subnav bar.
```erb title="subnav-search"
<div class="subnav">
<nav class="subnav-links" aria-label="Repository">
<a href="#url" class="subnav-item selected" aria-current="page">Item 1</a>
<a href="#url" class="subnav-item">Item 2</a>
<a href="#url" class="subnav-item">Item 3</a>
</nav>
<div class="subnav-search float-left">
<input type="search" name="name" class="form-control subnav-search-input" value="" aria-label="Search site">
<%= octicon "search", :class => "subnav-search-icon" %>
</div>
</div>
You can also use a subnav-search-context
to display search help in a select menu.
```erb title=”subnav-search-context”
```