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