Item
리스트 아이템을 구성하는 컴파운드 컴포넌트
개요
Item 컴포넌트 패밀리는 미디어, 콘텐츠, 액션 등을 조합하여 다양한 형태의 리스트 아이템을 구성합니다. render prop을 통해 링크 등 다른 요소로 렌더링할 수 있습니다.
주요 특징
- ✅ 컴파운드 컴포넌트: ItemMedia, ItemContent, ItemActions 등 유연한 슬롯 구성
- ✅ Variants: default, outline, muted 3가지 시각적 스타일
- ✅ Sizes: default, sm, xs 3단계 크기
- ✅ render prop: base-ui useRender 기반으로
<a>,<button>등으로 렌더링 가능 - ✅ 접근성: ItemGroup에
role="list"자동 적용 - ✅ 디자인 토큰: 테마 커스터마이징 지원
Variants
Item은 3가지 variant를 지원합니다.
Preview
투명 배경, 테두리 없음
테두리가 있는 스타일
음소거 배경 스타일
Variant 설명
| Variant | 설명 | 사용 사례 |
|---|---|---|
| default | 투명 배경, 테두리 없음 | 기본 리스트 아이템 |
| outline | 테두리 있는 스타일 | 카드형 리스트 |
| muted | 음소거 배경 | 강조/선택된 항목 |
Sizes
Item은 3가지 크기를 지원합니다.
Preview
기본 크기의 아이템입니다.
작은 크기의 아이템입니다.
사용 예시
아이콘 미디어
ItemMedia의 variant="icon"으로 아이콘 배경 박스를 표시합니다.
Preview
푸시 알림 및 이메일 알림을 관리합니다.
비밀번호, 보안 및 개인정보를 관리합니다.
이미지 미디어
ItemMedia의 variant="image"로 이미지를 표시합니다.
Preview
링크로 렌더링
render prop으로 Item을 <a> 태그로 렌더링합니다.
액션 버튼
ItemActions에 버튼을 배치합니다.
Preview
v2.0에서 추가된 새로운 기능을 확인하세요.
ItemSeparator
ItemGroup 내부에서 아이템 사이에 구분선을 추가합니다.
Preview
개인 정보를 관리합니다.
앱 설정을 변경합니다.
API Reference
Item
리스트 아이템의 핵심 래퍼입니다. base-ui useRender 기반으로 render prop을 지원합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "default" | "outline" | "muted" | "default" | 시각적 스타일 |
size | "default" | "sm" | "xs" | "default" | 크기 |
render | React.ReactElement | - | 렌더링할 요소 (예: <a />) |
className | string | - | 추가 CSS 클래스 |
ItemGroup
Item을 묶는 리스트 컨테이너입니다. role="list"가 자동 적용됩니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
ItemMedia
아이콘이나 이미지를 표시하는 미디어 영역입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "default" | "icon" | "image" | "default" | 미디어 타입 |
className | string | - | 추가 CSS 클래스 |
ItemContent
제목과 설명을 감싸는 flex column 컨테이너입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
ItemTitle
아이템의 제목을 표시합니다. 한 줄로 말줄임(line-clamp-1)이 적용됩니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
ItemDescription
아이템의 설명 텍스트를 표시합니다. 두 줄까지 표시(line-clamp-2)됩니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
ItemActions
아이템 우측의 액션 영역입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
ItemHeader
아이템 전체 너비를 차지하는 상단 영역입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
ItemFooter
아이템 전체 너비를 차지하는 하단 영역입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
ItemSeparator
아이템 사이에 시각적 구분선을 추가합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
기본 사용법
import {
Item,
ItemGroup,
ItemMedia,
ItemContent,
ItemTitle,
ItemDescription,
ItemActions,
ItemSeparator,
} from "@vortex/ui-foundation"
;<ItemGroup>
<Item variant="outline">
<ItemMedia variant="icon">
<Bell />
</ItemMedia>
<ItemContent>
<ItemTitle>제목</ItemTitle>
<ItemDescription>설명 텍스트</ItemDescription>
</ItemContent>
<ItemActions>
<Button variant="outline" size="sm">
액션
</Button>
</ItemActions>
</Item>
</ItemGroup>접근성
시맨틱 마크업
ItemGroup→role="list"자동 적용renderprop으로<a>태그 렌더링 시 포커스 링 자동 적용
권장 사항
- ✅ 클릭 가능한 아이템은
render={<a href="..." />}사용 - ✅ 이미지에 적절한
alt속성 제공 - ✅ 액션 버튼에 명확한 라벨 제공
- ❌
<div onClick>대신renderprop으로 시맨틱 요소 사용