Getting Started

To begin using Maker UI, install the library from npm:

npm i maker-ui
# or
yarn add maker-ui

The core library includes layout components as well as basic primitives and a JSX runtime that you can use to build your page designs.

If you just want to use primitives without the layout system, you can import @maker-ui/primitives

Create a Basic Layout#

In a new file, create a layout component that will wrap your application:

import * as React from 'react'
import {
  Layout,
  Header,
  Navbar,
  MobileMenu,
  Content,
  Main,
  Footer,
} from 'maker-ui'

export const MyLayout = ({ children }) => {
  return (
    <Layout>
      <Header>
        <Navbar />
        <MobileMenu />
      </Header>
      <Content>
        <Main>{children}</Main>
      </Content>
      <Footer>Footer Copyright</Footer>
    </Layout>
  )
}

The JSX from above outputs a semantically structured DOM tree. This example creates a single-column page layout that supports mobile navigation right out of the box.

With the Layout API, you can quickly create layout skeletons for sidebars, collapsible side navigation, and much more.

Customize Maker UI Options#

You can tell your app layout how to look and feel on desktop and mobile by supplying a MakerUIOptions configuration object:

import * as React from 'react'
import {
  Layout,
  Header,
  Navbar,
  MobileMenu,
  Content,
  Main,
  Footer,
  MakerUIOptions, // For TypeScript users
} from 'maker-ui'

const options: MakerUIOptions = {
  header: {
    breakpoint: 1080,
    maxWidth: 960,
    navType: 'center',
    mobileNavType: 'basic',
    sticky: true,
    stickyOnMobile: false,
  },
}

export const MyLayout = ({ children }) => {
  return (
    <Layout options={options}>
      <Header>
        <Navbar />
        <MobileMenu />
      </Header>
      <Content>
        <Main>{children}</Main>
      </Content>
      <Footer>Footer Copyright</Footer>
    </Layout>
  )
}

Starting on Line 13, we create a new MakerUIOptions object and add a few settings for the header.

On Lines 15 and 16, we tell our header to switch from desktop mode to its mobile layout at 1080px. The inner contents of our navbar should never exceed a max-width of 960px.

On Lines 17 and 18, we choose from 12 pre-built CSS grid layouts to dictate how our nav will look on desktop and mobile. We can always customize the exact behavior of these layouts later on.

Lastly, on Lines 19 and 20, we specify that we want our header to use sticky positioning on desktop and a relative position on mobile.

With the options configuration object, you can control 50+ settings that tell your layout how to behave. Use MakerUIOptions to set color modes, handle error boundaries, configure dropdown menus, and much more.

For a complete list of layout settings, check out the Maker UI Options guide.

Now we can import a custom Logo component and create our header navigation menu.

import * as React from 'react'
import {
  Layout,
  Header,
  Navbar,
  MobileMenu,
  Content,
  Main,
  Footer,
  MakerUIOptions,
  MakerMenu, // For TypeScript users
} from 'maker-ui'

// Your custom logo component
import { Logo } from './Logo'

const options: MakerUIOptions = {
  header: {
    breakpoint: 1080,
    maxWidth: 960,
    navType: 'center',
    mobileNavType: 'basic',
    sticky: true,
    stickyOnMobile: false,
  },
}

// An array of menu items
const menu: MakerMenu = [
  { label: 'Home', path: '/' },
  { label: 'About', path: '/about' },
  { label: 'Contact', path: '/contact' },
  { label: 'GitHub', path: 'https://github.com', newTab: true },
]

export const MyLayout = ({ children }) => {
  return (
    <Layout options={options}>
      <Header>
        <Navbar logo={<Logo />} menu={menu} />
        <MobileMenu menu={menu} />
      </Header>
      <Content>
        <Main>{children}</Main>
      </Content>
      <Footer>Footer Copyright</Footer>
    </Layout>
  )
}

Maker UI will add your custom logo to the navbar and create accessible desktop and mobile menus for you.

The MakerMenu type is used by all Maker UI components that handle navigation menus. It supports a variety of common conventions including nested submenus, custom class selectors, new tab support, and leading icons.

Add Custom Styles#

It's time to add some styles to our responsive layout skeleton.

All Maker UI layout components accept the css prop (covered here). However, adding too many styles directly to the layout tree can quickly turn our file into a mess of CSS-in-JS.

To address this, Maker UI's root <Layout> component accepts a styles prop where we can add global style that are applied to the entire document, just like a regular CSS stylesheet.

The styles prop fully supports responsive arrays. This is a great place for:

CSS resets
Global or default CSS rules
Shared or utility class styles
Layout component styles via ID or class selector

By default, the styles prop uses the breakpoints that you specify in MakerUIOptions when it parses any array-based CSS rules.

import * as React from 'react'
import {
  Layout,
  Header,
  Navbar,
  MobileMenu,
  Content,
  Main,
  Footer,
  MakerUIOptions,
  MakerMenu,
} from 'maker-ui'

...

const styles = {
  a: {
    textDecoration: 'none',
  },
  header: {
    padding: [15, '10px 30px'],
    borderBottom: '1px solid',
  },
  footer: {
    display: 'grid',
    gridTemplateColumns: ['1fr', 'repeat(4, 1fr)'],
    gap: 30,
  }
}

export const MyLayout = ({ children }) => {
  return (
    <Layout options={options} styles={styles}>
      <Header>
        <Navbar logo={<Logo />} menu={menu} />
        <MobileMenu menu={menu} />
      </Header>
      <Content>
        <Main>{children}</Main>
      </Content>
      <Footer>
        Footer Copyright
      </Footer>
    </Layout>
  )
}

In this example, we add a global textDecoration rule to all anchor tags while also applying custom styles to Maker UI's header and footer components.

The easiest way to target a Maker UI layout component (without reading the Layout API docs, of course) is to open DevTools and identify the proper ID or class selector for the job.

Use Inside a Root Provider#

When your new layout is ready to go, import it into your app's root component and treat it like a top-level application provider.

You can use your router's current location to trigger conditional layouts and you can dynamically change the MakerUIOptions or styles as needed.

import * as React from 'react'
import * as ReactDOM from 'react-dom'

import { MyLayout } from './MyLayout'

const element = <MyLayout />
ReactDOM.render(element, document.getElementById('root'))

Best Practices#

In a real application, you would store your options, styles, and menu objects in separate files or even generate them dynamically via network requests at build or runtime.

See Best Practices for a complete list of helpful tips and common issues.

Contents

Getting Started

Create a Basic Layout#

Customize Maker UI Options#

Add a Logo and Menu#

Add Custom Styles#

Use Inside a Root Provider#

Best Practices#