Rebass MDX
⚛️#️⃣ MDX + Styled System + Emotionnpm 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 atheme
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 additionalstyles
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 themefuture
: theme with Avenir Nextdark
: 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 theStyled
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
TheRebassMDX
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
- `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