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

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