JSX Pragma

Theme UI uses custom JSX functions and JSX import source comments to allow you to style elements with values from your theme using the sx prop.

What is JSX

JSX is an XML-like syntax extension to JavaScript. It's a syntax sugar usually used for React's jsx function. You don't need to write JSX to use React, but it's meant to make code more readable, especially for tree structures with attributes.

Given the following JSX:

// example JSX
<div>
  <Button onClick={handleClick}>Hello</Button>
</div>

The above JSX syntax compiles to the following:

import { jsx } from 'react/jsx-runtime'

jsx('div', {
  children: jsx(Button, {
    onClick: handleClick,
    children: 'Hello',
  }),
})

Most apps use Babel to compile JSX syntax for use with React or other similar libraries. JSX can be compiled to any function call. By default the Babel plugin will convert JSX into calls to the jsx function imported from react/jsx-runtime, but libraries like Preact, MDX, Emotion, and Vuejs use custom functions to create elements with JSX.

Technically Babel also calls jsxs from react/jsx-runtime and jsxDEV from react/jsx-dev-runtime in some cases, but the concept still holds.

To change the underlying create element functions, you can either add an option to the Babel plugin or you can set a pragma comment at the beginning of a module. Changing the function import source in Babel config will transform all JSX in an application into the same set of functions. Using a pragma comment limits the change to only the modules that it's added to. This lets you default to the React jsx function in most places and use custom functions only where you need it, giving the author more control over where it's used.

Theme UI uses custom create element functions to add the sx and css props in React. The preferred way of using these functions is by adding the custom pragma comment to the top of your file.

/** @jsxImportSource theme-ui */

See the sx prop docs to learn more.

Automatic JSX runtime

React v17 introduced a new JSX transform, also called "automatic runtime" (backported to React v16.14.0) If you use any of those versions together with a configurable transpiler (such as Babel or TypeScript), you can configure JSX to use the automatic runtime (globally, for your entire app), and no longer need to use the custom pragma comments in your files to use sx.

Here are a few examples showing how to do that depending how you build your application:

Using @babel/preset-react

// babel.config.js
module.exports = {
  presets: [
    [
      '@babel/preset-react',
      {
        importSource: 'theme-ui', // or '@theme-ui/core'
        runtime: 'automatic',
        throwIfNamespace: false,
      },
    ],
  ],
  // ...
}

NOTE: this requires babel >= 7.9.0

Using @babel/plugin-transform-react-jsx

This plugin is included in the preset above, but can also used as a standalone babel plugin.

// babel.config.js
module.exports = {
  presets: [
    [
      '@babel/plugin-transform-react-jsx',
      {
        importSource: 'theme-ui', // or '@theme-ui/core'
        runtime: 'automatic',
        throwIfNamespace: false,
      },
    ],
  ],
  // ...
}

NOTE: this requires babel >= 7.9.0

Using TypeScript

If you use TypeScript to transpile your source code with tsc (or only typecheck), or for instance to run tests with ts-jest

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "theme-ui"
  }
  // ...
}

NOTE: this requires TypeScript >= 4.1

Using Next.js

With Babel

module.exports = {
  presets: [
    [
      'next/babel',
      {
        'preset-react': {
          importSource: 'theme-ui', // or '@theme-ui/core'
          runtime: 'automatic',
          throwIfNamespace: false,
        },
      },
    ],
  ],
  // ...
}

You can read more about customizing Babel config in Next.js docs.

With SWC

Next.js is gradually migrating to SWC, and recommends using it for all new projects.

In jsconfig.json or tsconfig.json (since Next.js 12.0.4):

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "theme-ui" // or "@theme-ui/core"
    // ... the rest of your compilerOptions redacted for brevity
  }
}

Using Vite

Vite transpiles JSX using esbuild. Per Vite documentation, configure the pragma project-wide like this:

import { defineConfig } from 'vite'

export default defineConfig({
  esbuild: {
    jsxFactory: 'jsx',
    jsxInject: `import { jsx } from 'theme-ui'`,
  },
})

esbuild will use theme-ui’s jsx for every component by programatically injecting import { jsx } from 'theme-ui' to the start of every JSX file.