Components & Hooks API

Note

By default, these components and hooks only work inside a Docz theme, because they rely on a lot of data fetched by docz at build-time.

`<ComponentsProvider>`

Use this provider to pass your components to MDX and they will be used when converting your markdown to html.

import React from 'react'
import { ComponentsProvider, theme } from 'docz'

import MyCoolSidebar from './my-cool-sidebar'
import * as components from './my-component-list'

const map = {
  page: components.Page,
  h1: components.H1,
  h2: components.H2,
  pre: components.Pre,
}

const Theme = theme(({ children }) => (
  <div>
    <MyCoolSidebar />
    <ComponentsProvider components={map}>
      {children}
    </ComponentsProvider>
  </div>
))

Properties

components: ComponentsMap

This map is responsible to render components inside your compiled .mdx

Type Definitions

interface ComponentsMap {
  loading?: CT
  layout?: CT<LayoutProps>
  notFound?: CT<RouteComponentProps<any>>
  playground?: PlaygroundComponent
  h1?: CT<any> | string
  h2?: CT<any> | string
  h3?: CT<any> | string
  h4?: CT<any> | string
  h5?: CT<any> | string
  h6?: CT<any> | string
  span?: CT<any> | string
  a?: CT<any> | string
  ul?: CT<any> | string
  table?: CT<any> | string
  pre?: CT<any> | string
  code?: CT<any> | string
  inlineCode?: CT<any> | string
  [key: string]: any
}

interface ComponentsProviderProps = {
  components: ComponentsMap
}

export const ComponentsProvider: React.FC<ComponentsProviderProps>

`<Playground>`

Used to render your component inside a playground and show an editable version of your code inside it.

Properties

none

Type Definitions

interface PlaygroundProps {
  children: React.ReactNode | () => React.ReactNode | React.ReactNode[]
}

`<Props>`

Component that takes a component and generates a table of properties based on your properties definitions.

markdown

---
name: MyComponent
---

import { Props } from 'docz'
import MyComponent from './MyComponent'

<Props of={MyComponent} />

Descriptions

You can add descriptions for your props by adding a comment on the line above the prop.

Note: Description comments must be in the format /** Description */.

MyComponent.propTypes = {
  /** The description for myProp */
  myProp: PropTypes.string,
}

Properties

of: React.ComponentType<any>

`useComponents`

Hook responsible for accessing the components map passed as a prop to the <ComponentsProvider> of your theme.

import { useComponents } from 'docz'

const App = () => {
  const components = useComponents()
  return /* ... */
}

Params

none

Return

components: ComponentsMap

`useDocs`

Use this hook to get the list of all parsed documents. It can be useful when you want to create something like a menu or a list.

import { useDocs, Link } from 'docz'

const App = () => {
  const docs = useDocs()
  return (
    <MyMenu>
      {docs.map(doc => (
        <Link key={doc.id} to={doc.route}>
          {doc.name}
        </Link>
      ))}
    </MyMenu>
  )
}

Params

none

Return

docs: Docs[]

All documents parsed by docz

Typings Definitions

interface Docs {
  id: string
  filepath: string
  link: string | null
  slug: string
  name: string
  route: string
  menu: string | null
  headings: Heading[]
  [key: string]: any
}

export function useDocs(): Docs[]

`useMenus`

This hook will return the menu built by Docz using your documents. Use this to quickly get your menus or use useDocs if you want the documents ordered in the order of your project configuration.

import { useMenus } from 'docz'

const App = () => {
  const menus = useMenus()
  return /* ... */
}

Params

options: Object
- query: String Use query to filter menu results. The query is matched against the menu headers, not page content.

Return

menus: MenuItem[]

Type Definitions

export interface MenuItem {
  id: string
  name: string
  route?: string
  href?: string
  menu?: MenuItem[]
  order?: number
  parent?: string
}

export function useMenus(opts: UseMenuOpts): MenuItem[]

`useConfig`

Retrieve the project config object passed on your project configuration. By default, Docz merges your themeConfig object with the default theme config of each theme.

import React from 'react'
import { useConfig } from 'docz'

const MyDeepComponentInsideMyTheme = () => {
  const config = useConfig()
  return /* ... */
}

Properties

none

Return

config: Config

Type Definitions

export type ThemeConfig = Record<string, any>
export interface Config {
  title: string
  description: string
  themeConfig: ThemeConfig
  menu: MenuItem[]
  version: string | null
  repository: string | null
  native: boolean
  separator: string
  codeSandbox: boolean
  linkComponent?: React.ComponentType<any>
}

export function useConfig(): Config

`theme()`

If you want to create your custom theme you need to use the theme() function. It's a Higher Order Component that receives a config property as the first parameter and returns a function that receives your theme component as a parameter:

import React from 'react'
import { theme, DocPreview } from 'docz'

const Theme = () => (
  <div>
    <MyCoolestSidebar />
    <DocPreview />
  </div>
)

const themeConfig = {
  /* ... */
}

export default theme(themeConfig)(Theme)

Type Definitions

import { ComponentType, ReactNode } from 'react'

interface ThemeConfig {
  [key: string]: any
}

function theme(config: ThemeConfig): (Component: ComponentType) => ReactNode