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