Merge pull request #818 from deckchairlabs/custom-cache-docs

docs: added custom CacheProvider guide

Author: jxnblk

package.json

@@ -19,6 +19,7 @@
   "devDependencies": {
     "@babel/cli": "^7.4.4",
     "@babel/core": "^7.4.5",
+    "@babel/helper-validator-identifier": "^7.9.0",
     "@babel/plugin-transform-runtime": "^7.7.6",
     "@babel/preset-env": "^7.4.5",
     "@babel/preset-react": "^7.0.0",

packages/docs/src/pages/guides/custom-cache-provider.mdx

@@ -0,0 +1,74 @@
+---
+title: Custom CacheProvider
+---
+
+# Custom CacheProvider
+
+## Style container
+
+You may come across a situation where you want to inject the generated styles into a
+different element than the current document head (an iframe perhaps).
+
+By using the CacheProvider from `@emotion/core` and `createCache` from `@emotion/cache` you can
+specify the target container element.
+
+```jsx
+import { ThemeProvider } from 'theme-ui'
+import { CacheProvider } from '@emotion/core'
+import createCache from '@emotion/cache'
+
+/**
+ * @see https://emotion.sh/docs/@emotion/cache
+ */
+const cache = createCache({
+  container: document.getElementById('my-cool-iframe'),
+})
+
+const theme = {
+  colors: {
+    text: 'tomato',
+  },
+}
+
+export default ({ children }) => {
+  return (
+    <CacheProvider value={cache}>
+      <ThemeProvider theme={theme}>{children}</ThemeProvider>
+    </CacheProvider>
+  )
+}
+```
+
+### With react-frame-component
+
+```jsx
+import { ThemeProvider } from 'theme-ui'
+import { CacheProvider } from '@emotion/core'
+import createCache from '@emotion/cache'
+import Iframe, { FrameContextConsumer } from 'react-frame-component'
+
+const theme = {
+  colors: {
+    text: 'tomato',
+  },
+}
+
+export default ({ children }) => {
+  return (
+    <Iframe initialContent="IFRAME_CONTENT">
+      <FrameContextConsumer>
+        {frameContext => {
+          const cache = createCache({
+            container: frameContext.document.head,
+          })
+          return (
+            <CacheProvider value={cache}>
+              <ThemeProvider theme={theme}>{children}</ThemeProvider>
+            </CacheProvider>
+          )
+        }}
+      </FrameContextConsumer>
+    </Iframe>
+  )
+}
+```

packages/docs/src/pages/guides/index.mdx

@@ -28,6 +28,8 @@ import { Cards } from '../..'
   Style content responsively
 - [Nested ThemeProviders](/guides/nested-theme-providers)
   Add contextual theme and stylistic changes
+- [Custom CacheProvider](/guides/custom-cache-provider)
+  Customise the styles generated and where they are injected
 - [Syntax Highlighting](/guides/syntax-highlighting)
   Add syntax highlighting to MDX code blocks
 - [Theme Color Meta Tag](/guides/theme-color-meta-tag)

packages/docs/src/sidebar.mdx

@@ -72,6 +72,7 @@
   - [MDX Layout Components](/guides/mdx-layout-components)
   - [Responsive Typography](/guides/responsive-typography)
   - [Nested ThemeProviders](/guides/nested-theme-providers)
+  - [Custom CacheProvider](/guides/custom-cache-provider)
   - [Syntax Highlighting](/guides/syntax-highlighting)
   - [Theme Color Meta Tag](/guides/theme-color-meta-tag)
   - [Color Mode Toggles](/guides/color-mode-toggles)