Skip to main content

Getting Started

Installation​

Install the core packages using your preferred package manager:

# npm
npm install @md3-react/core @md3-react/theme

# yarn
yarn add @md3-react/core @md3-react/theme

# pnpm
pnpm add @md3-react/core @md3-react/theme

Basic Setup​

Wrap your application with the ThemeProvider to enable theming:

import { ThemeProvider } from '@md3-react/theme';
import { Button } from '@md3-react/core';

function App() {
  return (
    <ThemeProvider>
      <Button variant="filled">Click me</Button>
    </ThemeProvider>
  );
}

Next.js Setup​

For Next.js applications, you'll need to configure the Vanilla Extract plugin:

1. Install the plugin​

npm install @vanilla-extract/next-plugin

2. Configure next.config.js​

const { createVanillaExtractPlugin } = require('@vanilla-extract/next-plugin');
const withVanillaExtract = createVanillaExtractPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@md3-react/core', '@md3-react/theme'],
};

module.exports = withVanillaExtract(nextConfig);

3. Add ThemeProvider to layout​

// app/layout.tsx
import { ThemeProvider } from '@md3-react/theme';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

Vite Setup​

For Vite projects:

1. Install the plugin​

npm install @vanilla-extract/vite-plugin

2. Configure vite.config.ts​

import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [react(), vanillaExtractPlugin()],
});

TypeScript Configuration​

md3-react is written in TypeScript and provides comprehensive type definitions out of the box. No additional configuration is required.

For the best experience, we recommend using TypeScript 5.0 or later.

Importing Components​

You can import components in two ways:

import { Button, Typography, Icon } from '@md3-react/core';

Direct imports (for better tree-shaking)​

import { Button } from '@md3-react/core/Button';
import { Typography } from '@md3-react/core/Typography';

Adding Material Symbols Font​

For the Icon component to work properly, add the Material Symbols font to your HTML:

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0"
/>

Or import it in your CSS:

@import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0');

What's Next?​