---
name: Creating your themes
route: /docs/creating-your-themes
parent: Documentation
menu: Customizing
---

# Creating your themes

One of the main features of Docz is that it allows you to create your own theme from scratch and just use the data parsed from Docz.
We provide a bunch of components that can help you create your own theme with little effort.

Let's assume we have the following project structure :

```
pages/
  hello-world.mdx
src/
  gatsby-theme-docz/
    index.js
  ui/
    Page.js
doczrc.js
package.json
```


The previous way of customizing docz in v0 and v1 was to use the `theme` property inside the `doczrc.js` file. 

With v2, we leverage GatsbyJS theme shadowing to override any and all files of the theme.

For example, to create a new theme wrapper and override some styles, we create a file located at `src/gatsby-theme-docz/index.js` that shadows [gatsby-theme-docz/src/index.js](https://github.com/doczjs/docz/blob/master/core/gatsby-theme-docz/src/index.js) 
and provide a new theme container implementation as shown below.


## Creating your theme component

Create your theme component that takes in `children` as props and export it as default while using the [`theme()`](/docs/components-api) high order component as an enhancer.

```js
// src/gatsby-theme-docz/index.js
import React from 'react'
import { theme } from 'docz'

const Theme = ({ children }) => <div>{children}</div>

export default theme()(Theme)
```

> It's required to "pass down" the `children` property inside your theme component in order to render Docz routes properly.

If you create something like the above example you won't have anything too useful to show.
To customize your documentation make sure to check the [gatsby-docz-theme](https://github.com/doczjs/docz/tree/master/core/gatsby-theme-docz/src) source code
to decide which modules you want to override.

## Default theme configuration

Each theme has its own default `themeConfig` object that allows you to override any part of the default theme found [here](https://github.com/doczjs/docz/blob/master/core/gatsby-theme-docz/src/theme/index.js).

The `themeConfig` allows you to customize fonts, colors, spaces, styles properties and other project global variables.

```js
// src/gatsby-theme-docz/index.js
import React from 'react'
import { theme } from 'docz'

const Theme = ({ children }) => <div>{children}</div>

const themeConfig = {
  colors: {
    primary: 'tomato',
    secondary: 'khaki',
    gray: 'lightslategray',
  },
}

export default theme(themeConfig)(Theme)
```

By default, Docz will use [this object](https://github.com/doczjs/docz/blob/master/core/gatsby-theme-docz/src/theme/index.js) as the default configuration and merge it with the `themeConfig` setting in the project configuration.

You can then use the `useConfig` hook to do a lot of things, like use css-in-js theming or retrieve props from your `themeConfig` in a deep rendered component.

```js
// src/gatsby-theme-docz/index.js
import React from 'react'
import { theme, useConfig } from 'docz'
import { ThemeProvider } from 'theme-ui'

const Theme = () => {
  const config = useConfig()
  return (
    <ThemeProvider theme={config}>
      <div>My theme</div>
    </ThemeProvider>
  )
}

const themeConfig = {
  colors: {
    primary: 'tomato',
    secondary: 'khaki',
    gray: 'lightslategray',
  },
}

export default theme(themeConfig)(Theme)
```

## Providing Components

As explained in the components API section, the `<ComponentsProvider>` is the component responsible for providing components to MDX and Docz to render your markdown files with. 

With these components passed to the provider, you can change how your mdx file will be rendered and alter default behaviors and styles.

```js
// src/gatsby-theme-docz/index.js
import React from 'react'
import { theme, useConfig, ComponentsProvider } from 'docz'
import { ThemeProvider } from 'theme-ui'

import * as components from './ui'

const map = {
  page: components.Page,
  notFound: components.NotFound,
  render: components.Render,
  h1: components.H1,
  h2: components.H2,
  h3: components.H3,
  h4: components.H4,
  h5: components.H5,
  h6: components.H6,
  ul: components.List,
  loading: components.Loading,
  table: components.Table,
  pre: components.Pre,
  inlineCode: components.Code,
}

const Theme = ({ children }) => {
  const config = useConfig()
  return (
    <ThemeProvider theme={config}>
      <ComponentsProvider components={map}>
        {children}
      </ComponentsProvider>
    </ThemeProvider>
  )
}

const themeConfig = {
  colors: {
    primary: 'tomato',
    secondary: 'khaki',
    gray: 'lightslategray',
  },
}

export default theme(themeConfig)(Theme)
```

This is powerful because it pushes you to think about your site as a set of base components 
and to create a default style for each one that will be used in all your documents while keeping your code DRY.

## Getting data from documents

By now you should have a working site. But with the code above you will only see a single page without any link or information about the rest of your documents.

Having a way to navigate your documentation is essential in your documentation site.

Let's create a `Menu` component by using the `useMenus` hook and the `<Link>` component.

The hook will give you information about all the menus' information parsed by Docz 
and the component will provide a way to navigate between them.

An example `Menu` component is shown below : 

```js
// src/Menu.js
import React from 'react'
import { useMenus, Link } from 'docz'

export const Menu = () => {
  const menus = useMenus()
  return (
    <ul>
      {menus.map(menu => (
        <li key={menu.id}>
          <Link to={menu.route}>{menu.name}</Link>
        </li>
      ))}
    </ul>
  )
}
```

This will create a fully functional navigation menu to your documentation and you can then use the `<Menu />` component inside your theme:

```js
// src/gatsby-theme-docz/index.js
import React from 'react'
import { theme, useConfig, ComponentsProvider } from 'docz'
import { ThemeProvider } from 'theme-ui'

import { Menu } from './Menu'
import * as components from './my-components'

const map = {
  page: components.Page,
  notFound: components.NotFound,
  render: components.Render,
  h1: components.H1,
  h2: components.H2,
  h3: components.H3,
  h4: components.H4,
  h5: components.H5,
  h6: components.H6,
  ul: components.List,
  loading: components.Loading,
  table: components.Table,
  pre: components.Pre,
  inlineCode: components.Code,
}

const Theme = ({ children }) => {
  const config = useConfig()
  return (
    <ThemeProvider theme={config}>
      <Menu />
      <ComponentsProvider components={map}>
        {children}
      </ComponentsProvider>
    </ThemeProvider>
  )
}

const themeConfig = {
  colors: {
    primary: 'tomato',
    secondary: 'khaki',
    gray: 'lightslategray',
  },
}

export default theme(themeConfig)(Theme)
```
You can also use this component to create other things like a search component, link to custom pages or whatever else you would like.

## Using documents settings

Another interesting thing that you can do when you're creating your own theme is to use the `componentMap`'s `<Page>` component to customize the document preview depending on each document's settings. 

Each document can have its own settings defined in the header of the `.mdx` file. 

The `Page` component receives a prop called `doc` that contains the settings data. You can use this data to build your own variations of the rendered pages.

For example, suppose that you'd like to add a hero image to some documents and leave others unchanged. 

You could do that by providing a `hero` property to your document, and then if that property is defined you would render a hero, else you would show the document as is.

Your markdown would look something like this : 

```markdown
<!-- 
hello-world.mdx
-->
---
name: Hello world
hero: /my/hero/img.png
---

# Hello world

This is a page!
```

And your `Page` component would look like the following : 

```js
// src/ui/Page.js
import React from 'react'

import MyCoolHero from './MyCoolHero'

export const Page = ({ doc, children }) => (
  <div>
    {doc.hero && <MyCoolHero img={doc.hero} />}
    {children}
  </div>
)
```

Armed with this knowledge, you can create many variations of your documents based on the data provided in your MDX.

## Examples

To see an example of a theme, you can check the [source code](https://github.com/doczjs/docz/tree/master/core/gatsby-theme-docz/src) of `gatsby-theme-docz`.
