name: mantine-ui description: Rules and best practices for Mantine v8 UI library. Use when working with @mantine/core, @mantine/hooks, @mantine/notifications components, or when building UI with Mantine. Covers styling, theming, responsive design, and component-specific patterns. license: MIT metadata: author: spotsccc version: "1.0.0"

Mantine v8 UI Library

Comprehensive component and styling guide for Mantine v8, designed for AI agents and LLMs. Contains rules across 9 categories covering 50+ components and hooks, with decision trees, props reference, gotchas, and code examples.

When to Apply

Reference these guidelines when:

• Building UI with @mantine/core components
• Using @mantine/hooks in React components
• Implementing toast notifications with @mantine/notifications
• Styling Mantine components (choosing between props, CSS Modules, Styles API)
• Setting up theming with createTheme() and MantineProvider
• Working with Next.js + Mantine integration

General

• Version: Mantine v8 (@mantine/core, @mantine/hooks, @mantine/notifications)
• All components: import { Component } from '@mantine/core'
• Hooks: import { useHook } from '@mantine/hooks'
• Notifications: import { notifications } from '@mantine/notifications'
• Theme: createTheme() + MantineProvider; access via useMantineTheme()

All components support

• className, classNames (Styles API), style, styles
• Style props: m, p, c, bg, fz, fw, ta, w, h, maw, mah, pos, etc.
• Responsive: hiddenFrom, visibleFrom (breakpoint-based show/hide)
• Polymorphic: component prop to change root element

Rule Categories

| # | Category | Prefix | Components / Scope | |---|----------|--------|--------------------| | 1 | Best Practices | best-practices | Styling, theming, responsive, CSS variables | | 2 | Layout | layout/ | Container, Grid, SimpleGrid, Stack, Group, Flex, Box, AppShell, Paper, Card, Center, Space, Divider | | 3 | Typography | typography/ | Text, Title, Anchor, Code, Highlight, TypographyStylesProvider | | 4 | Inputs & Buttons | inputs/ | Button, ActionIcon, TextInput, Textarea, Select, MultiSelect, TagsInput, NumberInput, Checkbox, Switch | | 5 | Data Display | data-display/ | Table, Badge, Image, Avatar, ThemeIcon, Timeline, Indicator, List, Accordion | | 6 | Navigation | navigation/ | NavLink, Breadcrumbs, Burger, Menu, Tabs, Pagination, Stepper | | 7 | Feedback | feedback/ | Alert, Notification, Loader, LoadingOverlay, Skeleton, Progress | | 8 | Overlays | overlays/ | Modal, Drawer, Popover, Tooltip, HoverCard | | 9 | Hooks | hooks/ | useDisclosure, useDebouncedValue, useMediaQuery, useClickOutside, useIntersection, useHotkeys |

Quick Reference

1. Best Practices

• best-practices — Styling priority, Styles API, responsive design, PostCSS, polymorphic components, CSS variables

2. Layout

Read decision tree: rules/layout/README.md

• layout/container — Max-width centered wrapper
• layout/grid — 12-column responsive grid
• layout/simple-grid — Equal-width responsive grid
• layout/stack — Vertical flex container
• layout/group — Horizontal flex container
• layout/flex — Full-control flex container
• layout/box — Generic wrapper (div)
• layout/app-shell — Page-level layout shell
• layout/paper — Surface with background/shadow
• layout/card — Structured surface with sections
• layout/center — Center content
• layout/space — Spacing element
• layout/divider — Horizontal/vertical separator

3. Typography

Read decision tree: rules/typography/README.md

• typography/text — Display text with theme styles
• typography/title — Semantic headings h1–h6
• typography/anchor — Themed link element
• typography/code — Inline and block code
• typography/highlight — Highlight matching substrings
• typography/typography-styles-provider — Apply theme to raw HTML

4. Inputs & Buttons

Read decision tree: rules/inputs/README.md

• inputs/button — Action trigger (button or link)
• inputs/action-icon — Icon-only button
• inputs/text-input — Single-line text input
• inputs/textarea — Multi-line text input
• inputs/select — Single value from list
• inputs/multi-select — Multiple values from list
• inputs/tags-input — Free-form tags with suggestions
• inputs/number-input — Numeric input with increment/decrement
• inputs/checkbox — Boolean toggle (checkmark)
• inputs/switch — Boolean toggle (switch)

5. Data Display

Read decision tree: rules/data-display/README.md

• data-display/table — Themed HTML table
• data-display/badge — Status label, tag, count
• data-display/image — Image with optional fallback
• data-display/avatar — User photo / initials
• data-display/theme-icon — Icon with colored background
• data-display/timeline — Chronological events
• data-display/indicator — Notification dot / count on element
• data-display/list — Styled ordered / unordered list
• data-display/accordion — Collapsible sections

6. Navigation

Read decision tree: rules/navigation/README.md

• navigation/nav-link — Sidebar link with icon, description
• navigation/breadcrumbs — Path navigation breadcrumbs
• navigation/burger — Mobile menu toggle
• navigation/menu — Dropdown action menu
• navigation/tabs — Content tab switching
• navigation/pagination — Page number navigation
• navigation/stepper — Multi-step wizard / progress

7. Feedback

Read decision tree: rules/feedback/README.md

• feedback/alert — Static important message block
• feedback/notification — Toast notification
• feedback/loader — Spinning indicator
• feedback/loading-overlay — Block UI during loading
• feedback/skeleton — Content placeholder
• feedback/progress — Progress bar

8. Overlays

Read decision tree: rules/overlays/README.md

• overlays/modal — Accessible overlay dialog
• overlays/drawer — Side panel overlay
• overlays/popover — Anchored popup with rich content
• overlays/tooltip — Simple text hint on hover
• overlays/hover-card — Rich content preview on hover

9. Hooks

Read decision tree: rules/hooks/README.md

• hooks/use-disclosure — Boolean state (open/close/toggle)
• hooks/use-debounced-value — Debounce input value
• hooks/use-media-query — Viewport width (NOT SSR-safe)
• hooks/use-click-outside — Detect click outside element
• hooks/use-intersection — Observe element visibility
• hooks/use-hotkeys — Keyboard shortcuts

Theme Tokens (CSS Variables)

| Token | CSS Variable | Style prop | |-------|-------------|------------| | Spacing | var(--mantine-spacing-{xs\|sm\|md\|lg\|xl}) | p, m, gap | | Colors | var(--mantine-color-{name}-{0-9}) | c, bg ("blue.6") | | Font size | var(--mantine-font-size-{size}) | fz | | Radius | var(--mantine-radius-{size}) | radius prop | | Shadow | var(--mantine-shadow-{size}) | shadow prop | | Headings | var(--mantine-h{1-6}-font-size) | Title order | | Primary | var(--mantine-primary-color-filled) | color prop |

Next.js Pages Router

• ColorSchemeScript in _document.tsx, mantineHtmlProps on <Html>
• MantineProvider in _app.tsx
• @mantine/* packages in transpilePackages (next.config)
• Use component={Link} for Next.js Link (v13+)
• All Mantine components are client components ('use client' already in entry points)

How to Use

Read individual rule files for detailed props, gotchas, and code examples:

rules/best-practices.md
rules/layout/container.md
rules/inputs/select.md
rules/hooks/use-disclosure.md

Each category directory contains:

• README.md — decision tree for choosing the right component, comparison tables, common patterns
• Component files — key props, rules/gotchas, and code examples

Styling priority: Component props > Style props > CSS Modules > style prop. Read rules/best-practices.md first.