Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including @rebass/mdx with all npm packages installed. Try it out:

var mdx = require("@rebass/mdx")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@rebass/mdx v2.0.0

MDX Provider for styled components

Rebass MDX

⚛️#️⃣ MDX + Styled System + Emotion

npm i @rebass/mdx

Wrap your application with the RebassMDX provider component. All child MDX documents will receive component and theming context from this provider.

import React from 'react'
import RebassMDX from '@rebass/mdx'
import Document from './document.mdx

export default props =>
  <RebassMDX>
    <Document />
  </RebassMDX>

Theming

Pass a theme object to the RebassMDX provider component to add an Emotion theming context. The theme is a Styled System Theme that can be used to apply consistent colors and typography across an entire app.

// example theme
export default {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#07c',
  },
  fonts: {
    body: 'system-ui, sans-serif',
    heading: 'inherit',
    monospace: 'Menlo, monospace',
  },
}

Styles

An additional styles object can be added to the theme object to apply styles to MDX elements.

// example theme styles
export default {
  colors: {
    primary: 'tomato',
  },
  styles: {
    h1: {
      color: 'primary',
    }
  },
}

The styles object uses @styled-system/css so that core Styled System props can be mixed with CSS syntax.

// example theme styles
export default {
  colors: {
    primary: 'tomato',
  },
  styles: {
    h1: {
      // using Styled System props
      fontSize: [ 4, 5 ],
      fontFamily: 'heading',
      color: 'primary',
      // alongside other CSS
      textTransform: 'uppercase',
      letterSpacing: '0.2em',
    }
  }
}

Built-in Themes

Rebass MDX includes a handful of built-in themes that can be used out-of-the-box or as a basis for extending into a custom theme.

import React from 'react'
import { RebassMDX } from '@rebass/mdx'
import themes from '@rebass/mdx/themes'

export default props =>
  <RebassMDX theme={themes.base}>
    {props.children}
  </RebassMDX>
  • base: the default theme
  • future: theme with Avenir Next
  • dark: dark mode theme

Custom Components

Custom MDX components can be added to context. This can be useful for adding syntax highlighting, live code editors, or linked headings.

import React from 'react'
import { RebassMDX } from '@rebass/mdx'
import Link from './Link'

export default props =>
  <RebassMDX
    components={{
      a: Link,
    }}>
  </RebassMDX>

Any component can be added to context to apply theming with the RebassMDX provider. These components can be rendered with the Styled component.

Styled Components

For usage outside of an MDX file, use the Styled component to render styled components anywhere in your app. These components can be styled using the theme and the theme.styles object.

import React from 'react'
import { Styled } from '@rebass/mdx'

export default props =>
  <Styled.wrapper>
    <Styled.h1>
      Hello
    </Styled.h1>
  </Styled.wrapper>

For custom components, use the tag prop.

import React from 'react'
import { Styled } from '@rebass/mdx'

export default props =>
  <Styled.wrapper>
    <Styled tag='CustomComponent'>
      Hello
    </Styled>
  </Styled.wrapper>

useComponents Hook

Alternatively, Rebass MDX components can be accessed by using the useComponents hook.

import React from 'react'
import { useComponents } from '@rebass/mdx'

export default props => {
  const Styled = useComponents()

  return (
    <Styled.h1>
      Hello
    </Styled.h1>
  )
}

Nesting Providers

The RebassMDX component can be nested to change styles contextually. This can be useful for styling sections of a page differently where needed.

// example root-level provider
import React from 'react'
import RebassMDX from '@rebass/mdx'

export default props =>
  <RebassMDX>
    {props.children}
  </RebassMDX>
// example nested provider for style overrides
import React from 'react'
import RebassMDX, { Styled } from '@rebass/mdx'

export default props =>
  <RebassMDX
    theme={{
      styles: {
        h1: {
          fontSize: 3,
        }
      }
    }}>
    <Styled.h1>Hello</Styled.h1>
  </RebassMDX>

API

  • RebassMDX: core provider component
    • props:
      • theme add a custom Styled System Theme
        • theme.styles override component styles
      • components override specific components or add custom components to code fence examples
  • Styled
  • useComponents

MIT License

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free