npm-react-aria

1
# Tags
2

3
Tag components for displaying and managing collections of labels, categories, or metadata with full accessibility support including keyboard navigation and screen reader announcements.
4

5
## Capabilities
6

7
### Tag
8

9
Provides individual tag behavior with optional dismiss functionality and keyboard navigation.
10

11
```typescript { .api }
12
/**
13
 * Provides tag behavior and accessibility
14
 * @param props - Tag configuration options
15
 * @param state - Tag state from useTagState
16
 * @param ref - Ref to the tag element
17
 * @returns Tag props and state
18
 */
19
function useTag(props: AriaTagProps, state: TagState, ref: RefObject<Element>): TagAria;
20

21
interface AriaTagProps {
22
  /** Tag content/label */
23
  children: ReactNode;
24
  /** Whether the tag can be removed */
25
  isDismissible?: boolean;
26
  /** Whether the tag is disabled */
27
  isDisabled?: boolean;
28
  /** Whether the tag is selected (for selectable tags) */
29
  isSelected?: boolean;
30
  /** Handler called when the tag is dismissed */
31
  onDismiss?: () => void;
32
  /** Handler called when the tag is selected */
33
  onSelect?: () => void;
34
  /** Text content of the tag for accessibility */
35
  textValue?: string;
36
  /** ARIA label for the dismiss button */
37
  dismissLabel?: string;
38
}
39

40
interface TagAria {
41
  /** Props to spread on the tag element */
42
  tagProps: DOMAttributes<Element>;
43
  /** Props for the dismiss button (if dismissible) */
44
  dismissButtonProps: DOMAttributes<Element>;
45
  /** Whether the tag is currently focused */
46
  isFocused: boolean;
47
  /** Whether the tag is currently hovered */
48
  isHovered: boolean;
49
}
50
```
51

52
**Usage Example:**
53

54
```typescript
55
import { useTag } from "react-aria";
56
import { useTagState } from "react-stately";
57

58
function Tag(props) {
59
  let state = useTagState(props);
60
  let ref = useRef();
61
  let { tagProps, dismissButtonProps, isFocused } = useTag(props, state, ref);
62

63
  return (
64
    <div
65
      {...tagProps}
66
      ref={ref}
67
      className={`tag ${isFocused ? 'focused' : ''} ${props.isSelected ? 'selected' : ''}`}
68
    >
69
      <span className="tag-content">{props.children}</span>
70
      {props.isDismissible && (
71
        <button {...dismissButtonProps} className="tag-dismiss">
72
          ×
73
        </button>
74
      )}
75
    </div>
76
  );
77
}
78
```
79

80
### Tag Group
81

82
Manages a collection of tags with keyboard navigation, selection state, and batch operations.
83

84
```typescript { .api }
85
/**
86
 * Provides tag group behavior for managing collections of tags
87
 * @param props - Tag group configuration
88
 * @param state - Tag group state from useTagGroupState
89
 * @param ref - Ref to the tag group element
90
 * @returns Tag group props and utilities
91
 */
92
function useTagGroup(props: AriaTagGroupProps, state: TagGroupState, ref: RefObject<Element>): TagGroupAria;
93

94
interface AriaTagGroupProps {
95
  /** Collection of tag items */
96
  items?: Iterable<TagItem>;
97
  /** Whether multiple tags can be selected */
98
  selectionMode?: 'none' | 'single' | 'multiple';
99
  /** Currently selected tag keys */
100
  selectedKeys?: Iterable<Key>;
101
  /** Default selected keys (uncontrolled) */
102
  defaultSelectedKeys?: Iterable<Key>;
103
  /** Handler called when selection changes */
104
  onSelectionChange?: (keys: Set<Key>) => void;
105
  /** Handler called when a tag is dismissed */
106
  onDismiss?: (key: Key) => void;
107
  /** Whether the tag group is disabled */
108
  isDisabled?: boolean;
109
  /** Whether tags are read-only */
110
  isReadOnly?: boolean;
111
  /** Maximum number of tags to display */
112
  maxTags?: number;
113
  /** Label for the tag group */
114
  label?: ReactNode;
115
  /** Description for the tag group */
116
  description?: ReactNode;
117
  /** Error message for validation */
118
  errorMessage?: ReactNode;
119
}
120

121
interface TagGroupAria {
122
  /** Props to spread on the tag group container */
123
  tagGroupProps: DOMAttributes<Element>;
124
  /** Props for the group label */
125
  labelProps: DOMAttributes<Element>;
126
  /** Props for the description */
127
  descriptionProps: DOMAttributes<Element>;
128
  /** Props for the error message */
129
  errorMessageProps: DOMAttributes<Element>;
130
}
131
```
132

133
**Usage Example:**
134

135
```typescript
136
import { useTagGroup } from "react-aria";
137
import { useTagGroupState } from "react-stately";
138

139
function TagGroup(props) {
140
  let state = useTagGroupState(props);
141
  let ref = useRef();
142
  let { tagGroupProps, labelProps, descriptionProps } = useTagGroup(props, state, ref);
143

144
  return (
145
    <div {...tagGroupProps} ref={ref} className="tag-group">
146
      {props.label && (
147
        <label {...labelProps} className="tag-group-label">
148
          {props.label}
149
        </label>
150
      )}
151
      <div className="tag-list">
152
        {state.collection.map((item) => (
153
          <Tag
154
            key={item.key}
155
            item={item}
156
            state={state}
157
            isDismissible={!props.isReadOnly}
158
            isSelected={state.selectionManager.isSelected(item.key)}
159
            onDismiss={() => props.onDismiss?.(item.key)}
160
          />
161
        ))}
162
      </div>
163
      {props.description && (
164
        <div {...descriptionProps} className="tag-group-description">
165
          {props.description}
166
        </div>
167
      )}
168
    </div>
169
  );
170
}
171
```
172

173
## Types
174

175
```typescript { .api }
176
interface TagState {
177
  /** Whether the tag is selected */
178
  isSelected: boolean;
179
  /** Whether the tag is focused */
180
  isFocused: boolean;
181
  /** Whether the tag is hovered */
182
  isHovered: boolean;
183
  /** Whether the tag can be dismissed */
184
  isDismissible: boolean;
185
}
186

187
interface TagGroupState {
188
  /** Collection of tag items */
189
  collection: Collection<TagItem>;
190
  /** Selection manager for the tag group */
191
  selectionManager: SelectionManager;
192
  /** Whether the tag group is disabled */
193
  isDisabled: boolean;
194
  /** Add a new tag to the group */
195
  addTag: (tag: TagItem) => void;
196
  /** Remove a tag from the group by key */
197
  removeTag: (key: Key) => void;
198
  /** Clear all tags */
199
  clear: () => void;
200
}
201

202
interface TagItem {
203
  /** Unique identifier for the tag */
204
  key: Key;
205
  /** Tag content */
206
  content: ReactNode;
207
  /** Text representation for accessibility */
208
  textValue: string;
209
  /** Whether this tag is dismissible */
210
  isDismissible?: boolean;
211
  /** Whether this tag is disabled */
212
  isDisabled?: boolean;
213
}
214
```