MUI Headless UI Best Practices

Comprehensive style guide for building headless React component libraries following MUI Base UI patterns. Contains 48 rules across 5 categories, prioritized by impact.

When to Apply

Reference these guidelines when:

• Building headless/unstyled component libraries

• Creating compound components with context-based composition

• Implementing accessible UI primitives with ARIA patterns

• Using render props and className callbacks for styling flexibility

• Writing components that support both controlled and uncontrolled modes

Rule Categories by Priority

Priority Category Impact Prefix

1 Component Patterns CRITICAL comp-

2 Naming Conventions HIGH name-

3 Organization HIGH org-

4 Error Handling HIGH err-

5 Style MEDIUM style-

Quick Reference

1. Component Patterns (CRITICAL)

• comp-forward-ref-named

• Use forwardRef with Named Function

• comp-props-parameter-naming

• Name Props Parameter componentProps

• comp-use-render-element

• Use useRenderElement for DOM Rendering

• comp-context-undefined-default

• Create Context with Undefined Default

• comp-context-error-message

• Context Error Messages with Hierarchy

• comp-use-controlled

• Use useControlled Hook for Dual Modes

• comp-state-memoization

• Memoize State Objects

• comp-context-value-memo

• Memoize Context Provider Values

• comp-plain-function-root

• Plain Function for Non-DOM Roots

• comp-hook-namespace-exports

• Hook Namespace Exports

• comp-props-destructure-order

• Props Destructuring Order

• comp-use-client-directive

• Add use client Directive

2. Naming Conventions (HIGH)

• name-component-naming

• Component Naming as ParentPart

• name-file-matches-export

• File Name Matches Primary Export

• name-directory-kebab-case

• Directory Naming kebab-case

• name-part-directory-lowercase

• Part Directory Naming lowercase

• name-context-suffix

• Context Naming with Suffix

• name-context-hook

• Context Hook as useComponentContext

• name-props-interface

• Props Interface as ComponentProps

• name-state-interface

• State Interface as ComponentState

• name-namespace-type-exports

• Namespace Type Exports

• name-event-type

• Event Type Naming Convention

• name-constants

• Constant Naming SCREAMING_SNAKE_CASE

• name-data-attributes

• Data Attribute Naming lowercase

• name-hooks

• Hook Naming with use Prefix

• name-refs

• Ref Variable Naming with Suffix

• name-handlers

• Handler Naming Convention

3. Organization (HIGH)

• org-component-directory

• Component Directory Structure

• org-dual-barrel-exports

• Dual Barrel Export Pattern

• org-test-colocation

• Test File Colocation

• org-context-placement

• Context File Placement

• org-data-attributes-file

• Data Attributes Documentation File

• org-state-attributes-mapping

• State Attributes Mapping File

• org-css-vars-file

• CSS Variables Documentation File

• org-package-exports

• Package-Level Wildcard Exports

4. Error Handling (HIGH)

• err-dev-only-warnings

• Development-Only Warnings

• err-deduplicated-warnings

• Deduplicated Warning Messages

• err-message-prefix

• Message Prefix Standard

• err-context-error-guidance

• Context Error Guidance

• err-prop-validation-timing

• Prop Validation Timing

• err-cancelable-events

• Cancelable Event Pattern

• err-event-reason-constants

• Event Reason Constants

• err-typed-event-reasons

• Type-Safe Event Reasons

5. Style (MEDIUM)

• style-react-import

• React Import as Namespace

• style-internal-imports

• Internal Import Paths

• style-explicit-undefined

• Explicit Undefined in Prop Types

• style-default-values

• Default Values in Destructuring

• style-jsdoc-documentation

• JSDoc Documentation

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

• Example: comp-forward-ref-named

• Example: org-component-directory

Source

Extracted from MUI Base UI codebase on 2026-01-17.

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md