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 SCREAMINGSNAKECASE
• 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](references/_sections.md) - Category structure and impact levels
• [Rule template](assets/templates/_template.md) - Template for adding new rules
• Example: [comp-forward-ref-named](references/comp-forward-ref-named.md)
• Example: [org-component-directory](references/org-component-directory.md)

Source

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

Full Compiled Document

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