Usage with Next.js
Get started with a template
The easiest way to get started is to use one of the templates. All templates are configured correctly: they include PostCSS setup, ColorSchemeScript and other essential features. Some templates also include additional features like Jest, Storybook and ESLint.
If you are not familiar with GitHub, you can find a detailed instruction on how to bootstrap a project from a template on this page.
next-app-template Next.js template with app router and full setup: Jest, Storybook, ESLint | Use template | |
next-pages-template Next.js template with pages router and full setup: Jest, Storybook, ESLint | Use template | |
next-app-min-template Next.js template with app router and minimal setup – no additional tools included, only default Next.js configuration | Use template | |
next-pages-min-template Next.js template with pages router and minimal setup – no additional tools included, only default Next.js configuration | Use template | |
next-vanilla-extract-template Next.js template with Vanilla extract example | Use template |
Generate new application
Follow create-next-app guide to create new Next.js application:
Installation
Choose packages that you will use in your application:
Package | Description | |
---|---|---|
@mantine/hooks | Hooks for state and UI management | |
@mantine/core | Core components library: inputs, buttons, overlays, etc. | |
@mantine/form | Form management library | |
@mantine/dates | Date inputs, calendars | |
@mantine/charts | Recharts based charts library | |
@mantine/notifications | Notifications system | |
@mantine/code-highlight | Code highlight with your theme colors and styles | |
@mantine/tiptap | Rich text editor based on Tiptap | |
@mantine/dropzone | Capture files with drag and drop | |
@mantine/carousel | Embla based carousel component | |
@mantine/spotlight | Overlay command center | |
@mantine/modals | Centralized modals manager | |
@mantine/nprogress | Navigation progress |
Install dependencies:
PostCSS setup
Install PostCSS plugins and postcss-preset-mantine:
Create postcss.config.cjs
file at the root of your application with the following content:
Setup with pages router
Add styles imports and MantineProvider to the pages/_app.tsx
file:
Create pages/_document.tsx
file with ColorSchemeScript component.
Note that it is required even if you use only one color scheme in your application.
All set! Start development server:
Setup with app router
Add MantineProvider, ColorSchemeScript
and styles imports to the app/layout.tsx
file:
All set! Start development server:
app + pages router together
If you use both app and pages router in one application, you need to setup both pages/_app.tsx
and app/layout.tsx
files as described above.
Next.js Link with polymorphic components
Next.js Link
does not work in the same way as other similar components in all Next.js versions.
With Next.js 12 and below:
With Next.js 13 and above:
Server components
All Mantine components use useContext
hook to support default props
and Styles API. Mantine components cannot be used as server components.
It means that components will render both on the server and client.
Entry points of all @mantine/*
packages (index.js
files) have 'use client';
directive at the
top of the file – you do not need to add 'use client';
to your pages/layouts/components.
Compound components in server components
Some components like Popover have associated compound components (Component.XXX
),
where XXX
is a compound component name. Compound components cannot be used in server components.
Instead, use ComponentXXX
syntax or add 'use client';
directive to the top of the file.
Example that will not work in server components:
Example with 'use client';
directive:
Example with ComponentXXX
syntax:
app router tree shaking
To enable tree shaking with app router, enable experimental optimizePackageImports
feature in
your next.config.mjs
: