Skip to Content
ComponentsFoundationItem

Item

리스트 형태로 정보를 구조화하여 표시하는 컴포넌트

개요

Item 컴포넌트는 아이콘, 제목, 설명, 액션 등을 하나의 행(row) 형태로 구성하여 리스트 UI를 만듭니다. Composable 구조로 필요한 영역만 조합하여 사용할 수 있습니다.

주요 특징

  • ✅ Variant 지원: default, outline, muted 세 가지 시각적 스타일
  • ✅ Size 지원: default, sm, xs 세 가지 크기
  • ✅ 미디어 영역: 아이콘, 이미지 등 시각 요소 배치
  • ✅ 액션 영역: 버튼, 링크 등 인터랙션 요소 배치
  • ✅ 헤더/푸터: 상단/하단 영역으로 구조화
  • ✅ render prop: base-ui의 render prop으로 커스텀 렌더링 지원
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

기본 상태

기본 아이템

기본 아이템 설명입니다.

Variants

Default

투명한 보더의 기본 스타일

Outline

보더가 보이는 아웃라인 스타일

Muted

배경색이 있는 뮤트 스타일

Variant 설명

Variant설명사용 사례
default투명 보더, 배경 없음일반적인 리스트 아이템
outline보더 표시시각적으로 구분이 필요한 경우
muted투명 보더, 반투명 배경색비활성/보조 정보 표시

Sizes

Default Size

기본 크기 아이템

Small Size

작은 크기 아이템

Extra Small Size

매우 작은 크기 아이템

사용 예시

미디어 아이콘

아이콘을 함께 표시하여 항목의 의미를 시각적으로 전달합니다.

이메일 알림

새로운 이메일 알림을 받습니다.

푸시 알림

모바일 푸시 알림을 받습니다.

알림 설정

알림 환경을 설정합니다.

헤더/푸터 + 액션

헤더에 제목, 푸터에 메타 정보, 우측에 액션 버튼을 배치하는 구조입니다.

공지사항

시스템 정기 점검 안내입니다.

2025.01.01관리자

액션 버튼

우측에 액션 버튼을 배치하여 편집, 삭제 등 인터랙션을 제공합니다.

문서 제목

문서 설명입니다.

구분선

ItemSeparator로 아이템 사이에 구분선을 추가합니다.

첫 번째 아이템
두 번째 아이템
세 번째 아이템

render prop

base-ui의 render prop을 사용하여 Item을 다른 요소로 렌더링할 수 있습니다.

링크 아이템

클릭하면 이동합니다.

API Reference

컴포넌트 구조

컴포넌트HTML 요소Description
ItemGroup<div>리스트 컨테이너 (role=list)
Item<div>아이템 행
ItemMedia<div>아이콘/이미지 영역
ItemContent<div>제목 + 설명 콘텐츠 영역
ItemTitle<div>아이템 제목
ItemDescription<p>아이템 설명
ItemActions<div>우측 액션 영역
ItemHeader<div>상단 헤더 영역 (full-width)
ItemFooter<div>하단 푸터 영역 (full-width)
ItemSeparator<Separator>아이템 간 구분선

Item Props

PropTypeDefaultDescription
variant"default" | "outline" | "muted""default"시각적 스타일
size"default" | "sm" | "xs""default"크기
renderReact.ReactElement-커스텀 렌더링 요소 (base-ui)
classNamestring-추가 CSS 클래스

ItemMedia Props

PropTypeDefaultDescription
variant"default" | "icon" | "image""default"미디어 타입
classNamestring-추가 CSS 클래스

기본 사용법

import {
  Item,
  ItemGroup,
  ItemMedia,
  ItemContent,
  ItemTitle,
  ItemDescription,
  ItemActions,
  ItemHeader,
  ItemFooter,
  ItemSeparator,
} from "@vortex/ui-foundation"
 
<ItemGroup>
  <Item variant="outline">
    <ItemMedia variant="icon">
      <FileText className="size-4" />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>제목</ItemTitle>
      <ItemDescription>설명</ItemDescription>
    </ItemContent>
    <ItemActions>
      <Button size="sm">액션</Button>
    </ItemActions>
  </Item>
</ItemGroup>

접근성

ARIA 속성

  • ItemGroup은 role="list"를 가집니다.

권장 사항

  • ✅ 의미 있는 제목으로 항목의 목적을 명확히 전달
  • ✅ 액션 버튼에 명확한 레이블 제공
  • ✅ render prop으로 <a> 렌더링 시 접근 가능한 href 제공
  • ❌ 클릭 가능한 아이템에 중첩 인터랙션 요소 주의

관련 컴포넌트

Last updated on
InputNumberKanban