Mantle is ngrok's UI library and design system that powers its front-end.
Mantle is a carefully designed system of React components and utilities that establishes a unified design language and consistent user experience across ngrok's web applications. Built with flexibility, extensibility, and developer ergonomics in mind, Mantle prioritizes accessibility, performance, and long-term maintainability. Developed in TypeScript, it offers strong typing, rich IDE support, and increased confidence through compile-time safety. By progressively enhancing standard DOM elements, it not only improves usability and accessibility, but also fills functional gaps—providing a robust foundation for building cohesive, modern UIs throughout the platform.
To learn more about the design principles and architectural decisions that guide Mantle, see the Philosophy page.
All of Mantle's components are styled using Tailwind. and we compose around the following unstyled primitive component libraries:
Mantle uses Phosphor Icons as the primary icon library, providing
a versatile and consistent set of icons. In addition, custom-designed icons tailored to ngrok's
needs are available through the @ngrok/mantle/icons module.
Mantle is a living design system and the standard UI library for all ngrok user interfaces. It is continuously evolving as new components, patterns, and improvements are added.
Mantle is available on NPM and is open source on GitHub.
note
react and react-dom versions 18 and 19.Install @ngrok/mantle and all required peerDependencies:
1# npm2npm install -E @ngrok/mantle @phosphor-icons/react date-fns react react-dom3 4# pnpm5pnpm add -E @ngrok/mantle @phosphor-icons/react date-fns react react-dom6 7# bun8bun add -E @ngrok/mantle @phosphor-icons/react date-fns react react-domInstall tailwindcss as a dev dependency (all frameworks):
1# npm2npm install -DE tailwindcss3 4# pnpm5pnpm add -DE tailwindcss6 7# bun8bun add -DE tailwindcssInstall the additional dev dependencies for the Tailwind Vite plugin:
1# npm2npm install -DE @tailwindcss/vite3 4# pnpm5pnpm add -DE @tailwindcss/vite6 7# bun8bun add -DE @tailwindcss/viteAdd the @tailwindcss/vite plugin to your Vite configuration:
1// vite.config.ts2import { reactRouter } from "@react-router/dev/vite";3import { defineConfig } from "vite";4import tsconfigPaths from "vite-tsconfig-paths";5import tailwindcss from "@tailwindcss/vite";6 7export default defineConfig({8 plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],9});In your app's app/root.tsx, import mantle.css and set up the
Theme Provider, Toaster, and
Tooltip Provider.
warning
PreventWrongThemeFlashScript early in the <head> of your app to
prevent a flash of unstyled content (FOUC). For SSR apps, also send font preloads as HTTP Link
headers using preloadFontLink so fonts start fetching before the browser parses any HTML.1// app/entry.server.tsx — send font preload Link headers2import { assetsCdnOrigin, preloadFontLink } from "@ngrok/mantle/theme";3 4// inside your handleRequest / onShellReady:5responseHeaders.set(6 "Link",7 [8 `<${assetsCdnOrigin}>; rel=preconnect; crossorigin`,9 preloadFontLink("roobert"),10 preloadFontLink("jetbrains-mono"),11 preloadFontLink("family-regular"),12 ].join(", "),13);1// app/root.tsx2import {3 PreventWrongThemeFlashScript,4 ThemeProvider,5 useInitialHtmlThemeProps,6} from "@ngrok/mantle/theme";7import { Toaster } from "@ngrok/mantle/toast";8import { TooltipProvider } from "@ngrok/mantle/tooltip";9import type { PropsWithChildren } from "react";10import {11 isRouteErrorResponse,12 Links,13 Meta,14 Outlet,15 Scripts,16 ScrollRestoration,17} from "react-router";18 19import type { Route } from "./+types/root";20import "@ngrok/mantle/mantle.css";21 22export function Layout({ children }: PropsWithChildren) {23 const initialHtmlThemeProps = useInitialHtmlThemeProps({24 className: "h-full",25 });26 27 return (28 // suppressHydrationWarning prevents React from fighting the inline29 // theme script that corrects the class before paint on prerendered/SSR pages.30 <html {...initialHtmlThemeProps} lang="en-US" dir="ltr" suppressHydrationWarning>31 <head>32 <meta charSet="utf-8" />33 <meta name="viewport" content="width=device-width, initial-scale=1" />34 {/* PreventWrongThemeFlashScript must be as early as possible in <head> */}35 <PreventWrongThemeFlashScript />36 <Meta />37 <Links />38 </head>39 <body>40 <ThemeProvider>41 <TooltipProvider>42 <Toaster />43 {children}44 </TooltipProvider>45 </ThemeProvider>46 <ScrollRestoration />47 <Scripts />48 </body>49 </html>50 );51}52 53export default function App() {54 return <Outlet />;55}56 57export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {58 let message = "Oops!";59 let details = "An unexpected error occurred.";60 let stack: string | undefined;61 62 if (isRouteErrorResponse(error)) {63 message = error.status === 404 ? "404" : "Error";64 details =65 error.status === 404 ? "The requested page could not be found." : error.statusText || details;66 } else if (import.meta.env.DEV && error && error instanceof Error) {67 details = error.message;68 stack = error.stack;69 }70 71 return (72 <main className="pt-16 p-4 container mx-auto">73 <h1>{message}</h1>74 <p>{details}</p>75 {stack && (76 <pre className="w-full p-4 overflow-x-auto">77 <code>{stack}</code>78 </pre>79 )}80 </main>81 );82}You are now ready to use mantle components in your application! For example, you can use the Button.
For apps behind authentication where responses are not publicly cached by a CDN, you can
pass the theme cookie to useInitialHtmlThemeProps to eliminate the hydration mismatch entirely.
This ensures the server renders the correct theme class, so React hydration matches the inline
script without needing suppressHydrationWarning.
caution
ssrCookie on publicly cached pages. React Router serializes loader data into
the HTML, so the first visitor's theme would be baked into the CDN cache and served to everyone.
For public/CDN-cached apps, rely on suppressHydrationWarning instead (shown above).warning
Cookie header from a loader — it would leak HttpOnly/session cookies
into the HTML. Always use extractThemeCookie to return only the theme cookie.1import { extractThemeCookie, useInitialHtmlThemeProps } from "@ngrok/mantle/theme";2 3export const loader = async ({ request }: Route.LoaderArgs) => {4 const themeCookie = extractThemeCookie(request.headers.get("Cookie"));5 return { themeCookie };6};7 8export function Layout({ children }: PropsWithChildren) {9 const loaderData = useRouteLoaderData<typeof loader>("root");10 const initialHtmlThemeProps = useInitialHtmlThemeProps({11 className: "h-full",12 ssrCookie: loaderData?.themeCookie,13 });14 // ...15}Install the additional dev dependencies for the Tailwind Vite plugin:
1# npm2npm install -DE @tailwindcss/vite3 4# pnpm5pnpm add -DE @tailwindcss/vite6 7# bun8bun add -DE @tailwindcss/viteAdd the @tailwindcss/vite plugin to your Vite configuration:
1// vite.config.ts2import { defineConfig } from "vite";3import tailwindcss from "@tailwindcss/vite";4 5export default defineConfig({6 plugins: [tailwindcss()],7});In your app's src/main.tsx, import mantle.css and set up the
Theme Provider, Toaster, and
Tooltip Provider:
1// src/main.tsx2import { StrictMode } from "react";3import { createRoot } from "react-dom/client";4import { ThemeProvider } from "@ngrok/mantle/theme";5import { Toaster } from "@ngrok/mantle/toast";6import { TooltipProvider } from "@ngrok/mantle/tooltip";7import "@ngrok/mantle/mantle.css";8import App from "./App.tsx";9 10createRoot(document.getElementById("root")!).render(11 <StrictMode>12 <ThemeProvider>13 <TooltipProvider>14 <Toaster />15 <App />16 </TooltipProvider>17 </ThemeProvider>18 </StrictMode>,19);To prevent a flash of unstyled content (FOUC), update your index.html to include the theme
script. Import preventWrongThemeFlashScriptContent from @ngrok/mantle/theme and inline its
output in a <script> tag in the <head>:
warning
<head> of your app. We plan to
add a vite plugin in the future to automate this.1<!-- index.html -->2<!doctype html>3<html lang="en">4 <head>5 <meta charset="UTF-8" />6 <link rel="icon" type="image/svg+xml" href="/vite.svg" />7 <meta name="viewport" content="width=device-width, initial-scale=1.0" />8 <title>Vite + React + TS</title>9 <script>10 // Inline the output of preventWrongThemeFlashScriptContent()11 // from "@ngrok/mantle/theme" here to prevent FOUC12 </script>13 </head>14 <body>15 <div id="root"></div>16 <script type="module" src="/src/main.tsx"></script>17 </body>18</html>You are now ready to use mantle components in your application! For example, you can use the Button.
caution
In your app's entry/root file, import mantle.css and set up the
Theme Provider, Toaster, and
Tooltip Provider:
1// root.tsx2import { StrictMode } from "react";3import { createRoot } from "react-dom/client";4import { ThemeProvider } from "@ngrok/mantle/theme";5import { Toaster } from "@ngrok/mantle/toast";6import { TooltipProvider } from "@ngrok/mantle/tooltip";7import "@ngrok/mantle/mantle.css";8import App from "./App.tsx";9 10const container = window.document.getElementById("app");11 12if (!container) {13 throw new Error(14 "Something went wrong: cannot render application! Please refresh the page to try again.",15 );16}17 18const root = createRoot(container);19 20root.render(21 <StrictMode>22 <ThemeProvider>23 <TooltipProvider>24 <Toaster />25 <App />26 </TooltipProvider>27 </ThemeProvider>28 </StrictMode>,29);To prevent a flash of unstyled content (FOUC), include the theme script in the <head> of your
index.html. Import preventWrongThemeFlashScriptContent from @ngrok/mantle/theme and inline
its output:
warning
<head>
of your app.1<script>2 // Inline the output of preventWrongThemeFlashScriptContent()3 // from "@ngrok/mantle/theme" here to prevent FOUC4</script>You are now ready to use mantle components in your application! For example, you can use the Button.