Tags Input
Tags Input (태그 입력)
태그 생성, 삭제, 키보드 탐색 같은 기능으로 여러 값을 태그 형태로 입력받는 컴포넌트예요. 이메일 목록이나 키워드 입력에 유용해요.
출처: 문서
본문
TagsInput은 여러 값을 태그로 입력받는 컴포넌트예요. 태그 생성·삭제·키보드 탐색 같은 기능을 제공해요. <ExampleTabs name="tags-input-basic" />
사용법 (Usage)
import { TagsInput } from "@chakra-ui/react"
<TagsInput.Root>
<TagsInput.Label />
<TagsInput.Control>
<TagsInput.Item>
<TagsInput.ItemPreview>
<TagsInput.ItemText />
<TagsInput.ItemDeleteTrigger />
</TagsInput.ItemPreview>
<TagsInput.ItemInput />
</TagsInput.Item>
<TagsInput.Input />
</TagsInput.Control>
</TagsInput.Root>
단축 표현 (Shortcuts)
TagsInput 컴포넌트는 흔한 사용 사례를 위한 단축 표현도 제공해요.
TagsInputItems
TagsInputItems 단축 표현은 현재 값을 기준으로 모든 태그 아이템을 자동으로 렌더링해 줘요.
이렇게 쓰는 게 동작하고,
<TagsInput.Context>
{({ value }) =>
value.map((tag, index) => (
<TagsInput.Item key={index} index={index} value={tag}>
<TagsInput.ItemPreview>
<TagsInput.ItemText>{tag}</TagsInput.ItemText>
<TagsInput.ItemDeleteTrigger />
</TagsInput.ItemPreview>
<TagsInput.ItemInput />
</TagsInput.Item>
))
}
</TagsInput.Context>
아이템을 커스터마이즈할 필요가 없다면 이렇게 더 간결하게 쓸 수 있어요.
<TagsInput.Items />
예시 (Examples)
크기 (Sizes)
size prop으로 태그 입력의 크기를 조절할 수 있어요.
변형 (Variants)
variant prop으로 태그 입력의 시각적 스타일을 바꿀 수 있어요.
제어 (Controlled)
value와 onValueChange prop으로 태그를 프로그래밍 방식으로 제어할 수 있어요.
스토어 (Store)
태그 입력을 제어하는 또 다른 방법은 RootProvider 컴포넌트와 useTagsInput 스토어 훅을 사용하는 거예요. 이렇게 하면 컴포넌트 바깥에서도 상태와 메서드에 접근할 수 있어요.
RootProvider + useTagsInput또는Root중 하나만 사용하세요. 둘 다 쓰면 안 돼요.
최대 태그 수 (Max Tags)
TagsInput.Root 컴포넌트에 max prop을 넘기면 추가할 수 있는 태그 수를 제한할 수 있어요.
태그 편집 (Editable Tags)
editable prop으로 기존 태그를 더블 클릭하거나 하이라이트된 상태에서 Enter를 눌러 인라인 편집할 수 있게 해요. 사용자가 태그 값을 빠르게 업데이트할 수 있어요.
태그 검증 (Validate Tag)
validate prop으로 커스텀 검증 규칙을 구현할 수 있어요. 검증을 통과한 태그만 추가돼요.
비활성화 (Disabled)
disabled prop으로 태그 입력을 비활성화해 사용자 상호작용을 막을 수 있어요.
읽기 전용 (Readonly)
readOnly prop으로 태그 입력을 읽기 전용으로 만들 수 있어요. 포커스는 가능하지만 수정할 수는 없어요.
오류 상태 (Invalid)
TagsInput.Root 컴포넌트에 invalid prop을 넘기면 오류 메시지와 함께 태그 입력을 오류 상태로 표시할 수 있어요.
필드 (Field)
TagsInput.Root를 Field 컴포넌트와 조합해 라벨, 도움말 텍스트, 오류 메시지를 추가하는 예시예요.
폼 (Form)
TagsInput.Root를 form과 조합해 구조화된 데이터를 수집하고 제출을 처리하는 예시예요.
붙여넣기 (Paste)
TagsInput.Root 컴포넌트에 addOnPaste prop을 넘기면 사용자가 여러 값을 한 번에 붙여넣고, 구분자(delimiter)를 기준으로 자동으로 개별 태그로 나눌 수 있어요.
값 정리 (Sanitize Values)
sanitizeValue prop으로 값을 추가하기 전에 정규화할 수 있어요(예: 공백 제거, 소문자 변환).
블러 동작 (Blur Behavior)
blurBehavior prop으로 입력이 포커스를 잃었을 때 어떻게 동작할지 구성할 수 있어요(예: 현재 입력 값으로 태그 자동 생성).
커스텀 구분자 (Custom Delimiter)
delimiter prop으로 쉼표, 세미콜론, 공백 같은 커스텀 구분자를 사용해 입력하면서 새 태그를 만들 수 있어요.
색상 (Colors)
태그 값에 따라 각 태그에 다른 색상을 지정하는 예시예요.
콤보박스 (Combobox)
TagsInput 컴포넌트를 Combobox 컴포넌트와 조합해 사전 정의된 태그 목록에서 선택할 수 있는 태그 입력을 만드는 예시예요.
Props
TagsInput 컴포넌트의 Root, Item 파트 props에 대한 상세 정보는 공식 문서의 PropTable를 참고하세요.