mui-base

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