Tag field API

Import

Cimpress UI exports three tag field-related components:

TagField: main component that allows users to select multiple items from a collapsible list.
TagFieldItem: component that renders a single selectable item within a tag field.
TagFieldSection: component that groups related tag field items together under a section title.

import { TagField, TagFieldItem, TagFieldSection } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

Favorite fruits (controlled)

Favorite fruits (uncontrolled)

import { Stack, TagField, TagFieldItem, type Selection } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [selectedKeys, setSelectedKeys] = useState<Selection>(() => new Set(['apple', 'cherry']));

  return (
    <Stack gap={32}>
      <TagField label="Favorite fruits (controlled)" selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys}>
        <TagFieldItem id="apple">Apple</TagFieldItem>
        <TagFieldItem id="banana">Banana</TagFieldItem>
        <TagFieldItem id="cherry">Cherry</TagFieldItem>
      </TagField>

      <TagField label="Favorite fruits (uncontrolled)" defaultSelectedKeys={['apple', 'cherry']}>
        <TagFieldItem id="apple">Apple</TagFieldItem>
        <TagFieldItem id="banana">Banana</TagFieldItem>
        <TagFieldItem id="cherry">Cherry</TagFieldItem>
      </TagField>
    </Stack>
  );
}

Imperative API

This component exposes an imperative API through the apiRef prop. This API allows triggering behaviors that can’t be expressed by props.

Preview
Code

Favorite fruits

import { Button, Stack, TagField, type TagFieldApi, TagFieldItem } from '@cimpress-ui/react';
import { useRef } from 'react';

export default function Demo() {
  const apiRef = useRef<TagFieldApi>(null);

  return (
    <Stack gap={16}>
      <TagField label="Favorite fruits" defaultSelectedKeys={['apple', 'cherry']} apiRef={apiRef}>
        <TagFieldItem id="apple">Apple</TagFieldItem>
        <TagFieldItem id="banana">Banana</TagFieldItem>
        <TagFieldItem id="cherry">Cherry</TagFieldItem>
      </TagField>

      <Button onPress={() => apiRef.current?.focus()}>Focus</Button>
    </Stack>
  );
}

Accessibility notes

Tag field follows the ARIA combobox pattern. See the linked page for a list of available keyboard interactions.

Collapsible tag field list follows the ARIA listbox pattern. See the linked page for a list of available keyboard interactions.

The list of tags displayed next to the field is a single tab stop within the page’s tab order. Use the Tab key to navigate to the list, and the arrow keys to navigate between tags within the list. Use the Backspace or Delete key to remove tags from the list.

TagField requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

Collections

Tag field is a collection component. See our collection components guide to learn how to work with collections.

Forms

Tag field can integrate with native HTML forms. See our forms guide to learn how to work with forms.

API reference

TagField

Allows users to filter a collapsible list and select multiple items from it.

See tag field usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

TagFieldProps<T extends CollectionItem = CollectionItem>

selectedKeys Section titled “ selectedKeys ” Iterable<Key, any, any>: The currently selected keys in the collection (controlled).
defaultSelectedKeys Section titled “ defaultSelectedKeys ” Iterable<Key, any, any>: The initial selected keys in the collection (uncontrolled).
onSelectionChange Section titled “ onSelectionChange ” (keys: Set<Key>) => void: Handler that is called when the selection changes.
isVirtualized Section titled “ isVirtualized ” boolean: Whether the list of options should be virtualized. Use this as a performance optimization for large lists.

Defaults to false .
onScroll Section titled “ onScroll ” UIEventHandler<HTMLDivElement>: Handler that is called when the list of items is scrolled.
renderEmptyState Section titled “ renderEmptyState ” () => ReactNode: Provides content to display when there are no tags in the group.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
label Section titled “ label ” string: The content to display as the label.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
description Section titled “ description ” string: A description for the field. Provides a hint such as specific requirements for what to choose.
error Section titled “ error ” FieldError: An error message for the field.
validate Section titled “ validate ” (value: TagFieldValidationValue) => string | true | string[] | undefined: A function that returns an error message (or true) if a given value is invalid. Validation errors are displayed to the user when the form is submitted. For real-time validation, use the error prop instead.
placeholder Section titled “ placeholder ” string: The placeholder text displayed in the input field.
children Section titled “ children ” ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Section titled “ items ” Iterable<T, any, any>: The items to display in the collection.
apiRef Section titled “ apiRef ” RefObject<TagFieldApi | null>: A React ref that allows access to the imperative API of this component.
onOpenChange Section titled “ onOpenChange ” (isOpen: boolean, menuTrigger?: MenuTriggerAction) => void: Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
inputValue Section titled “ inputValue ” string: The value of the ComboBox input (controlled).
defaultInputValue Section titled “ defaultInputValue ” string: The default value of the ComboBox input (uncontrolled).
onInputChange Section titled “ onInputChange ” (value: string) => void: Handler that is called when the ComboBox input value changes.
onFocus Section titled “ onFocus ” (e: FocusEvent<HTMLInputElement>) => void: Handler that is called when the element receives focus.
onBlur Section titled “ onBlur ” (e: FocusEvent<HTMLInputElement>) => void: Handler that is called when the element loses focus.
autoFocus Section titled “ autoFocus ” boolean: Whether the element should receive focus on render.
isRequired Section titled “ isRequired ” boolean: Whether user input is required on the input before form submission.
isInvalid Section titled “ isInvalid ” boolean: Whether the input value is invalid.
isDisabled Section titled “ isDisabled ” boolean: Whether the input is disabled.
isReadOnly Section titled “ isReadOnly ” boolean: Whether the input can be selected but not changed by the user.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

TagFieldItem

Renders a single list item within TagField.

TagFieldItemProps<T extends CollectionItem>

children * Section titled “ children * ” StringLikeChildren: The content to display as the label.
id Section titled “ id ” Key: The ID of the item. Has to be unique across all sections and items.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
isDisabled Section titled “ isDisabled ” boolean: Whether the item is disabled.

TagFieldSection

Groups list items within TagField into a section.

TagFieldSectionProps<T extends CollectionItem>

title * Section titled “ title * ” string: The content to display as the section title.
id Section titled “ id ” Key: The ID of the section. Has to be unique across all sections and items.
children Section titled “ children ” ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Section titled “ items ” Iterable<T, any, any>: The items to display in the collection.

Tag field API

Import

Controlled/uncontrolled usage

Imperative API

Accessibility notes

Collections

Forms

API reference

TagField

ref

selectedKeys

defaultSelectedKeys

onSelectionChange

isVirtualized

onScroll

renderEmptyState

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

label

aria-label

aria-labelledby

aria-describedby

aria-details

form

name

description

error

validate

placeholder

children

items

apiRef

onOpenChange

inputValue

defaultInputValue

onInputChange

onFocus

onBlur

autoFocus

isRequired

isInvalid

isDisabled

isReadOnly

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

TagFieldItem

children *

id

onHoverStart

onHoverEnd

isDisabled

TagFieldSection

title *

id

children

items