Terminal
Terminal/Skill
Guides building your own Mantine-compatible components that support theming, the Styles API and CSS variables.
By Mantine
Works with
npx skills add mantinedev/skills --skill mantine-custom-componentsWritten for Mantine 9.x.
import {
Box, BoxProps, createVarsResolver, ElementProps,
factory, Factory, getRadius, MantineRadius,
StylesApiProps, useProps, useStyles,
} from '@mantine/core';
import classes from './MyComponent.module.css';
export type MyComponentStylesNames = 'root' | 'inner';
export type MyComponentVariant = 'filled' | 'outline';
export type MyComponentCssVariables = { root: '--my-radius' };
export interface MyComponentProps
extends BoxProps, StylesApiProps<MyComponentFactory>, ElementProps<'div'> {
radius?: MantineRadius;
}
export type MyComponentFactory = Factory<{
props: MyComponentProps;
ref: HTMLDivElement;
stylesNames: MyComponentStylesNames;
vars: MyComponentCssVariables;
variant: MyComponentVariant;
}>;
const defaultProps = {} satisfies Partial<MyComponentProps>;
const varsResolver = createVarsResolver<MyComponentFactory>((_theme, { radius }) => ({
// undefined leaves the variable unset, so the CSS fallback (theme default radius) applies
root: { '--my-radius': radius === undefined ? undefined : getRadius(radius) },
}));
export const MyComponent = factory<MyComponentFactory>((_props) => {
const props = useProps('MyComponent', defaultProps, _props);
const { classNames, className, style, styles, unstyled, vars, attributes, radius, ...others } = props;
const getStyles = useStyles<MyComponentFactory>({
name: 'MyComponent', classes, props,
className, style, classNames, styles, unstyled, vars, attributes, varsResolver,
});
return <Box {...getStyles('root')} {...others} />;
});
MyComponent.displayName = 'MyComponent';
MyComponent.classes = classes;
MyComponent.varsResolver = varsResolver;
/* MyComponent.module.css */
.root {
border-radius: var(--my-radius, var(--mantine-radius-default));
}
ref is a regular prop in React 19: it arrives in props and reaches the root element through ...others.
What you get without extra code:
getStyles('selector') gets the static class mantine-MyComponent-selector.classNames, styles, vars and attributes props, and the same keys in MyComponent.extend() in the theme.unstyled removes the CSS module classes. Static classes and the CSS variables on the root stay.MyComponent.extend() and MyComponent.withProps() static functions. withProps presets props at
runtime but does not change types: a required prop stays required for TypeScript, so make props you
intend to preset optional.Pass variant and size to Box: it sets data-variant and data-size attributes to style in CSS.
Passing variant to getStyles additionally applies the root--{variant} class when the CSS module defines one:
const { variant, size, ...others } = props;
<Box variant={variant} size={size} {...getStyles('root', { variant })} {...others} />
.root {
&[data-variant='outline'] { border: 1px solid var(--my-color); }
&[data-size='lg'] { height: 50px; }
}
Sizes driven by one size prop: define the token values in CSS and select one with getSize. A
number or any CSS value passed as size is used as is (getSize(60, 'x') returns calc(3.75rem * var(--mantine-scale))).
root: { '--card-padding': getSize(size, 'card-padding'), '--card-fz': getFontSize(size) },
.root {
--card-padding-sm: 12px;
--card-padding-md: 16px;
--card-padding-lg: 24px;
padding: var(--card-padding, var(--card-padding-md));
}
For colors that follow the theme, resolve them in the vars resolver with
theme.variantColorResolver({ color: color || theme.primaryColor, theme, variant: variant || 'filled', autoContrast })
— it returns background, hover and color as colors and border as a full border shorthand value
(1px solid transparent). It knows the variants filled, light, outline, subtle, transparent, white and
default; autoContrast: undefined falls back to theme.autoContrast. For a single color use
getThemeColor(color, theme): it accepts 'blue', 'teal.7' and CSS colors.
.root {
background-color: var(--my-bg);
color: var(--my-color);
border: var(--my-bd); /* the whole shorthand, not border-color */
}
Because the resolver comes from the theme, an app can add its own variant (variant="danger") or
recolor an existing one without touching the component. Do not redeclare variant in your props
interface: StylesApiProps already types it as your variants plus any string.
| Scenario | Factory function | Type |
|---|---|---|
| Standard component | factory() | Factory<{}> |
Supports component prop (polymorphic) | polymorphicFactory() | PolymorphicFactory<{}> — add defaultComponent and defaultRef |
Props change based on a generic (e.g. multiple) | genericFactory() | Factory<{ signature: ... }> |
Use polymorphicFactory sparingly — it adds TypeScript overhead and slows IDE autocomplete.
Every factory component also accepts renderRoot={(props) => <a {...props} />} as an alternative to component.
Factory<{
props: MyComponentProps; // required
ref: HTMLDivElement; // element type for the forwarded ref
stylesNames: 'root' | 'inner'; // union of Styles API selectors
vars: { root: '--my-var' }; // CSS variable map per selector
variant: 'filled' | 'outline'; // accepted variant strings
staticComponents: { // sub-components (compound pattern)
Item: typeof MyComponentItem;
};
compound: true; // only for sub-components; disables theme classNames/styles/vars
ctx: { stepsCount: number }; // only if needed; passed to classNames/styles/vars functions as third arg
signature?: (...) => JSX.Element; // only for genericFactory
}>
Users and the theme can override defaults via Component.extend():
const theme = createTheme({
components: {
MyComponent: MyComponent.extend({
defaultProps: { radius: 'xl' },
classNames: { root: 'my-root' },
styles: { root: { color: 'red' } },
vars: (_theme, props) => ({ root: { '--my-radius': getRadius(props.radius) } }),
}),
},
});
In theme.components, sub-components are registered without the dot: MyCardSection: MyCard.Section.extend({ defaultProps }).
Read the part that matches the task before writing code:
references/patterns.md — complete examples. Read "Compound component with context" for components with sub-components (Card.Section), "Wrapping a Mantine component" when the component renders an existing Mantine input or component inside and must forward classNames / styles to it, "Components that share theme configuration" for a family of components with a common base, "Converting an existing component" when migrating a forwardRef component with inline styles, "Polymorphic component" for a component prop, "Generic component" for props that depend on a type parameter, "Theme integration" for extend and withPropsreferences/api.md — read it for any component beyond the template above: it is the only place that documents getStyles options (focusable), the mod prop, theme helper outputs, MantineThemeProvider and what theme functions receive. Every function and type: factory variants, useProps, useStyles and getStyles options, createVarsResolver, createSafeContext, StylesApiProps, CompoundStylesApiProps, BoxProps (including mod), ElementProps, theme helpers (getSize, getRadius, getThemeColor...)If the references do not cover what you need, do not guess:
@mantine/mcp-server) is connected, use search_docs, get_item_doc and get_apihttps://mantine.dev/llms.txt and open the Styles API, variants and sizes, and custom components pages