Skip to content
🚀 Material UI and MUI X v9 are out! Check out the announcement blogpost.
+

Chat - Slot customization

Replace slots across the headless primitives to adapt the Chat surface to a custom design system.

Slot replacement keeps the headless behavior and accessibility model while letting the markup match a product-specific design system.

Large applications that already standardize avatars, typography, and surfaces can adopt this pattern to reuse Chat's interaction and accessibility behavior without rewriting it.

  • Slot replacement across multiple primitive groups
  • slotProps for passing local configuration
  • Owner-state-driven styling hooks
  • Choosing slot replacement instead of rebuilding from headless primitives

The demo below replaces the conversation list, message, and composer slots with custom components driven by owner state:

Brand-adapted shell
The runtime and accessibility behavior stay the same. Only the rendered slots change.
Design review
Header spacing and slot strategy
You
You
Should we keep the default thread header or replace the title slot?
8:34 AM · sent
MUI Guide
MUI Guide
Keep the structure. Replace the title and actions slots so the behavior stays intact.
Marco Diaz
Marco Diaz
That also keeps focus restoration predictable when the active thread changes.
8:52 AM · sent

Key primitives

  • Slot replacement on roots, rows, and leaf subparts
  • Owner-state values such as selected, unread, focused, hasValue, isStreaming, and isGrouped
  • slotProps for passing local configuration into custom components

Choosing slot replacement

  • Replace slots in more than one primitive group, because the slot model behaves consistently across the package.
  • Keep the example grounded in a realistic design-system adaptation rather than a trivial tag swap.
  • Use slot replacement when the shipped behavior is correct; drop down to headless primitives when the structure itself needs to change.

When to use this pattern

Use this pattern when:

  • The Chat's interaction and accessibility behavior is correct as shipped
  • the product markup needs to align with an existing component system
  • styling requires owner-state-aware custom wrappers

This is common in design-system-heavy products where avatars, typography, buttons, surfaces, and layout containers are already standardized across the application.

Key behaviors of the slot model

  • The slot model is consistent across conversation list, message surfaces, composer, and indicators.
  • Owner state is the bridge between shipped behavior and product-specific rendering.
  • Slot replacement is still a structural customization path, not a full runtime rewrite.

See also

API