Issue #7: Content vs Popup Naming

Error: "Property 'Content' does not exist on Dialog" Source: Radix migration issue Why It Happens: Radix uses Content, Base UI uses Popup Prevention:

// ❌ Wrong - Radix naming ...

// ✅ Correct - Base UI naming ...

Issue #8: Overlay vs Backdrop Naming

Error: "Property 'Overlay' does not exist on Dialog" Source: Radix migration issue Why It Happens: Radix uses Overlay, Base UI uses Backdrop Prevention:

// ❌ Wrong - Radix naming

// ✅ Correct - Base UI naming

Issue #9: Disabled Button Tooltip Not Showing

Error: Tooltip doesn't show on disabled buttons Source: https://github.com/mui/base-ui/issues/567 Why It Happens: Disabled elements don't fire pointer events Prevention:

// ❌ Wrong - tooltip won't show } />

// ✅ Correct - wrap in span (

)} />

Issue #10: Select with Empty String Value

Error: Screen reader doesn't announce selected value Source: https://github.com/mui/base-ui/issues/678 Why It Happens: Empty string breaks ARIA labeling Prevention:

// ❌ Wrong - empty string Any

// ✅ Correct - sentinel value Any

Critical Rules Always Do

✅ Spread props from render functions -

✅ Use Positioner for popups - Select, Popover, Tooltip ✅ Wrap in Portal for modals - Dialog, Popover ✅ Use alignment not align - Base UI API, not Radix ✅ Style Arrow explicitly - No default arrow styles ✅ Test keyboard navigation - Tab, Escape, Arrow keys ✅ Verify screen reader - Check ARIA attributes applied

Never Do

❌ Use asChild pattern - Base UI doesn't support it ❌ Forget prop spreading - {...props} is required ❌ Skip Positioner - Floating components need it ❌ Expect automatic Portal - Must be explicit ❌ Use Radix naming - Content→Popup, Overlay→Backdrop, align→alignment ❌ Use empty string values - Breaks accessibility ❌ Assume API is stable - Beta may have breaking changes before v1.0

Configuration Files Reference vite.config.ts (Full Example) import { defineConfig } from "vite"; import react from "@vitejs/plugin-react";

export default defineConfig({ plugins: [react()], resolve: { alias: { "@": "/src", }, }, // Base UI works with any Vite setup - no special config needed });

Why these settings:

Base UI has no special Vite requirements Works with standard React plugin Compatible with Tailwind v4, CSS Modules, Emotion, etc. Tree-shakeable imports tsconfig.json (Full Example) { "compilerOptions": { "target": "ES2020", "useDefineForClassFields": true, "lib": ["ES2020", "DOM", "DOM.Iterable"], "module": "ESNext", "skipLibCheck": true,

"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "react-jsx",

"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,

"paths": {
  "@/*": ["./src/*"]
}

}, "include": ["src"], "references": [{ "path": "./tsconfig.node.json" }] }

Why these settings:

Standard Vite + React TypeScript config Base UI has excellent TypeScript support Render prop pattern fully typed Common Patterns Pattern 1: Dialog with Form Submission import { Dialog } from "@base-ui-components/react/dialog"; import { useState } from "react";

export function FormDialog() { const [open, setOpen] = useState(false); const [name, setName] = useState("");

const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); console.log("Submitted:", name); setOpen(false); };

return ( (

Open Form )} />

  <Dialog.Portal>
    <Dialog.Backdrop
      render={(props) => <div {...props} className="fixed inset-0 bg-black/50" />}
    />

    <Dialog.Popup
      render={(props) => (
        <div
          {...props}
          className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 bg-white rounded-lg shadow-xl p-6 w-full max-w-md"
        >
          <Dialog.Title
            render={(titleProps) => (
              <h2 {...titleProps} className="text-2xl font-bold mb-4">
                Enter Your Name
              </h2>
            )}
          />

          <form onSubmit={handleSubmit}>
            <input
              type="text"
              value={name}
              onChange={(e) => setName(e.target.value)}
              className="w-full px-3 py-2 border rounded mb-4"
              autoFocus
            />

            <div className="flex justify-end gap-2">
              <Dialog.Close
                render={(closeProps) => (
                  <button {...closeProps} type="button" className="px-4 py-2 border rounded">
                    Cancel
                  </button>
                )}
              />
              <button type="submit" className="px-4 py-2 bg-blue-600 text-white rounded">
                Submit
              </button>
            </div>
          </form>
        </div>
      )}
    />
  </Dialog.Portal>
</Dialog.Root>

); }

When to use: Forms in modals, user input dialogs

Pattern 2: Searchable Select import { Select } from "@base-ui-components/react/select"; import { useState } from "react";

const options = [ { value: "react", label: "React" }, { value: "vue", label: "Vue" }, { value: "angular", label: "Angular" }, ];

export function SearchableSelect() { const [value, setValue] = useState(""); const [search, setSearch] = useState("");

const filtered = options.filter((opt) => opt.label.toLowerCase().includes(search.toLowerCase()) );

return ( ( ( {options.find((opt) => opt.value === value)?.label || "Select..."} )} /> ▼ )} />

  <Select.Positioner side="bottom" alignment="start">
    <Select.Portal>
      <Select.Popup
        render={(props) => (
          <div {...props} className="w-64 bg-white border rounded shadow-lg">
            <div className="p-2 border-b">
              <input
                type="text"
                value={search}
                onChange={(e) => setSearch(e.target.value)}
                placeholder="Search..."
                className="w-full px-3 py-2 border rounded"
              />
            </div>
            <div className="max-h-60 overflow-y-auto">
              {filtered.map((option) => (
                <Select.Option
                  key={option.value}
                  value={option.value}
                  render={(optionProps) => (
                    <div
                      {...optionProps}
                      className="px-4 py-2 cursor-pointer hover:bg-gray-100 data-[selected]:bg-blue-600 data-[selected]:text-white"
                    >
                      {option.label}
                    </div>
                  )}
                />
              ))}
            </div>
          </div>
        )}
      />
    </Select.Portal>
  </Select.Positioner>
</Select.Root>

); }

When to use: Long option lists, type-ahead filtering

Pattern 3: Number Field with Currency Formatting import { NumberField } from "@base-ui-components/react/number-field"; import { useState } from "react";

export function CurrencyInput() { const [price, setPrice] = useState(9.99);

return (

    <div className="flex items-center gap-2">
      <NumberField.Decrement
        render={(props) => (
          <button {...props} className="w-8 h-8 bg-gray-200 rounded">
            −
          </button>
        )}
      />

      <NumberField.Input
        render={(props) => (
          <input
            {...props}
            className="w-32 px-3 py-2 text-center border rounded"
          />
        )}
      />

      <NumberField.Increment
        render={(props) => (
          <button {...props} className="w-8 h-8 bg-gray-200 rounded">
            +
          </button>
        )}
      />
    </div>
  </div>
</NumberField.Root>