slots-api

What this skill does

# MUI Slots & slotProps API

The slots/slotProps pattern is MUI's primary mechanism for deep component customization. It lets you replace internal sub-components, inject custom renderers, and pass props to every layer of a compound component without wrapper hacks.

## 1. What Are Slots?

Every compound MUI component is built from smaller internal elements. The `slots` prop lets you swap any of those internal elements with your own component. The `slotProps` prop lets you pass additional props to each slot — whether you replaced it or not.

```tsx
// Before (MUI v5 — deprecated)
<Autocomplete
  PaperComponent={CustomPaper}
  componentsProps={{ paper: { elevation: 8 } }}
/>

// After (MUI v6+ — slots API)
<Autocomplete
  slots={{ paper: CustomPaper }}
  slotProps={{ paper: { elevation: 8 } }}
/>
```

**Key rules:**
- `slots` accepts component references (not JSX elements)
- `slotProps` accepts either a plain object or a callback function
- Slot names are camelCase: `slots.valueLabel`, not `slots.ValueLabel`
- The component you provide receives all the props that the default slot component would receive — spread them through

## 2. Common Slot Patterns by Component

### TextField

```tsx
import { TextField, InputBase, FormHelperText } from '@mui/material';

// Replace the underlying input element
<TextField
  label="Custom Input"
  slots={{
    input: InputBase,
    inputLabel: CustomLabel,
  }}
  slotProps={{
    input: {
      sx: { borderRadius: 2, bgcolor: 'grey.50' },
      'aria-describedby': 'helper-text',
    },
    inputLabel: {
      shrink: true,
      sx: { fontWeight: 600 },
    },
    formHelperText: {
      sx: { fontSize: '0.75rem', color: 'warning.main' },
    },
    htmlInput: {
      maxLength: 100,
      pattern: '[A-Za-z]+',
    },
  }}
  helperText="Letters only, max 100 chars"
/>
```

### Autocomplete

```tsx
import {
  Autocomplete,
  TextField,
  Paper,
  Popper,
  type PaperProps,
  type PopperProps,
  type AutocompleteRenderOptionState,
} from '@mui/material';
import { forwardRef } from 'react';

// Custom paper with shadow and border radius
const StyledPaper = forwardRef<HTMLDivElement, PaperProps>((props, ref) => (
  <Paper
    {...props}
    ref={ref}
    elevation={8}
    sx={{ borderRadius: 2, border: '1px solid', borderColor: 'divider' }}
  />
));
StyledPaper.displayName = 'StyledPaper';

// Custom popper with width matching
const WidePopper = forwardRef<HTMLDivElement, PopperProps>((props, ref) => (
  <Popper {...props} ref={ref} placement="bottom-start" sx={{ minWidth: 400 }} />
));
WidePopper.displayName = 'WidePopper';

<Autocomplete
  options={options}
  slots={{
    paper: StyledPaper,
    popper: WidePopper,
    listbox: CustomListbox,
  }}
  slotProps={{
    paper: { 'data-testid': 'autocomplete-dropdown' },
    popper: { modifiers: [{ name: 'offset', options: { offset: [0, 8] } }] },
    listbox: { sx: { maxHeight: 300, '& .MuiAutocomplete-option': { py: 1 } } },
    chip: { size: 'small', color: 'primary', variant: 'outlined' },
    clearIndicator: { sx: { color: 'error.main' } },
  }}
  renderInput={(params) => <TextField {...params} label="Search" />}
/>
```

### Select

```tsx
import { Select, MenuItem } from '@mui/material';

<Select
  value={value}
  onChange={handleChange}
  slots={{
    root: CustomSelectRoot,
  }}
  slotProps={{
    listbox: {
      sx: {
        maxHeight: 250,
        '& .MuiMenuItem-root': {
          borderRadius: 1,
          mx: 0.5,
        },
      },
    },
  }}
>
  <MenuItem value={10}>Ten</MenuItem>
  <MenuItem value={20}>Twenty</MenuItem>
</Select>
```

### Slider

```tsx
import { Slider, type SliderThumbSlotProps } from '@mui/material';
import { forwardRef } from 'react';

// Custom thumb with tooltip-style display
const CustomThumb = forwardRef<HTMLSpanElement, SliderThumbSlotProps>(
  (props, ref) => {
    const { children, className, ...other } = props;
    return (
      <span ref={ref} className={className} {...other}>
        {children}
        <span style={{
          position: 'absolute',
          top: -28,
          fontSize: 12,
          fontWeight: 700,
          background: '#1976d2',
          color: '#fff',
          borderRadius: 4,
          padding: '2px 6px',
        }}>
          {props['aria-valuenow']}
        </span>
      </span>
    );
  }
);
CustomThumb.displayName = 'CustomThumb';

<Slider
  value={sliderValue}
  onChange={handleSliderChange}
  slots={{
    thumb: CustomThumb,
    track: CustomTrack,
    rail: CustomRail,
    valueLabel: CustomValueLabel,
    mark: CustomMark,
    markLabel: CustomMarkLabel,
  }}
  slotProps={{
    thumb: {
      'data-testid': 'custom-thumb',
      sx: { width: 24, height: 24 },
    },
    track: {
      sx: { height: 8, borderRadius: 4 },
    },
    rail: {
      sx: { height: 8, borderRadius: 4, opacity: 0.3 },
    },
    valueLabel: {
      sx: { bgcolor: 'primary.dark', fontSize: 12 },
    },
  }}
  marks={[
    { value: 0, label: '0' },
    { value: 50, label: '50' },
    { value: 100, label: '100' },
  ]}
/>
```

### DatePicker

```tsx
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
import { PickersDay, type PickersDayProps } from '@mui/x-date-pickers/PickersDay';
import { type Dayjs } from 'dayjs';

// Highlight weekends
function CustomDay(props: PickersDayProps<Dayjs>) {
  const { day, ...other } = props;
  const isWeekend = day.day() === 0 || day.day() === 6;

  return (
    <PickersDay
      {...other}
      day={day}
      sx={{
        ...(isWeekend && {
          bgcolor: 'warning.light',
          '&:hover': { bgcolor: 'warning.main' },
        }),
      }}
    />
  );
}

<DatePicker
  label="Select date"
  value={dateValue}
  onChange={handleDateChange}
  slots={{
    day: CustomDay,
    field: CustomField,
    textField: CustomTextField,
    actionBar: CustomActionBar,
    toolbar: CustomToolbar,
    layout: CustomLayout,
  }}
  slotProps={{
    day: {
      sx: { borderRadius: 1 },
    },
    textField: {
      size: 'small',
      variant: 'filled',
      helperText: 'MM/DD/YYYY',
    },
    actionBar: {
      actions: ['clear', 'today', 'accept'],
    },
    toolbar: {
      hidden: false,
      toolbarFormat: 'ddd, MMM D',
    },
    popper: {
      placement: 'bottom-end',
    },
  }}
/>
```

### Dialog

```tsx
import { Dialog, Backdrop, type BackdropProps } from '@mui/material';
import { forwardRef } from 'react';

const BlurredBackdrop = forwardRef<HTMLDivElement, BackdropProps>((props, ref) => (
  <Backdrop
    {...props}
    ref={ref}
    sx={{
      backdropFilter: 'blur(8px)',
      backgroundColor: 'rgba(0, 0, 0, 0.3)',
    }}
  />
));
BlurredBackdrop.displayName = 'BlurredBackdrop';

<Dialog
  open={open}
  onClose={handleClose}
  slots={{
    backdrop: BlurredBackdrop,
    transition: Fade,
  }}
  slotProps={{
    backdrop: {
      timeout: 500,
      'data-testid': 'dialog-backdrop',
    },
    paper: {
      sx: {
        borderRadius: 3,
        boxShadow: 24,
        minWidth: 400,
      },
      elevation: 0,
    },
  }}
>
  <DialogTitle>Confirm Action</DialogTitle>
  <DialogContent>Are you sure?</DialogContent>
</Dialog>
```

### Tooltip

```tsx
import { Tooltip, Popper, type PopperProps } from '@mui/material';
import { forwardRef } from 'react';

const ThemedPopper = forwardRef<HTMLDivElement, PopperProps>((props, ref) => (
  <Popper
    {...props}
    ref={ref}
    sx={{
      '& .MuiTooltip-tooltip': {
        bgcolor: 'primary.dark',
        fontSize: 14,
        borderRadius: 2,
        px: 2,
        py: 1,
      },
      '& .MuiTooltip-arrow': {
        color: 'primary.dark',
      },
    }}
  />
));
ThemedPopper.displayName = 'ThemedPopper';

<Tooltip
  title="Detailed description here"
  arrow
  slots={{
    popper: ThemedPopper,
  }}
  slotProps={{
    popper: {
      modifiers: [{ name: 'offset', options: { offset: [0, -4] } }],
    },
    arrow: {
      sx: { color: 'primary.dark' },
    },
    tooltip: {
      sx: { maxWidth: 300 },
    },
    tran