README

react-skeletal-nav 🦴🧭

A set of React components for building recursive navigation UIs for the web

Intro

Makes defining recursive navs as simple as this

const Header = () => (
  <Nav>
    <NavItem title="Item 1" href="/" />
    <NavItem title="Item 2" href="/" />
    <NavItem title="Sub Nav">
      <Nav>
        <NavItem title="Subitem 1" href="/" />
        <NavItem title="Subitem 2" href="/" />
      </Nav>
    </NavItem>
  </Nav>
);

It's also possible to render from JSON by taking advantage from the react-from-json library.

Install

npm install --save react-skeletal-nav

Usage

react-skeletal-nav provides 3 skeleton components:

<Nav /> - The root navigation component.
<NavItem /> - A navigation item, such as a link to a page, or link to a nested <Nav />
<NavList /> - A group of <NavItem /> components. Useful for segmenting your items. Optional.

You need to extend these components for use in your app. It's easiest to use the HOCs provided, but you can also use render props.

Nav.js

import React from 'react';
import { withNav } from 'react-skeletal-nav';

export const Nav = withNav(
  ({ children, goBack, route, isStack, isVisible }) =>
    // Only render stack nav
    isStack && (
      // Hide if not visible, but don't unmount so nested Navs stay mounted
      <div style={{ display: isVisible ? 'block' : 'none' }}>
        {/* Never render the back button on the "root" nav */}
        {route !== 'root' && <button onClick={goBack}>Back</button>}

        {/* Render children, including nested Navs */}
        {children}
      </div>
    )
);

NavItem.js

import React from 'react';
import { withNavItem } from 'react-skeletal-nav';

export const NavItem = withNavItem(({ children, href, onClick, title }) => (
  <div>
    {href && <a href="">{title}</a>}
    {!href && <button onClick={onClick}>{title}</button>}

    {/* Render nested navs */}
    {children}
  </div>
));

App.js

import Nav from './Nav';
import NavItem from './NavItem';

export default () => (
  <Nav>
    <NavItem title="Item 1" href="/" />
    <NavItem title="Item 2" href="/" />
    <NavItem title="Sub Nav">
      <Nav>
        <NavItem title="Subitem 1" href="/" />
        <NavItem title="Subitem 2" href="/" />
      </Nav>
    </NavItem>
  </Nav>
);

Rendering from JSON

We can also render complex navigation UI from JSON, using the react-from-json library. This is particularly useful when working with a headless CMS.

import React from 'react';
import ReactFromJSON from 'react-from-json';
import Nav from './Nav';
import NavItem from './NavItem';

const componentMapping = {
  Nav,
  NavItem
};

const data = {
  type: 'Nav',
  props: {
    children: [
      { type: 'NavItem', props: { href: '/', title: 'Item 1' } },
      { type: 'NavItem', props: { href: '/', title: 'Item 2' } },
      {
        type: 'NavItem',
        props: {
          children: {
            type: 'Nav',
            props: {
              children: [
                {
                  type: 'NavItem',
                  props: { href: '/', title: 'Subitem 1' }
                },
                {
                  type: 'NavItem',
                  props: { href: '/', title: 'Subitem 2' }
                }
              ]
            }
          },
          title: 'SubNav'
        }
      }
    ]
  }
};

export default () => <ReactFromJSON mapping={componentMapping} entry={data} />;

API

TBD

Contributing & Releasing

Follow the angular verison of conventional commits when committing to this repo, as this generates the CHANGELOG.md and ensures we follow semver.

To bump version, generate changelog and prep for release, run:

yarn release

then to publish

npm publish

react-skeletal-nav

Usage no npm install needed!