Gatsby-theme-ni NPM

gatsby-theme-ni

This is the base theme for building NI-branded Gatsby sites. It contains a small amount of configuration, and a handful of components that make it easy to build consistent-looking UIs.

It comes with a few Gatsby plugins:

gatsby-plugin-svgr enables importing SVGs as React components
gatsby-plugin-emotion server renders your Emotion styles
gatsby-plugin-react-helmet server renders <head> tags set with React Helmet
gatsby-plugin-typography provides a stylesheet reset and sets default styles for basic HTML elements

Installation
Configuration
Components and utilities
Examples

Installation

$ npm install gatsby gatsby-theme-ni

Configuration

// gatsby-config.js
module.exports = {
  __experimentalThemes: [
    {
      resolve: 'gatsby-theme-ni',
      options: {
        root: __dirname
      }
    }
  ],
  siteMetadata: {
    title: 'Apollo rocks!',
    description: 'Gatsby themes are pretty cool too...'
  }
};

Components and utilities

All of the React components and utilities documented here are available as named exports in the gatsby-theme-ni package. You can import them like this:

import {MenuButton, Sidebar, breakpoints} from 'gatsby-theme-ni';

Layout

Layout should wrap every page that gets created. It configures React Helmet and sets the meta description tag with data from the siteMetadata property in your Gatsby config. It also sets the favicon for the page to the Apollo "A" logo.

import {Layout} from 'gatsby-theme-ni';

function MyPage() {
  return (
    <Layout>
      Hello world
    </Layout>
  );
}

Prop name	Type	Required
children	node	yes

Header

A sticky header component with a white background and our brand primary, #220a82 #220a82 as the font color.

import {Layout, Header} from 'gatsby-theme-ni';

function MyPage() {
  return (
    <Layout>
      <Header>Main nav goes up here</Header>
    </Layout>
  );
}

MobileHeader and DesktopHeader components are also exported, and can be used to easily render headers with different content depending on the window size.

import {Layout, MobileHeader, DesktopHeader} from 'gatsby-theme-ni';

function MyPage() {
  return (
    <Layout>
      <MobileHeader>
        This is only shown on mobile
        <HamburgerMenu />
      </MobileHeader>
      <DesktopHeader>
        <Logo />
        This is only shown on desktop
        <HorizontalMenu />
      </DesktopHeader>
    </Layout>
  );
}

Prop name	Type	Required
children	node	yes

Sidebar

A component that renders a sidebar with a LogoTitle component in the top left corner. It can also be configured to collapse into the left side of the page on narrow windows.

import {Layout, Sidebar} from 'gatbsy-theme-ni';

function MyPage() {
  return (
    <Layout>
      <Sidebar>
        Sidebar content goes here
      </Sidebar>
    </Layout>
  );
}

Prop name	Type	Required	Description
children	node	yes
responsive	bool	no	If `true`, the sidebar will behave as a drawer absolutely positioned on the left
open	bool	no	Controls the sidebar visibility when the `responsive` prop is `true`
noLogo	bool	no	If `true`, the logo next to the site title at the top left will be hidden

SidebarNav

A configurable two-tiered, expandable/collapsible navigation component for use in conjunction with the Sidebar component above. It accepts a contents prop that defines what links and collapsible sections get rendered. Here's an example of the expected shape of a contents prop:

const contents = [
  {
    title: 'Getting started',
    path: '/'
  },
  {
    title: 'External link',
    path: 'https://apollographql.com',
    anchor: true
  },
  {
    title: 'Advanced features',
    pages: [
      {
        title: 'Schema stitching',
        path: '/advanced/schema-stitching'
      }
    ]
  }
];

Each element in the array can have title, path, pages, and anchor props. pages is an array of more elements with the same shape. By default, a Gatsby Link component will be used to render the links, but you can use a regular HTML anchor tag (<a>) by passing the anchor property to true on any page object.

The SidebarNav component gives the currently selected page an "active" style, and if it's a subpage, it will keep the currently active section expanded. To facilitate this, you must pass the current path to the pathname prop. Luckily, Gatsby exposes this in the location prop that gets passed automatically to every page!

import {Layout, Sidebar, SidebarNav} from 'gatsby-theme-ni';

function MyPage(props) {
  return (
    <Layout>
      <Sidebar>
        <SidebarNav
          contents={contents}
          pathname={props.location.pathname}
        />
      </Sidebar>
    </Layout>
  );
}

Prop name	Type	Required	Description
contents	array	yes	An array of items to render
pathname	string	yes	The current path (`props.location.pathname` expected)
alwaysExpanded	bool	no	If `true`, all collapsible sections are expanded and cannot close

ResponsiveSidebar

A render props component that manages the state for responsive sidebars. On mobile devices, the sidebar is opened by a MenuButton component, and dismissed when the user clicks away from the sidebar. This component's children prop accepts a function that provides values and functions to enable this behavior easily.

import {
  Layout,
  Sidebar,
  ResponsiveSidebar,
  FlexWrapper,
  MenuButton
} from 'gatsby-theme-ni';

function MyPage() {
  return (
    <Layout>
      <ResponsiveSidebar>
        {({sidebarOpen, openSidebar, onWrapperClick, sidebarRef}) => (
          <FlexWrapper onClick={onWrapperClick}>
            <Sidebar responsive open={sidebarOpen} ref={sidebarRef}>
              This is a sidebar
            </Sidebar>
            <MenuButton onClick={openSidebar} />
          </FlexWrapper>
        )}
      </ResponsiveSidebar>
    </Layout>
  );
}

Prop name	Type	Required	Description
children	func	yes	A render prop-style function that returns a React component

LogoTitle

A component that renders a NI logo, and the site title, as defined in the siteMetadata Gatsby config option.

import {LogoTitle} from 'gatsby-theme-ni';

function MyPage() {
  return <LogoTitle />;
}

Through component shadowing, you can override the logo that gets shown. Simply create a file that exports a SVG React component in your theme consumer at src/gatsby-theme-ni/components/logo.js.

// src/gatsby-theme-ni/components/logo.js
export {ReactComponent as default} from '../../assets/custom-logo.svg';

Check out this CodeSandbox for a full component shadowing example!

Prop name	Type	Required	Description
noLogo	bool	no	If `true`, the NI logo is hidden

colors

An object mapping semantic names to hex strings. All of these colors are drawn from Space Kit. You can use this utility to write CSS-in-JS rules like this:

import {colors} from 'gatsby-theme-ni';

const StyledButton = styled.button({
  color: colors.primary,
  background: colors.background
});

breakpoints

A mapping of size keys to media queries. This is useful for writing responsive CSS-in-JS components.

import {breakpoints} from 'gatsby-theme-ni';

const StyledMenu = styled.nav({
  fontSize: 24,
  [breakpoints.lg]: {
    fontSize: 20
  },
  [breakpoints.md]: {
    fontSize: 16
  },
  [breakpoints.sm]: {
    fontSize: 12
  }
})