Gatsby Theme Elements

Build responsive Gatsby themes with layouts powered by ThemeUI.

Gatsby Theme Elements takes care of accessibility, responsive navigation, and theming so you can focus on creating awesome content or adding new integrations to your Gatsby site.

https://gatsby-theme-elements.netlify.com/

Getting Started

To install Elements, first download the theme:

npm i --save gatsby-theme-elements

or

yarn add gatsby-theme-elements

In your gatsby-config.js file, add:

module.exports = {
  plugins: ['gatsby-theme-elements'],
}

Installation

Elements creates your default layout settings by shadowing two configuration files: options.js and theme.js.

Create a new folder in your project's /src directory called gatsby-theme-elements and add these two files:

theme.js

Acts as a wrapper for ThemeUI

Use theme.js to export your theme object without having to shadow gatsby-plugin-theme-ui in your project directory. With ThemeUI, you might:

• Add fonts with Typography.js
• Declare variants
• Set infinite color modes
• Create MDX styles
• Create sizing scales

Elements uses a few custom ThemeUI properties to control default layout styles. Add the following colors and shadows to your theme object:

colors: {
    logo: "",              // SVG logo fill
    border: "",            // Theme border color
    bg_topbar: "",         // Topbar background
    bg_header: "",         // Header background
    bg_mobilenav: "",      // MobileNav background
    bg_sidenav: "",        // SideNav background
    bg_tabbar: "",         // TabBar background
    bg_footer: "",         // Footer background
    text_navlink: "",      // Header link color
    text_topbar: "",       // Topbar text color
},
shadows: {
    header: "",            // Header shadow
    tabbar: "",            // TabBar shadow
  }

If you need to change these values for different layouts, you can always override them at the component level.

options.js

Handles all positioning and DOM measurements

This file lets you set things like widths, scroll behaviors, breakpoints, and animation springs. A complete options.js file looks like this:

export default {
  topbar: {
    sticky: true,
    maxWidth: 1260,
  },
  header: {
    sticky: true,
    stickyMobile: true,
    maxWidth: 1260,
    mobileNavWidth: 300,
    mobileAnimation: "fade", // fade, fadeInUp, fadeInDown, slideRight, slideLeft
    spring: { tension: 170, friction: 26 }, // React Spring config object for your MobileNav
  },
  sideNav: {
    width: "18em",
    spring: { tension: 170, friction: 26 }, // spring config for your responsive SideNav
  },
  content: {
    maxWidth: 1020,
    gridGap: 30,
  },
  sidebar: {
    width: ".3fr",
  },
  footer: {
    maxWidth: 1020,
    gridGap: 30,
  },
  breakpoints: {
    sm: 750,
    md: 960,
    lg: 1240,
  },
}

NOTE: Set your breakpoints in options.js, not your ThemeUI object. Elements currently uses these breakpoint values for layout calculations.

Layout Components

The Elements component library gives you access to all of the hooks and semantic markup you need to quickly build a state of the art website.

Although they can be used independently, the components are aware of one another and work best together in a layout tree like so:

<Layout>
  <Header>
    <Logo />
    <NavMenu />
    <MobileNav />
    <MenuToggle />
    <ColorToggle />
  </Header>

  <ContentWrapper>
    <SideNav />
    <Main>{children}</Main>
  </ContentWrapper>

  <Footer>
    <FooterWidgets />
  </Footer>
</Layout>

Styling

Layout components work seamlessly with ThemeUI's sx prop, so you can weave into and around them to build flexible containers or apply new styles.

By default, the layout components use the settings you defined in options.js and theme.js. This makes building new page layouts and child themes incredibly easy.

Component List

| Component | Description | | ------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Layout | The root layout component (required) | | Topbar | A topbar or status bar that sits above the site header | | Header | A flexible header element that wraps your primary navigation | | Logo | A link that accepts a child or defaults to an optional shadowed logo file. To use without wrapping it around a child component, create a third file in your gatsby-theme-elements directory for a React component called logo.js. | | NavMenu | The site's primary navigation ul wrapped in a nav element. Hides on mobile. | | MenuToggle | Button that accesses the useMenu hook to toggle a mobile menu. It comes with default hamburger and close icons or you can wrap it around your own. | | ColorToggle | Button that accesses ThemeUI's colorMode hook to cycle through colors. Defaults to the name of the current color or you can wrap it around your own icon. | | MobileNav | A fixed mobile wrapper component that can be configured to animate on mount. Triggered by MenuToggle or the useMenu hook. | | ContentWrapper | A wrapper that uses a layout prop to determine the position of its children. This component wraps Main, Sidebar, and SideNav. | | Main | The layout's main content element | | Sidebar | The layout's sidebar component. Can be positioned left or right of Main. | | SideNav | An optional fixed side navigation component. Can be positioned left or right of Main. | | TabBar | A fixed wrapper component that moves mobile navigation to the bottom of the screen like a native mobile app. You can wrap it around your own components or feed it a menu object. The TabBar formats this menu into a horizontal scrollable row with links, labels, and icons. | | Footer | The document footer element | | FooterWidgets | A grid wrapper for building skiplink accessible footer columns |

Usage

To use any of these components, just import them from gatsby-theme-elements:

// basic usage
import { Layout, Header, ContentWrapper, Main, Footer } from 'gatsby-theme-elements`

Unlike other Gatsby themes, you don't need to shadow components because you can edit their behavior from your config files. Detailed information on each component is coming to a documentation site soon.

Hooks

If you prefer to build your own layout components or access theme options from child themes, you can use the following hooks:

• useOptions
• useMenu
• useSideNav
• useMeasurements

useOptions

useOptions returns an object with all of the theme options specified in options.js:

import { useOptions } from "gatsby-theme-elements"

const Component = () => {
  const options = useOptions()

  return...
}

useMenu

useMenu returns an array that lets you view and set the open / close status of the mobile nav

import { useMenu } from "gatsby-theme-elements"

const Component = () => {
  const [menuActive, toggleMenu] = useMenu()

  return...
}

useSideNav

useSideNav returns an array that lets you view and set the open / close status of the side nav. The SideNav's default status changes depending on the viewport width and your mobile breakpoint.

import { useSideNav } from "gatsby-theme-elements"

const Component = () => {
  const [sideNavActive, toggleSideNav] = useSideNav()

  return...
}

useMeasurements

useMeasurements returns an object with all of Element's key measurements:

• topbarHeight
• headerHeight
• sideNavWidth
• sidebarWidth
• viewportX (updates on resize)
• viewportY (updates on resize)

This might come in handy if you need to access screen dimensions or layout positions.

import { useMeasurements } from "gatsby-theme-elements"

const Component = () => {
  const metrics = useMeasurements()

  return...
}

License

The MIT License (MIT)

Created by Mike Darche