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.jsmodule.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.jsmodule.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
// babel.config.jsmodule.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
In jsconfig.json
or tsconfig.json
(since Next.js 12.0.4):
Edit the page on GitHub{"compilerOptions": {"jsxImportSource": "theme-ui"}}