Mantine UI Development

Purpose

Build React UIs with Mantine's component library, Styles API for customization, and @mantine/form for form handling.

When NOT to Use

• Basic React development (Claude knows this)
• Non-Mantine UI libraries (Material UI, Chakra, etc.)
• Simple HTML/CSS without Mantine
• Mantine v6 or earlier (this skill covers v7+)

Quick Start

Step 1: Import Components

// Core components
import { Button, TextInput, Select, Modal } from '@mantine/core';

// Hooks
import { useDisclosure, useToggle } from '@mantine/hooks';

// Form handling
import { useForm } from '@mantine/form';

Step 2: Basic Component Usage

<Button variant="filled" color="blue" size="md" loading={isLoading}>
  Submit
</Button>

<TextInput
  label="Email"
  placeholder="your@email.com"
  error={errors.email}
  required
/>

Step 3: Customize with Styles API

See Core Patterns below.

Step 4: Validate Accessibility

• Add aria-label to icon-only buttons
• Check keyboard navigation works
• Verify focus states are visible

Core Patterns

Styles API (Critical)

Mantine components have multiple inner elements. Use Styles API to target them:

// Option 1: classNames prop (recommended for CSS modules)
import classes from './Button.module.css';

<Button classNames={{
  root: classes.button,      // Outer wrapper
  label: classes.buttonLabel // Text content
}} />

/* Button.module.css */
.button {
  background: linear-gradient(45deg, blue, purple);
}
.buttonLabel {
  font-weight: 700;
}

// Option 2: styles prop (inline styles for inner elements)
<Button styles={{
  root: { padding: '10px 20px' },
  label: { color: 'white' }
}} />

// Option 3: CSS variables
<Button style={{ '--button-bg': 'var(--mantine-color-blue-6)' }} />

// Option 4: Data attributes for state
<Button data-active={isActive} />

Finding selector names: Check Mantine docs for each component's "Styles API" section listing available selectors.

Form Handling (@mantine/form)

import { useForm } from '@mantine/form';
import { TextInput, Checkbox, Button, Box } from '@mantine/core';

function LoginForm() {
  const form = useForm({
    initialValues: {
      email: '',
      password: '',
      rememberMe: false,
    },
    validate: {
      email: (value) =>
        /^\S+@\S+$/.test(value) ? null : 'Invalid email',
      password: (value) =>
        value.length >= 8 ? null : 'Password must be 8+ characters',
    },
    // Optional: validate on change instead of only on submit
    validateInputOnChange: true,
  });

  const handleSubmit = (values: typeof form.values) => {
    console.log('Form submitted:', values);
  };

  return (
    <Box component="form" onSubmit={form.onSubmit(handleSubmit)}>
      <TextInput
        label="Email"
        placeholder="your@email.com"
        {...form.getInputProps('email')}
      />
      <TextInput
        label="Password"
        type="password"
        {...form.getInputProps('password')}
      />
      <Checkbox
        label="Remember me"
        {...form.getInputProps('rememberMe', { type: 'checkbox' })}
      />
      <Button type="submit" mt="md">Login</Button>
    </Box>
  );
}

Key form methods:

• form.getInputProps('fieldName') - Binds value, onChange, error
• form.getInputProps('field', { type: 'checkbox' }) - For checkboxes/switches
• form.onSubmit(handler) - Validates before calling handler
• form.setFieldValue('field', value) - Programmatic updates
• form.reset() - Reset to initial values
• form.validate() - Manual validation

Polymorphic Components

Change the underlying HTML element:

// Button as link
<Button component="a" href="/dashboard">
  Go to Dashboard
</Button>

// Text as span (default is p)
<Text component="span">Inline text</Text>

// Card as article
<Card component="article">Content</Card>

TypeScript note: Ref type changes with component prop!

// Default: HTMLButtonElement
const buttonRef = useRef<HTMLButtonElement>(null);
<Button ref={buttonRef} />

// With component="a": HTMLAnchorElement
const linkRef = useRef<HTMLAnchorElement>(null);
<Button component="a" ref={linkRef} href="/" />

Theming

import { MantineProvider, createTheme } from '@mantine/core';

const theme = createTheme({
  primaryColor: 'violet',
  colors: {
    // Add custom color palette
    brand: [
      '#f0e6ff', '#d9c2ff', '#c29dff', '#ab79ff',
      '#9454ff', '#7d30ff', '#660bff', '#5200d9',
      '#3e00a6', '#2b0073'
    ],
  },
  components: {
    Button: {
      defaultProps: {
        radius: 'md',
      },
    },
  },
});

function App() {
  return (
    <MantineProvider theme={theme}>
      {/* Your app */}
    </MantineProvider>
  );
}

Dark Mode

import { useMantineColorScheme, Button } from '@mantine/core';

function ColorSchemeToggle() {
  const { colorScheme, toggleColorScheme } = useMantineColorScheme();

  return (
    <Button onClick={() => toggleColorScheme()}>
      {colorScheme === 'dark' ? 'Light' : 'Dark'} mode
    </Button>
  );
}

CSS for dark mode:

/* Use light-dark() function */
.myComponent {
  background: light-dark(white, var(--mantine-color-dark-7));
  color: light-dark(black, white);
}

Common Pitfalls

1. Nested Interactive Elements

Wrong:

<Accordion.Control>
  <Button onClick={handleDelete}>Delete</Button>  {/* Invalid! */}
</Accordion.Control>

Correct:

<Accordion.Item>
  <Box style={{ display: 'flex', alignItems: 'center' }}>
    <Accordion.Control style={{ flex: 1 }}>Title</Accordion.Control>
    <Button onClick={handleDelete}>Delete</Button>
  </Box>
  <Accordion.Panel>Content</Accordion.Panel>
</Accordion.Item>

2. Tooltip on Disabled Button

Wrong:

<Tooltip label="Disabled">
  <Button disabled>Click me</Button>  {/* Tooltip won't show! */}
</Tooltip>

Correct:

<Tooltip label="Disabled">
  <Button data-disabled onClick={(e) => e.preventDefault()}>
    Click me
  </Button>
</Tooltip>

3. ActionIcon.Group Wrapping

Wrong:

<ActionIcon.Group>
  <div>  {/* Invalid wrapper! */}
    <ActionIcon><IconEdit /></ActionIcon>
  </div>
</ActionIcon.Group>

Correct:

<ActionIcon.Group>
  <ActionIcon><IconEdit /></ActionIcon>
  <ActionIcon><IconTrash /></ActionIcon>
</ActionIcon.Group>

4. Missing aria-label

Wrong:

<ActionIcon>
  <IconSearch />  {/* No accessible name! */}
</ActionIcon>

Correct:

<ActionIcon aria-label="Search">
  <IconSearch />
</ActionIcon>

5. AspectRatio in Flexbox

Wrong:

<Flex>
  <AspectRatio ratio={16/9}>  {/* Won't size correctly */}
    <Image src="/photo.jpg" />
  </AspectRatio>
</Flex>

Correct:

<Flex>
  <AspectRatio ratio={16/9} w={300}>  {/* Explicit width */}
    <Image src="/photo.jpg" />
  </AspectRatio>
</Flex>

6. Select vs Autocomplete Confusion

• Select: User MUST choose from options (enforces list)
• Autocomplete: User CAN type any value (suggestions only)

// Use Select when value must be from list
<Select data={['Option 1', 'Option 2']} />

// Use Autocomplete when free text is acceptable
<Autocomplete data={['Suggestion 1', 'Suggestion 2']} />

Accessibility Requirements

1. Icon buttons must have aria-label:

   <ActionIcon aria-label="Close modal">
     <IconX />
   </ActionIcon>
   

2. Use closeButtonLabel prop:

   <Modal closeButtonLabel="Close this dialog" opened={opened} onClose={close}>
   

3. Set heading order for accordions:

   <Accordion.Control order={3}>  {/* Renders as <h3> */}
   

4. Test keyboard navigation:

   • Tab through form fields
   • Enter/Space on buttons
   • Escape to close modals
   • Arrow keys in menus

Troubleshooting

Problem	Cause	Solution
Styles not applying	Wrong selector name	Check component's Styles API docs for available selectors
Dark mode has wrong colors	Hardcoded color values	Use light-dark() CSS function or theme colors
Form not validating	Wrong config	Use validate for submit-time, validateInputOnChange for live validation
TypeScript ref errors	Polymorphic component	Update ref type to match component prop value
Component won't accept custom props	Polymorphic typing	Props don't extend default element; use component to change
Tooltip not showing on disabled	Disabled blocks events	Use data-disabled with onClick preventDefault

External Documentation

For latest Mantine documentation:

1. Context7 (recommended):

   mcp__context7__get-library-docs
   context7CompatibleLibraryID: "/mantinedev/mantine"
   topic: "Button" or "Select" or "form" etc.
   

2. Direct fetch:

   WebFetch → https://mantine.dev/llms.txt
   

3. Official docs: https://mantine.dev

Component Quick Reference

See REFERENCE.md for detailed component patterns including:

• Layout: Stack, Group, Grid, Flex, Container, AppShell
• Inputs: TextInput, Select, Checkbox, DatePicker
• Feedback: Modal, Notifications, Alert
• Navigation: Tabs, NavLink, Breadcrumbs
• Data: Table, Skeleton, Timeline

---

Related Agent

For comprehensive React + Mantine UI guidance that coordinates this and other Mantine skills, use the mantine-ui-expert agent.

Cost Optimization: Use model="haiku" when invoking this agent for routine component development tasks. Haiku is sufficient for template-based Mantine patterns and Styles API usage.