2nd/10_Wiki/Topic_Programming/Coding/React_Headless_UI_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
react-headless-ui-patterns	Headless UI — Radix / Headless UI / 자체 Build	Coding	draft	B	conceptual	2026-05-09	2026-05-09	react headless radix accessibility vibe-coding	language applicable_to TS / React Frontend		Radix UI Headless UI shadcn/ui render props compound components

Headless UI

행동 + a11y 만 제공, 스타일은 너의 것. Radix UI / Headless UI (Tailwind Labs) / Ariakit. shadcn/ui = Radix 위에 Tailwind. 직접 dropdown / dialog / combobox 만들지 말 것.

📖 핵심 개념

• Behavior: focus / keyboard / portal / aria.
• Compound components: <Dialog><Dialog.Trigger>...<Dialog.Content> 패턴.
• Render prop / asChild: child element 가 행동 흡수.
• Controlled vs uncontrolled.

💻 코드 패턴

Radix Dialog

import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Root>
  <Dialog.Trigger asChild>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
    <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6 rounded-md">
      <Dialog.Title>Confirm</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <div className="flex gap-2 justify-end">
        <Dialog.Close asChild><Button variant="ghost">Cancel</Button></Dialog.Close>
        <Button onClick={handleConfirm}>Yes</Button>
      </div>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

자동 처리: focus trap, ESC, click-outside, scroll lock, aria.

Radix Dropdown

import * as Menu from '@radix-ui/react-dropdown-menu';

<Menu.Root>
  <Menu.Trigger asChild><Button>Menu</Button></Menu.Trigger>
  <Menu.Portal>
    <Menu.Content className="bg-white rounded shadow p-1" sideOffset={4}>
      <Menu.Item onSelect={() => navigate('/profile')}>Profile</Menu.Item>
      <Menu.Item onSelect={logout}>Sign out</Menu.Item>
      <Menu.Separator className="h-px bg-gray-200 my-1" />
      <Menu.Sub>
        <Menu.SubTrigger>More →</Menu.SubTrigger>
        <Menu.SubContent>...</Menu.SubContent>
      </Menu.Sub>
    </Menu.Content>
  </Menu.Portal>
</Menu.Root>

Headless UI Combobox (autocomplete)

import { Combobox, ComboboxInput, ComboboxOptions, ComboboxOption } from '@headlessui/react';

const [q, setQ] = useState('');
const filtered = q ? items.filter(i => i.name.includes(q)) : items;

<Combobox value={selected} onChange={setSelected}>
  <ComboboxInput onChange={(e) => setQ(e.target.value)} displayValue={(i: Item) => i?.name} />
  <ComboboxOptions>
    {filtered.map(i => <ComboboxOption key={i.id} value={i}>{i.name}</ComboboxOption>)}
  </ComboboxOptions>
</Combobox>

asChild 패턴 (Radix)

<Tooltip.Trigger asChild>
  <button className="...">My button</button>
</Tooltip.Trigger>
// 새 element 안 만들고 child 에 trigger props 합침

요구사항: child 가 ref 를 받아야 → forwardRef 컴포넌트 사용.

Ariakit Toolbar (잘 쓰는 라이브러리)

import * as Ariakit from '@ariakit/react';

const toolbar = Ariakit.useToolbarStore();
<Ariakit.Toolbar store={toolbar}>
  <Ariakit.ToolbarItem>Bold</Ariakit.ToolbarItem>
  <Ariakit.ToolbarItem>Italic</Ariakit.ToolbarItem>
</Ariakit.Toolbar>

shadcn/ui (Radix + Tailwind, copy-paste)

npx shadcn@latest add dialog
# 컴포넌트 직접 코드베이스에 복사 — 너가 소유 + 수정 자유

컴파운드 패턴 자체 구현

const TabsContext = createContext<TabsCtx | null>(null);

function Tabs({ defaultValue, children }: ...) {
  const [value, setValue] = useState(defaultValue);
  return <TabsContext.Provider value={{ value, setValue }}>{children}</TabsContext.Provider>;
}
function TabsTrigger({ value, children }: ...) {
  const ctx = useContext(TabsContext)!;
  return <button onClick={() => ctx.setValue(value)} aria-selected={ctx.value === value}>{children}</button>;
}
function TabsContent({ value, children }: ...) {
  const ctx = useContext(TabsContext)!;
  return ctx.value === value ? <div>{children}</div> : null;
}

Tabs.Trigger = TabsTrigger;
Tabs.Content = TabsContent;

🤔 의사결정 기준

컴포넌트	추천
Modal / Dialog	Radix Dialog
Dropdown / Popover	Radix DropdownMenu / Popover
Combobox / Listbox	Headless UI / Ariakit
Tabs	Radix Tabs
Toast	Sonner / Radix Toast
Date picker	react-day-picker
Drag & drop	dnd-kit
자체 디자인 시스템	shadcn 카피 + 변경

❌ 안티패턴

• 자체 dialog (focus trap 없음): a11y / 키보드 깨짐. 라이브러리 사용.
• Portal 안 쓰면: z-index / overflow 지옥.
• asChild 사용 시 child 가 forwardRef X: ref 전달 안 됨.
• Animation 직접: Radix data-state + Tailwind animate 가 깔끔.
• Controlled / uncontrolled 혼용: 둘 중 하나.
• 모든 컴포넌트 npm 라이브러리 의존: 무거움. 자주 쓰는 건 자체.
• Radix UI css 미적용: 기본 unstyled. Tailwind/CSS 직접.

🤖 LLM 활용 힌트

• Radix + Tailwind + shadcn/ui 표준 조합.
• Combobox = Headless UI / Ariakit.
• 자체 자체 일 때만 — focus trap / a11y 제대로 구현해야.

🔗 관련 문서

• Frontend_Tailwind_Architecture
• Frontend_A11y_Testing
• React_Component_Composition