gatsby-theme-elements

    1.0.7 • Public • Published

    Elements Logo

    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.

    npm version

    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

    Install

    npm i gatsby-theme-elements

    DownloadsWeekly Downloads

    25

    Version

    1.0.7

    License

    MIT

    Unpacked Size

    62.2 kB

    Total Files

    50

    Last publish

    Collaborators

    • mkdarche