ChipGroup#
단일 또는 다중 선택을 지원하는 칩 그룹 컴포넌트입니다. Wrap/Scroll 레이아웃,
최대 선택 수 제한, 타이틀/힌트 헤더를 지원합니다. 칩 자체는 Chip 으로
렌더링되며 사용자는 chipBuilder 를 통해 다른 chip variant 도 사용할 수
있습니다.
Live Preview#
default
Web
Flutter
React
Swift
Kotlin
Flutter
Loading Flutter...
class ChipGroupDefaultExample extends StatefulComponent {
const ChipGroupDefaultExample({super.key});
@override
State<ChipGroupDefaultExample> createState() =>
_ChipGroupDefaultExampleState();
}
class _ChipGroupDefaultExampleState extends State<ChipGroupDefaultExample> {
Set<String> _selected = const {'Flutter'};
@override
Component build(BuildContext context) {
return ChipGroup<String>(
items: const ['Flutter', 'React', 'Swift', 'Kotlin'],
initialValue: _selected,
selectionMode: CoreChipGroupSelectionMode.multi,
onChanged: (next) => setState(() => _selected = next),
chipBuilder:
(item, {required selected, required enabled, required onTap}) =>
Chip(
label: item,
selected: selected,
enabled: enabled,
chipColor: CoreChipColor.primary,
onTap: onTap,
),
);
}
}
class ChipGroupDefaultExample extends StatefulWidget {
const ChipGroupDefaultExample({super.key});
@override
State<ChipGroupDefaultExample> createState() =>
_ChipGroupDefaultExampleState();
}
class _ChipGroupDefaultExampleState extends State<ChipGroupDefaultExample> {
Set<String> _selected = const {'Flutter'};
@override
Widget build(BuildContext context) {
return ChipGroup<String>(
items: const ['Flutter', 'React', 'Swift', 'Kotlin'],
initialValue: _selected,
selectionMode: CoreChipGroupSelectionMode.multi,
onChanged: (next) => setState(() => _selected = next),
chipBuilder: (item, {required selected, required enabled, required onTap}) =>
Chip(
label: item,
selected: selected,
enabled: enabled,
chipColor: CoreChipColor.primary,
onTap: onTap,
),
);
}
}
scroll
Web
All
Frontend
Backend
Mobile
Design
DevOps
Data
AI/ML
Flutter
Loading Flutter...
class ChipGroupScrollExample extends StatefulComponent {
const ChipGroupScrollExample({super.key});
@override
State<ChipGroupScrollExample> createState() =>
_ChipGroupScrollExampleState();
}
class _ChipGroupScrollExampleState extends State<ChipGroupScrollExample> {
Set<String> _selected = const {};
@override
Component build(BuildContext context) {
return ChipGroup<String>(
items: const [
'All',
'Frontend',
'Backend',
'Mobile',
'Design',
'DevOps',
'Data',
'AI/ML',
],
layout: CoreChipGroupLayout.scroll,
selectionMode: CoreChipGroupSelectionMode.single,
initialValue: _selected,
onChanged: (next) => setState(() => _selected = next),
chipBuilder:
(item, {required selected, required enabled, required onTap}) =>
Chip(
label: item,
selected: selected,
enabled: enabled,
chipColor: CoreChipColor.neutral,
onTap: onTap,
),
);
}
}
class ChipGroupScrollExample extends StatefulWidget {
const ChipGroupScrollExample({super.key});
@override
State<ChipGroupScrollExample> createState() =>
_ChipGroupScrollExampleState();
}
class _ChipGroupScrollExampleState extends State<ChipGroupScrollExample> {
Set<String> _selected = const {};
@override
Widget build(BuildContext context) {
return ChipGroup<String>(
items: const [
'All',
'Frontend',
'Backend',
'Mobile',
'Design',
'DevOps',
'Data',
'AI/ML',
],
layout: CoreChipGroupLayout.scroll,
selectionMode: CoreChipGroupSelectionMode.single,
initialValue: _selected,
onChanged: (next) => setState(() => _selected = next),
chipBuilder: (item, {required selected, required enabled, required onTap}) =>
Chip(
label: item,
selected: selected,
enabled: enabled,
chipColor: CoreChipColor.neutral,
onTap: onTap,
),
);
}
}
사용 시기 (When to Use)#
이 컴포넌트를 사용하세요:
- 여러 태그/카테고리 중 하나 또는 여러 개를 선택할 때
- 필터 옵션을 칩 형태로 제공할 때
- 가로 스크롤 가능한 태그 목록이 필요할 때
대신 다른 컴포넌트를 사용하세요:
RadioGroup: 라디오 버튼 형태의 단일 선택이 필요할 때Select: 드롭다운 형태의 선택이 필요할 때ChipInput: 사용자가 직접 텍스트를 입력하여 칩을 생성할 때
Props / Parameters#
| 속성 | 타입 | 기본값 | 설명 |
|---|---|---|---|
items | List<T> | 필수 | 표시할 아이템 목록 |
chipBuilder |
CoreChipGroupItemBuilder<T, W> |
필수 | 각 칩 위젯/컴포넌트 빌더 |
selectionMode |
CoreChipGroupSelectionMode? |
multi |
단일/다중 선택 모드 |
layout |
CoreChipGroupLayout? |
wrap |
wrap / scroll 레이아웃 |
initialValue |
Set<T>? |
null |
초기 선택 아이템 |
onChanged |
void Function(Set<T>)? |
null |
선택 변경 콜백 |
allowDeselect |
bool |
true |
single 모드에서 재탭 시 해제 허용 |
maxSelection |
int? |
null |
최대 선택 수 |
maxSelectionBehavior |
CoreChipGroupMaxBehavior? |
disableRest |
최대 도달 시 동작 |
minSelection |
int? |
null |
최소 선택 수 (해제 차단) |
title | W? | null | 헤더 타이틀 |
selectionHint |
W? |
null |
헤더 힌트 (예: 선택 개수 표시) |
showFade |
bool |
true |
scroll 모드에서 가장자리 페이드 표시 |
chipGroupStyle |
CoreChipGroupStyle? |
null |
인스턴스 스타일 슬롯 (itemSpacing/rowSpacing/titleGapStyle/fadeWidth/fadeColor + 타이틀/힌트 텍스트 스타일) |
CoreChipGroupStyle#
chipGroupStyle 슬롯에 전달하는 스타일. 모든 시각 chrome 은 여기로 모인다 (Epic #1302 / #1370).
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
itemSpacing |
double? |
8 |
칩 간 가로 간격 (px, pre-scaling) —
Wrap.spacing
/
Row.spacing
/
column-gap
네이티브 스칼라
|
rowSpacing |
double? |
8 |
wrap 행 간 세로 간격 (px, pre-scaling) |
titleGapStyle |
CoreGapStyle? |
size: 8 |
타이틀 행과 칩 영역 사이 세로 간격 슬롯 |
fadeWidth |
double? |
32 |
scroll 모드 가장자리 페이드 폭 (px, pre-scaling) |
fadeColor |
CoreColor? |
surface |
페이드 색상 |
titleTextStyle |
CoreTextStyle? |
null |
타이틀 텍스트 스타일 (color/fontWeight/fontSize/lineHeight/letterSpacing/fontFamily) |
selectionHintTextStyle |
CoreTextStyle? |
null |
힌트 텍스트 스타일 |
예제#
ChipGroup<String>(
items: const ['Flutter', 'React', 'Swift', 'Kotlin'],
selectionMode: CoreChipGroupSelectionMode.multi,
onChanged: (next) => print(next),
chipBuilder:
(item, {required selected, required enabled, required onTap}) =>
Chip(
label: item,
selected: selected,
chipColor: CoreChipColor.primary,
onTap: onTap,
),
)