Full JSX email documentation as Markdown.
# Introduction
> Build and send emails using React and TypeScript.
JSX email provides a set of React components and helpers for building delightful and responsive email templates, compatible with modern email clients. Our components handle the heavy lifting of compatibility and client inconsistency so designers and developers can focus on building impactful and engaging templates.
## Getting Started
Everything to know about the components, props, and usage is available within our [Documentation Site](https://jsx.email/docs/introduction). Please give that a read and let us know if there’s anything we can help with.
## Components
A list of available components can be found on the [`jsx-email` Documentation](https://jsx.email/docs/introduction)
## Featured Features
The goals of this project are to provide an improved focus on Developer Experience, maintenance, fast improvements and fast releases. And there are number of key features that make JSX email what it is:
* [Email Client Compatibility Checking](https://jsx.email/docs/core/cli#client-compatibility-check)
* Exclusive Components
* Handles cross-client inconsistencies for you
* Optional Configuration Files
* Plugins
* Crazy fast Tailwind support
* Support for `` and `async` within Components
* Enhanced Developer Experience (DX)
* Wonderful Command Line tools
* Works with Monorepos out of the box. No exhaustive setup needed.
* A smooth and simple Preview Server
* Fast improvements, feature development, and releases
* Community-driven, not Company-driven
* No vendor lock-in for tools. `jsx-email` uses only generic components and tools
## Service Integrations
This includes [AWS SES](https://aws.amazon.com/ses), [Loops](https://loops.so), [Nodemailer](https://nodemailer.com), [Postmark](https://postmarkapp.com),[Resend](https://resend.com), [Plunk](https://www.useplunk.com/), and [SendGrid](https://sendgrid.com). See our documentation on [Email Providers](https://jsx.email/docs/email-providers) for more info and example usage.
## Migrating to Version 3
See the [v3 migration guide](/docs/v3/migration) for a full list of breaking changes and important information about updating to v3.0.0.
To browse the source code and documentation markdown for v2.8.4 please [click here](https://github.com/shellscape/jsx-email/tree/jsx-email-v2.8.4).
## Contributing, Working With This Repo
[](https://liberamanifesto.com)
We 💛 contributions! After all, this is a community-driven project. We have no corporate sponsorship or backing. The maintainers and users keep this project going! Please check out our [Contribution Guide](./CONTRIBUTING.md). JSX email is [MIT Licensed](./LICENSE.md)
We (the maintainers) use JSX email daily.
---
# Quick Start
> Quick Start
## Quick Start
In this doc you’ll find information on quickly getting started using JSX email. For more in-depth information, please see the other sections of our Documentation.
Info
This guide, along with the rest of the documentation here, assume that the reader has fundamental Node and NPM skills and is familiar with using command line tools on Window, Linux, or Mac OS.
For those not familiar with the bits above, here are some links to resources that we’d recommend reading before working with this project:
* [Node Fundamentals](https://www.codecademy.com/learn/learn-nodejs-fundamentals/modules/intro-to-node-js/cheatsheet)
* [NPM Fundamentals](https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/)
* [Executing Local NPM Packages](https://jaireina.medium.com/executing-local-npm-packages-226820ad2c31)
* [`npx`](https://docs.npmjs.com/cli/v8/commands/npx) and [`pnpm exec`](https://pnpm.io/cli/exec)
* [How to use relative paths on windows CMD?](https://superuser.com/a/1270599)
## Prerequisites
* [Node.js](https://nodejs.org/en/) [LTS Version](https://github.com/nodejs/Release) v22.0.0+
* React v19.1.0+
## New Projects
If you’re starting a new project — whether that’s a project solely for email templates, or a project that will eventually host additional code — our [`create-mail`](https://github.com/shellscape/jsx-email/tree/main/packages/create-mail) utility is a perfect choice, and the fastest way to get started. The utility will scaffold a new project and get everything ready for developing new email templates. To begin, make sure you have a terminal (or command line) open and your current working directory is the directory you’d like to create a new project. Run the following command in your terminal (without the `$` symbol):
```
$ npx create-mail my-email-project
```
This command will install and execute `create-mail`, create a `my-email-project` directory, and add a starter template.
While the *Existing Projects* section below can be safely skipped, the information beneath it is useful and worth giving a read before working with JSX email, as it contains information on the project and template that was just created.
## Existing Projects
The happy path for adding JSX email to an existing project is by using the JSX email CLI:
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
If you want to avoid global installation, you can use `pnpm dlx`, `npx`, or `yarn` instead like so:
```
$ pnpm dlx email
```
## Create A Template
First, we’ll create a directory for our email templates, and then add a new template:
```
$ mkdir ./emails
$ email create BatmanEmail --out=./emails
```
This command will create a new template named `BatmanEmail.tsx` in the `./emails` directory.
Tips
If you’d rather create a `.jsx` file, use the `--jsx` flag
## Email Previews
One of the major benefits of JSX email over alternatives is our incredibly slim and fast preview server, which requires no additional dependency installation, complex mounting, or difficult setup rules for monorepos. To run the preview server, run the following command in your terminal:
```
# MacOS and Linux
$ email preview ./emails
```
Info
Windows paths are different than MacOS or Linux paths. `./emails` above will not work on Windows. Please see the link above regarding Windows relative paths if you are unfamiliar with how they work on the Command Line
The CLI will startup a preview server and open a new browser tab at `http://localhost:55420`. It’s that simple.
Tips
Please use `email help preview` to view optional flags, including setting the port.
## Building Your Template
The next step is to build your template. This can be done with the CLI, or with the [`render` method](/docs/core/render) in code. While most people will need to render emails dynamically at runtime using `render`, the CLI is capable of rendering both static and dynamic emails that take props as input. To build your email into an HTML document, run:
```
$ email build ./emails/BatmanEmail.tsx
```
Tips
Please use `email help build` to view optional flags, including providing props and setting the output path.
---
# CLI
> The Command Line Interface and developer tooling for JSX email
The Command Line Interface and developer tooling for JSX email
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
Nearly all installations of this package will want it installed into `devDependencies` so please make sure to add the `-D` flag.
## Usage
Installing this package will add an `email` binary, which will be available to `pnpm exec`, `npx`, and `yarn`.
Invoking the CLI without parameters or flags will produce help information in the console. From there, all of the functions of the CLI can be viewed, along with any applicable parameters and flags:
```
→ pnpm exec email
jsx-email v0.0.0
A CLI for working with Email Templates made with jsx-email
Usage
$ email [...options]
Commands
build
check
create
help []
preview
Options
--help Displays this message
--version Displays the current jsx-email version
Examples
$ email
$ email --help
$ email build ./src/templates/Invite.tsx
$ email create invite
$ email preview ./src/templates
```
## Build
Tips
To view info, flags, and options for the `build` command, run `email help build`.
The `build` command compiles and renders an email template to HTML for use with an email provider. The command takes a directory or single file as input:
```
$ cd ~/code/email-app
$ email build ./emails
```
Or for a single file:
```
$ cd ~/code/email-app
$ email build ./emails/Batman.tsx
```
To render using the sample props you export from a template file, pass the `--use-preview-props` flag. When set, `email build` will use the `previewProps` export (if present) instead of `--props`.
## Check
Tips
To view info, flags, and options for the `check` command, run `email help check`.
`jsx-email` can run a client compatibility check on any template, comparing it to the compatibility tables from \`[caniuse.com](https://caniemail.com/) and display any email client incompatibility issues. This check is incredibly helpful in diagnosing and debugging display issues between multiple email clients.
```
$ email check ./emails/Batman.tsx
```
To check templates using their exported `previewProps`, pass the `--use-preview-props` flag so the check runs against the same sample data as your previews and builds.
To limit compatibility checks to specific email clients, pass `--email-clients` with a comma-separated list of caniemail client names or globs:
```
$ email check ./emails/Batman.tsx --email-clients gmail.*,outlook.*
```
Default check clients can also be configured in `jsx-email.config.*` with `check.emailClients`. The CLI flag takes precedence over config when both are present.
Example output:
```
Checking email template for Client Compatibility...
Found 1 files:
./emails/Batman.tsx
Starting build...
Build complete
./emails/Batman.tsx
error Class selector is not supported by:
gmail.mobile-webmail
protonmail.desktop-webmail
protonmail.ios
error border-radius is not supported by:
outlook.windows
outlook.windows-mail
...
warn target attribute is only partially supported by:
apple-mail.macos
apple-mail.ios
outlook.windows
outlook.windows-mail
outlook.ios
outlook.android
Check Complete: 14 error(s), 20 warning(s)
```
## Preview
Tips
To view info, flags, and options for the `preview` command, run `email help preview`.
JSX email ships with a Preview Tool as part of the CLI. Our Preview is fast, simple, and smooth. It doesn’t require installing any crazy dependencies, downloading additional “clients,” or copying your project’s dependencies. It just works. And the best part: it works with monorepos out of the box.
The preview also supports static local assets. For a good example of how to handle local assets like images, please have a look at [the samples AirBnB template](https://github.com/shellscape/jsx-email/blob/main/apps/samples/emails/airbnb-review.tsx). Notice that `baseUrl` is set using a condition on `import.meta.isJsxEmailPreview`. That `import.meta` property is specific to `jsx-email` and will be replaced appropriately at build time. Local assets are served from the templates root directory, in this case `apps/samples/emails`, at the server root. So a `apps/samples/emails/batman.png` file would be served at `/batman.png` in the browser. We recommend using a `static` or `assets` directory in your templates root directory, so it’s clear where files are being served from when viewing in the Preview Tool.
To use the Preview Tool, open your terminal and navigate to your project. We’re assuming you’ve already installed the CLI as shown above, and that you’ve already run `email create` to create an email in an `emails` directory.
```
$ cd ~/code/email-app
$ email preview ./emails
```
The Preview Tool will start up and open a new window in your browser, and you’ll be presented with a page that looks like:
\
\
\
\
\
\
## Deploying Your Preview App
As part of the CLI, users have the ability to build their templates into a deployable preview app. The resulting app can be deployed anywhere, not just select service providers. To build templates into a deployable app, run:
```
$ email preview --build-path
```
where `` is the path you want the build output files placed.
---
# Compile
> Compile jsx-email templates into a bundle
Compile jsx-email templates into a bundle
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
## Usage
```
import { readFile } from 'node:fs/promises;';
import { resolve } from 'node:path';
import { compile } from 'jsx-email/compile';
const templatePath = resolve(__dirname, './emails/Batman');
const outDir = resolve(__dirname, '.compiled');
const compiledFiles = await compile({ files: [templatePath], hashFiles: false, outDir });
```
Tips
Once compiled into a bundle, the file can be imported and passed to render such like:
```
import { render } from 'jsx-email';
import { Template } from './.compiled/batman.js';
const html = render();
```
Note that whether or not to use a file extension in the import depends on your project’s settings. When using TypeScript you may have to adjust types to avoid errors, using this method.
## Method Options
```
export interface Options {
disableDefaultStyle?: boolean;
inlineCss?: boolean;
minify?: boolean;
plainText?: boolean | PlainTextOptions;
pretty?: boolean;
}
```
### Options
```
files: string[];
```
An array of absolute paths for JSX/TSX template files to compile
```
hashFiles?: boolean;
```
Default: true. If `true`, adds the build hash to compiled file names. Set this to `false` if hashing and unique output filenames aren’t needed.
```
outDir: string;
```
An absolute path to output the compiled file(s)
```
writeMeta?: boolean;
```
If `true`, writes the ESBuild metadata for the compiled file(s)
---
# Configuration
> Configuration
## Configuring jsx-email
When running `email` from the command line or programmatically using the [`render`](/docs/core/render) function, jsx-email will attempt to find and use a `jsx-email.config` file. jsx-email will traverse a directory structure looking for config files until it reaches a git repository root directory, or the OS’s home directory. This is quite fast, and allows for scoping your configuration file at the filesystem level you’d like to. By default, jsx-email looks for configuration files with the following file extensions and locations:
```
.config/jsx-emailrc.js
.config/jsx-emailrc.cjs
.config/jsx-emailrc.mjs
.config/jsx-email.config.js
.config/jsx-email.config.cjs
.config/jsx-email.config.mjs
.jsx-emailrc.js
.jsx-emailrc.cjs
.jsx-emailrc.mjs
jsx-email.config.js
jsx-email.config.cjs
jsx-email.config.mjs
```
Info
jsx-email does not currently support TypeScript, YAML, or JSON files.
### Config File
The most basic configuration file might look like this:
```
import { defineConfig } from 'jsx-email/config';
export const config = defineConfig({
render: { minify: true }
});
```
The named export `config` is required regardless of how the file is constructed. Note the use of the `defineConfig` import and the `config` named export - while any plain object will be accepted and parsed, the use of `defineConfig` is encouraged for ensuring your config is compliant.
### Intellisense
Since jsx-email ships with TypeScript typings, you can leverage your IDE’s intellisense with jsdoc type hints:
```
/** @type {import('jsx-email/config').JsxEmailConfig} */
export const config = { ... };
```
### Async Configuration
The `config` export inherently supports `Promise`. This is helpful when needing to perform other async operations before returning a value to the export. This can be done in a few ways:
```
export const config = (async () => { ... })();
```
Or
```
export const config = new Promise((resolve, reject) => { ... })
```
Alternatively, when using the `defineConfig` function, an async function may be passed to it as the first argument:
```
export const config = defineConfig(async () => {
const data = await asyncFunction()
return {
...
}
});
```
### Available Properties
jsx-email configuration files support the following properties:
```
check?: {
emailClients?: string[]
}
```
*Optional*. Allows the configuration file to specify the default email clients used by the CLI’s `check` command.
```
import { defineConfig } from 'jsx-email/config';
export const config = defineConfig({
check: {
emailClients: ['gmail.*', 'outlook.*']
}
});
```
The `emailClients` values use the same client names and glob patterns supported by [caniemail](https://www.caniemail.com/). Exact clients such as `gmail.desktop-webmail`, provider globs such as `outlook.*`, platform globs such as `*.ios`, and `*` for all clients are supported.
The CLI’s `--email-clients` flag takes precedence over this config value when provided:
```
$ email check ./emails/welcome.tsx --email-clients apple-mail.*,gmail.*
```
```
esbuild?: {
plugins?: Plugin[]
}
```
*Optional*. Default: `undefined`. Allows the configuration file to specify [ESBuild Plugins](https://esbuild.github.io/plugins) to use during the initial transform from JSX/TSX to JavaScript for the `build` and `preview` commands.
Tips
ESBuild plugins are only run when using the CLI’s `build` or `preview` commands. ESBuild, and by extension the `esbuild` configuration option, are not used when using `render` directly in code
```
logLevel?: 'debug' | 'info' | 'warn' | 'error';
```
*Optional*. Default: `info`. The level at which logs for jsx-email will appear in the terminal / console.
```
plugins?: JsxEmailPlugin[];
```
*Optional*. An array of plugins; objects which contain a valid [`JsxEmailPlugin` definition](/docs/core/plugins).
```
render?: RenderOptions;
```
*Optional*. The value specified will be merged with the [`render` function options](https://jsx.email/docs/core/render#method-options) when a render takes place. Please see the [`render` documentation](https://jsx.email/docs/core/render#method-options) for more details.
---
# Plugins
> Plugins
## Plugins
`jsx-email` supports plugins to modify the rendering pipeline according to need. A plugin might provide custom minifcation after rendering, or replace tokens in a template before rendering, for example. For implementation examples, please see the Core Plugins below.
### Core Plugins
By default, `jsx-email` ships with `peerDependencies` on several plugins:
* [plugin-inline](/docs/plugins/inline)
* [plugin-minify](/docs/plugins/minify)
* [plugin-pretty](/docs/plugins/pretty)
### Authoring Plugins
Plugins are extremely flexible in how they’re provided to `jsx-email`. They can be the result of a local function, a file export, or a package export. Regardless of how a plugin is provided, all plugins are defined by a straightforward interface:
```
export interface JsxEmailPlugin {
afterRender?: RenderHookFn;
beforeRender?: RenderHookFn;
name: string;
process?: ProcessHookFn;
symbol: typeof pluginSymbol;
}
```
To instruct a render to use plugins, utilize a [Configuration File](/docs/core/config) and specify the `plugins` property:
```
import { defineConfig } from 'jsx-email/config';
import { somePlugin } from './plugins/some-plugin';
export const config = defineConfig({
plugins: [somePlugin]
});
```
### Lifecycle Hooks
Plugins can affect a template at several different stages throughout the rendering process. The following hooks are supported, and are executed in the following order:
* `afterRender`
* `process`
* `beforeRender`
Implemented hooks within plugins can be synchronous or asynchrounous and return a `Promise`. All hooks are exexcuted *after* JSX is converted to HTML.
Function definitions for both `afterRender` and `beforeRender` should match:
```
(params: RenderHookParams) => string | Promise;
```
The `params` argument provided to these two hooks match the following definition:
```
interface RenderHookParams {
chalk: typeof chalk;
html: string;
log: any;
}
```
As a convenience, all hooks are provided a `chalk` instance and a `log` utility for providing user feedback in the console.
#### `afterRender`
As the name suggests, this hook is run after the other hooks and after `render` is considered to be complete, but before the resulting HTML is written to disk.
#### `beforeRender`
This hook is run just before the HTML processing step is begun. It can be handy for replacing tokens in the HTML that may have an effect in the processing step or `afterRender` hooks.
#### `process`
The `process` hook is unique in that the return result from the hook function should return a [`rehype` Plugin](https://unifiedjs.com/learn/guide/create-a-rehype-plugin/). `jsx-email` uses [`rehype`](https://github.com/rehypejs/rehype) for compliant and *fast* HTML processing and modification. The [`plugin-minify` Core Plugin](https://github.com/shellscape/jsx-email/blob/main/packages/plugin-minify) provides an example of such a `rehype` plugin. This hook runs between `beforeRender` and `afterRender`. The function definition for this hook should match:
```
interface ProcessHookParams {
chalk: typeof chalk;
log: any;
}
(params: ProcessHookParams) =>
RehypePlugin | RehypePreset | Promise | Promise;
```
---
# Render
> Render JSX email components to HTML email
Render JSX email components to HTML email
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
Peer Dependencies
`@jsx-email/plugin-inline`, `@jsx-email/plugin-minify`, and `@jsx-email/plugin-pretty` are peer dependencies of `jsx-email`. Package managers that automatically install peer dependencies will install them for you. If you disable peer dependency auto-installation, install the plugin packages manually before using `inlineCss`, `minify`, or `pretty`.
## Usage
```
import { render } from 'jsx-email';
import { Template } from './emails/Batman';
const html = await render();
```
## Method Options
```
export interface Options {
disableDefaultStyle?: boolean;
inlineCss?: boolean;
minify?: boolean;
plainText?: boolean | PlainTextOptions;
pretty?: boolean;
}
```
### Options
```
disableDefaultStyle?: boolean;
```
If `true`, disables all of the default styles for all components for the rendering operation.
```
inlineCss?: boolean;
```
If `true`, converts any elements with CSS class names to use style attributes with the combined CSS styles from the class names on the element. This option loads the [`plugin-inline`](https://github.com/shellscape/jsx-email/blob/main/packages/plugin-inline) plugin.
```
minify?: boolean;
```
If `true`, minifies the HTML for rendered templates. This option loads the [`plugin-minify`](https://github.com/shellscape/jsx-email/blob/main/packages/plugin-minify) plugin.
```
plainText?: boolean | PlainTextOptions;
```
If `true` or an `object`, renders the target email(s) to plain text. If you need to modify how the target is rendered to plain text, an `object` representing [`html-to-text` options](https://github.com/html-to-text/node-html-to-text/blob/master/packages/html-to-text/README.md#options) should be used.
```
pretty?: boolean;
```
If `true`, beautifies the HTML output for each target email. This option loads the [`plugin-pretty`](https://github.com/shellscape/jsx-email/blob/main/packages/plugin-pretty) plugin.
## Debugging
The rendered HTML can often be difficult to trace or match back to the JSX source template. To make things easier, users can enable a debugging flag which will output jsx-email-specific `data-type` attributes in the HTML. To enable this, set an environment variable like so: `DEBUG=jsx-email:elements`.
Users may also wish to pass the `{ minify: false }` option to the `render` method.
---
# Avatar
> Displays a profile avatar with image and fallback support
Prompt
Displays a profile avatar with image and fallback support
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
## Usage
Use `Avatar` for profile images. If `src` is missing, it renders fallback text.
```
import { Avatar } from 'jsx-email';
const Email = () => {
return (
);
};
```
Fallback-only example:
```
import { Avatar } from 'jsx-email';
const Email = () => {
return ;
};
```
### Image Fallbacks
* Visible fallback text uses this order:
1. trimmed `fallback`
2. derived initials from `name`
3. literal `"?"`
* Non-decorative fallback avatars (`decorative={false}`) use this accessible label order:
1. trimmed `alt`
2. `name`
3. resolved visible fallback text
* Decorative fallback avatars (`decorative={true}`) render with `role="presentation"` and `aria-hidden="true"`.
## Component Props
```
src?: string;
```
Path or URL for the avatar image.
```
alt?: string;
```
Accessible alt text for image avatars. If omitted, the component derives text from `name` or `fallback`.
```
name?: string;
```
A readable label used for alt derivation and fallback initials.
```
fallback?: string;
```
Fallback text used when `src` is not provided.
```
decorative?: boolean;
```
Marks the avatar as decorative. Decorative avatars use presentational accessibility attributes.
```
disableDefaultStyle?: boolean;
```
If `true`, instructs the component *not to add* default `style` properties to the component. This can be useful when attempting to override default styles with `Tailwind` or class names.
```
width?: string | number;
```
Avatar width. Defaults to `40` when no explicit size is provided.
```
height?: string | number;
```
Avatar height. Defaults to `40` when no explicit size is provided.
## Caveats
* Default avatar images use `object-fit: cover` to maintain rounded presentation.
* Some email clients may not fully support `object-fit`, so source images may appear stretched or letterboxed.
* For the most consistent results, provide pre-cropped square images and explicit `width`/`height`.
Tips
This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'img'>`, except `children`.
---
# AvatarGroup
> Displays a group of avatars with optional overlap
Prompt
Displays a group of avatars with optional overlap
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
## Usage
`AvatarGroup` arranges `Avatar` children in a row.
```
import { Avatar, AvatarGroup } from 'jsx-email';
const Email = () => {
return (
);
};
```
Use overlap only when needed:
```
import { Avatar, AvatarGroup } from 'jsx-email';
const Email = () => {
return (
);
};
```
Truncate long groups with a `+N` overflow token:
```
import { Avatar, AvatarGroup } from 'jsx-email';
const Email = () => {
return (
);
};
```
Render in reverse order for right-to-left layouts:
```
import { Avatar, AvatarGroup } from 'jsx-email';
const Email = () => {
return (
);
};
```
## Component Props
```
direction?: 'ltr' | 'rtl';
```
Controls group rendering order. Defaults to `"ltr"`.
```
max?: number;
```
Maximum number of avatars to render before appending an overflow token (for example, `+2`).
```
overlap?: boolean;
```
If `true`, overlaps avatars. Defaults to `false` for compatibility-safe rendering.
```
spacing?: number;
```
Spacing in pixels between avatars. Defaults to `8`.
```
disableDefaultStyle?: boolean;
```
If `true`, instructs the component *not to add* default `style` properties to the component. This can be useful when attempting to override default styles with `Tailwind` or class names.
## Caveats
* `overlap={true}` is an enhanced mode that depends on negative margins and layered stacking. Rendering can vary across older or stricter email clients.
* Keep overlap values conservative and verify output with `email check` before sending.
Tips
This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'table'>`, except `cellPadding` and `cellSpacing`.
---
# Background
> A JSX email component for background images in your Email template
Prompt
A JSX email component for background images in your Email template
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
## Usage
Add the background component to your email template.
```
import { Body, Column, Html, Section } from 'jsx-email';
const Email = () => {
return (
Content goes here
);
};
```
## Component Props
```
interface BackgroundProps extends Omit<
React.ComponentPropsWithoutRef<'td'>,
'height' | 'width' | 'bgcolor'
> {
src: string;
bgColor?: string;
bgRepeat?: 'repeat' | 'no-repeat';
height?: number;
width?: number;
}
```
```
src: string;
```
The path to the image
```
bgColor?: string;
```
The hex code that represents the fallback `background-color` incase the image doesn’t load
```
bgRepeat?: 'repeat' | 'no-repeat';
```
A string that represents the value of `background-repeat`. Default value is `no-repeat`
```
height?: number;
```
The `height` of the container in pixels
```
width?: number;
```
The `width` of the container in pixels
---
# Barcode
> Render email-safe 1D and 2D barcodes as HTML tables
Prompt
Render email-safe 1D and 2D barcodes and QR codes as HTML tables
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
## Usage
```
import { Barcode } from 'jsx-email';
const Email = () => {
return (
);
};
```
## Barcode Types
The component also exports typed wrappers with fixed `type` values:
* `QrCode`
* `AztecCode`
* `DataMatrix`
* `Code128Barcode`
* `Code39Barcode`
* `EanBarcode`
* `UpcBarcode`
```
import {
AztecCode,
Code128Barcode,
Code39Barcode,
DataMatrix,
EanBarcode,
QrCode,
UpcBarcode
} from 'jsx-email';
const Email = () => {
return (
<>
);
};
```
## Props
### TypeScript Interface
```
type BarcodeType = 'qrcode' | 'azteccode' | 'datamatrix' | 'code128' | 'code39' | 'ean13' | 'upca';
type BarcodeEcLevel = 'L' | 'M' | 'Q' | 'H';
type BarcodeProps =
| {
type?: 'qrcode';
text: string;
ecLevel?: BarcodeEcLevel;
fgColor?: string;
bgColor?: string;
cellSize?: number;
quietZone?: boolean;
lossyEnabled?: boolean;
lossyBudget?: number;
}
| {
type: 'azteccode';
text: string;
ecLevel?: BarcodeEcLevel;
fgColor?: string;
bgColor?: string;
cellSize?: number;
quietZone?: boolean;
lossyEnabled?: boolean;
lossyBudget?: number;
}
| {
type: 'datamatrix' | 'code128' | 'code39' | 'ean13' | 'upca';
text: string;
ecLevel?: never;
fgColor?: string;
bgColor?: string;
cellSize?: number;
quietZone?: boolean;
lossyEnabled?: boolean;
lossyBudget?: number;
};
```
### Required Props
#### text
```
text: string;
```
Barcode payload.
### Optional Props
#### type
```
type?: BarcodeType;
```
Barcode symbology. Defaults to `'qrcode'`.
#### ecLevel
```
ecLevel?: 'L' | 'M' | 'Q' | 'H';
```
Error-correction level for `qrcode` and `azteccode` only.
#### fgColor
```
fgColor?: string;
```
Foreground color for dark modules.
#### bgColor
```
bgColor?: string;
```
Background color for light modules.
#### cellSize
```
cellSize?: number;
```
Size in pixels for each rendered module.
#### quietZone
```
quietZone?: boolean;
```
Adds a 4-module border when `true`.
#### lossyEnabled
```
lossyEnabled?: boolean;
```
Enables optional lossy compression.
#### lossyBudget
```
lossyBudget?: number;
```
Compression budget between `0` and `1` (clamped at runtime).
### Additional Props
`Barcode` expresses common React props for `ComponentProps<'table'>`.
---
# Body
> A JSX email component for using a React `Body` component to wrap email content
Prompt
A JSX email component for using a React `Body` component to wrap email content
pnpm
aube
bun
npm
yarn
```
pnpm add jsx-email
```
```
aube add jsx-email
```
```
bun add jsx-email
```
```
npm add jsx-email
```
```
yarn add jsx-email
```
## Usage
Add the component to your email template. Include styles where needed.
```
import { Body, Column, Html, Section } from 'jsx-email';
const Email = () => {
return (
{/* First column */}{/* Second column */}
);
};
```
## Component Props
This component has no custom props, but expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'body'>`.
---
# Button
> A JSX email component which styles an anchor element to appear as a button
Prompt
A JSX email component which styles an anchor element to appear as a button
Tips
Semantics: Quite often in the email world we talk about buttons when we actually mean links. Behind the scenes this component is a `` element which is styled like a `