Custom Components

Learn how to add your own custom components to your Mosaic site.

Publishing an extension package

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.

Create Components Folder

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.

Create 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.css

Card Component: index.tsx

Create 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>
  );
};

Card Component: card.module.css

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.ts

Import Custom Card Component

Open 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.ts is marked 'use client'. Salt DS and any other component that uses hooks must be reachable from a client boundary. The server's BodyServer renders the client MdxRenderer; the editor consumes mdxComponents separately.

Use Your Custom Card Component

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.

Mosaic BETA

Coming soon