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 the Babel plugin 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.