---
title: "PillGroup"
description: "A pill-style single/multiple selection group supporting string and object items, quantity constraints, field mapping, and slot customization."
canonical_url: "https://nuxt.mhaibaraai.cn/en/docs/components/pill-group"
---
# PillGroup
> A pill-style single/multiple selection group supporting string and object items, quantity constraints, field mapping, and slot customization.
## Introduction
`MPillGroup` is a pill-style option group component supporting both single and multiple selection. It accepts string arrays or object arrays as items, maps business object fields via `labelKey`, `valueKey`, and `descriptionKey`, and supports quantity constraints, per-item semantic colors, active/inactive style differentiation, and slot customization.
## Usage
Pass a string array to generate single-select pills. The selected value is written directly to v-model:
```vue
```
### `items` Structured Items
Object `items` can render composite content via `label`, `description`, and `icon`, while preserving the original object as the value:
```vue
```
### `multiple` Multiple Selection Mode
When `multiple` is enabled, `modelValue` becomes an array. Use `valueKey` to save only a stable field as the selected value:
```vue
```
### `deselectable` Single Deselect
`deselectable` allows clicking the current item again to clear the selection — useful for optional filter conditions (ignored in multiple mode):
```vue
```
### `orientation` Layout Direction
Setting `orientation` to `vertical` stacks items vertically — suited for longer descriptions or narrow containers:
```vue
```
### `activeVariant` Active Style
`activeVariant` and `inactiveVariant` control the visual variant for selected and unselected states respectively:
```vue
```
### `size` Size
Use `size` to switch pill sizes. When placed inside `UFormField`, the size is automatically inherited from context:
```vue
```
### `color` Primary Color
Use `color` to set the component's primary color, making it easier to coordinate with external `UFieldGroup` or button groups:
```vue
```
### `min` and `max` Quantity Constraints
`min` and `max` constrain the number of multiple selections: unselected items become grayed out at the max, and selected items cannot be deselected at the min:
```vue
```
### `labelKey` Display Field
`labelKey` specifies the field to read from the business object for display. Falls back to `label` if not set:
```vue
```
### `valueKey` Value Field
`valueKey` specifies the field written back to `modelValue`, making it easy to save only a stable id rather than the entire object:
```vue
```
### `color` Per-Item Semantic Color
Each item can carry an independent `color`, applied per item at render time to express status differences:
```vue
```
### `disabled` Disabled
A per-item `disabled` prevents interaction on that item. The component-level `disabled` freezes the entire group while preserving the current value:
```vue
```
## Examples
### Slot-Based Item Customization
The `item-label`, `item-trailing`, and other slots can take over partial rendering of individual items. The selection indicator updates with the `selected` slot prop:
```vue [ComponentsPillGroupSlotsExample.vue]
{{ getItemLabel(item) }}
```
### Event Callbacks
Clicking an item fires `update:modelValue`, `change`, and `select` in sequence. The `select` payload contains `item`, `value`, `selected`, and `index`:
```vue [ComponentsPillGroupEventsExample.vue]
```
## API
### Props
```ts
/**
* Props for the MPillGroup component
*/
interface MPillGroupProps {
items?: T[] | undefined;
valueKey?: VK | undefined;
/**
* @default 'label'
*/
labelKey?: keyof Extract, object> & string | DotPathKeys, object>> | undefined;
/**
* @default 'description'
*/
descriptionKey?: keyof Extract, object> & string | DotPathKeys, object>> | undefined;
/**
* 对象模式下判定 selected 的比较依据。string 走 `getPath` 比较（multiple=true 时启用 Map O(1)）；
* function 自定义比较；不传则按 [valueKey, 'value', labelKey] 启发式回退。
*/
by?: string | (a: T, b: T): boolean | undefined;
/**
* 排列方向
* @default 'horizontal'
*/
orientation?: "horizontal" | "vertical" | undefined;
/**
* 按钮尺寸
* @default 'md'
*/
size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
/**
* 按钮颜色
* @default 'primary'
*/
color?: "primary" | "secondary" | "info" | "success" | "warning" | "error" | "important" | "neutral" | undefined;
/**
* 选中态单项视觉变体
* @default 'solid'
*/
activeVariant?: "link" | "solid" | "outline" | "soft" | "subtle" | "ghost" | undefined;
/**
* 未选中态单项视觉变体
* @default 'soft'
*/
inactiveVariant?: "link" | "solid" | "outline" | "soft" | "subtle" | "ghost" | undefined;
disabled?: boolean | undefined;
/**
* 是否可以多选
*/
multiple?: M | undefined;
/**
* 单选：再次点击当前选中项清空（多选模式下被忽略）
* @default false
*/
deselectable?: boolean | undefined;
/**
* 多选：最多可选数量
*/
max?: number | undefined;
/**
* 多选：最少需保留数量
*/
min?: number | undefined;
defaultValue?: GetModelValue | undefined;
modelValue?: GetModelValue & GetModelValue | undefined;
ui?: Record & { root?: SlotClass; list?: SlotClass; item?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; } | undefined;
}
```
### Emits
```ts
/**
* Emitted events for the MPillGroup component
*/
interface MPillGroupEmits {
blur: (payload: [event: FocusEvent]) => void;
focus: (payload: [event: FocusEvent]) => void;
change: (payload: [value: GetModelValue]) => void;
update:modelValue: (payload: [value: GetModelValue]) => void;
select: (payload: [payload: PillSelectPayload]) => void;
update:modelValue: (payload: [value: GetModelValue | undefined]) => void;
}
```
### Slots
```ts
/**
* Slots for the MPillGroup component
*/
interface MPillGroupSlots {
leading(): any;
default(): any;
trailing(): any;
item(): any;
item-leading(): any;
item-label(): any;
item-description(): any;
item-trailing(): any;
}
```
## Theme
## Changelog
See commit history for [src/runtime/components/PillGroup.vue](https://github.com/mhaibaraai/movk-nuxt/commits/main/src/runtime/components/PillGroup.vue).
## Sitemap
See the full [sitemap](https://nuxt.mhaibaraai.cn/sitemap.md) for all pages.