Learn how to add your own custom components to your Mosaic site.
An extension that renders Mosaic components or calls its hooks must use the host's React and Mosaic contexts. Declare the Mosaic packages it imports as peerDependencies, and add the same versions to devDependencies for local development. For example, an extension tested with the beta.98 release can declare:
{
"peerDependencies": {
"@jpmorganchase/mosaic-components": "^0.1.0-beta.98",
"@jpmorganchase/mosaic-store": "^0.1.0-beta.98",
"react": "^19.1.0",
"react-dom": "^19.1.0"
},
"devDependencies": {
"@jpmorganchase/mosaic-components": "0.1.0-beta.98",
"@jpmorganchase/mosaic-store": "0.1.0-beta.98",
"react": "^19.1.0",
"react-dom": "^19.1.0"
}
}
Externalize those peers when bundling the extension, including their subpath imports. Listing peers does not stop a bundler from embedding a second copy. A bundled or separately installed mosaic-store, for example, creates a different context: its hooks cannot see the host's StoreProvider or ColorModeProvider.
The host installs the packages and chooses one Mosaic release cohort. Test the packed extension against the host's providers, including an interaction that updates shared state. See Trying a snapshot for preview versions.
To start, create a components folder under src where you'll store your custom components.
src/
└── components/In this tutorial, we will create a custom Card component.
Inside the components folder, create a card folder, which will contain your React Card component. The card folder should include index.tsx and card.module.css files as shown in the structure below:
├── src/
│ ├── components/
│ │ └── card/
│ │ ├── index.tsx
│ │ └── card.module.cssCreate your Card component within the index.tsx file:
import React from 'react';
import styles from './card.module.css';
type CardProps = {
title: string;
content: string;
};
export const Card: React.FC<CardProps> = ({ title, content }) => {
return (
<div className={styles.card}>
<h2>{title}</h2>
<p>{content}</p>
</div>
);
};
Define your component styles in the card.module.css file:
.card {
background-color: #f5f5f5;
border: 1px solid #ccc;
border-radius: 4px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
padding: 16px;
transition: box-shadow 0.2s ease-in-out;
}
.card:hover {
box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
}
.card h2 {
color: #333;
font-size: 24px;
margin-bottom: 8px;
}
.card p {
color: #666;
font-size: 16px;
line-height: 1.5;
}
In this example, we use a CSS file, but you can use whichever styling approach you prefer, such as vanilla extract.
To export your Card component, create an index.ts file in the components folder:
export * from './card';
Your final folder structure should look like this:
├── src/
│ ├── components/
│ │ ├── card/
│ │ │ ├── index.tsx
│ │ │ └── card.module.css
│ │ ├── index.tsOpen your site's MDX component registry at
src/app/[namespace]/[...route]/MdxComponents.ts. This file is the App Router
equivalent of the old pages/_app.tsx component-merge step. Its hostComponents
registry is shared by the reader's MdxRenderer and the editor's mdxComponents map.
Add the following line to your imports:
import * as myComponents from '../../../components';
Replace this block:
const hostComponents = { Salt, Sitemap };
with:
const hostComponents = { Salt, Sitemap, ...myComponents };
Keep both exports wired to this registry so custom components work in reader pages and editor previews:
export const mdxComponents = { ...mosaicDefaultComponents, ...hostComponents };
export const MdxRenderer = createMdxRenderer({ components: hostComponents });
Host components override Mosaic's defaults when names match.
Note:
MdxComponents.tsis marked'use client'. Salt DS and any other component that uses hooks must be reachable from a client boundary. The server'sBodyServerrenders the clientMdxRenderer; the editor consumesmdxComponentsseparately.
Now you're ready to use your custom Card component. Build and run your site, and add the Card component to an MDX file in your docs folder or another source:
<Card title="My Card" content="This is the content of my card." />
You can create and add more custom components to your Mosaic site by following the same process.