Coming from Orbiter, you should be aware of the following changes:
onClearis not supported.validationStateis not supported. UseisInvalidinstead,readOnlyhas been renamedisReadOnly.
TagGroup
The TagGroup is a dynamic UI component that encapsulates a collection of tags. Each tag represents a label, category, keyword, or filter, and can be used for various groupings
Multiple or single tags can be used to categorize items. Use short labels for easy scanning. Use two words only if necessary to describe the status and differentiate it from other tags.
Anatomy
Structure
<TagGroup> <Tag> /* (Required) An item in the TagGroup */ <Avatar /> /* (Optional) An avatar in the Tag */ <Icon /> /* (Optional) An icon in the Tag */ <IconList /> /* (Optional) A list of icons in the Tag */ <Text /> /* (Optional) Text is optional, but becomes required if any other elements are present */ <Badge /> /* (Optional) A badge in the Tag */ </Tag> </TagGroup>
Composed Components
A Tag within a TagGroup uses the following components:
Usage
Label
A tag group can use the label prop to provide more context to the user.
Description
A tag group can use a description prop to provide more information to the user.
Disabled
Tags can be disabled using the disabledKeys prop.
Disabled Item
A tag can be disabled using the isDisabled prop.
Invalid Tag
If a tag group is invalid, it will display an error message. Displaying this error message will hide the helper message.
Removable
Tags can be removed using the onRemove callback.
If you are using a keyboard, you can press the backspace key to remove a tag.
Readonly
Tags can be set to read-only using the isReadOnly prop. This will prevent the user from removing tags.
Selectable
Tags can be selected using the selectionMode prop.
Use defaultSelectedKeys for initially selected items (uncontrolled) and selectedKeys to manage selected items (controlled).
The selected keys should match the item's id prop.
Sizes
A tag group can vary in size.
Item Sizes
A tag can vary in size.
Variants
A tag group can vary in style using the variant prop. The one seen here is subdued.
Item Variants
A tag can vary in style using the variant prop.
Empty List
Using the renderEmptyState prop, you can customize the empty state message when there are no tags.
ContextualHelp
A ContextualHelp element may be placed next to the label to provide additional information or help about a TagGroup.
Invalid TagGroup
A tag can be set as invalid using the isInvalid prop.
Loading
A tag can have a loading state using the isLoading prop.
Avatar
A tag can contain an avatar.
Icons
A tag can contain an icon or an icon list.
Count
A tag can contain a count using the Badge component.
Links
A tag can be a link by using the href prop on the Tag component. Tags with an href are not selectable.
React Router Links
A tag can be rendered as a react router link when using the href prop and setting the navigate prop on the HopperProvider.
Best Practices
Tags should:
- Be presented close to or within the input control that allows users to add and remove tags.
- Use appropriate colour semantics when describing states of an object
- Use a size that match the object it relates to. Tags should not be bigger or more prominent than the object it relates to.
Props
TagGroup
isInvalid?
Whether the tags are invalid or not.
size?
A tag can vary in size.
Defaults to md.
tagListProps?
The tag list props
variant?
The visual style of the TagGroup.
Defaults to neutral.
isReadOnly?
Whether or not the tags should render as readonly.
style?
The inline style for the element.
selectionBehavior?
How multiple selection should behave in the collection.
disabledKeys?
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
selectionMode?
The type of selection that is allowed in the collection.
disallowEmptySelection?
Whether the collection allows empty selection.
selectedKeys?
The currently selected keys in the collection (controlled).
defaultSelectedKeys?
The initial selected keys in the collection (uncontrolled).
className?
The CSS className for the element.
children?
The contents of the collection.
items?
Item objects in the collection.
renderEmptyState?
Provides content to display when there are no items in the tag list.
label?
The label of the field.
description?
The helper message of the field.
errorMessage?
The error message of the field.
necessityIndicator?
Whether the required state should be shown as an asterisk or a label, which would display (Optional) on all non required field labels.
contextualHelp?
A ContextualHelp element to place next to the label.
Tag
isInvalid?
Whether the tag is invalid or not.
isLoading?
Whether the tag is loading or not.
size?
The size of the tag.
Defaults to md.
variant?
The visual style of the Tag.
Defaults to neutral.
clearButtonProps?
The props of the ClearButton.
spinnerProps?
The props of the Spinner.
style?
The inline style for the element. A function may be provided to compute the style based on component state.
id?
A unique id for the tag.
textValue?
A string representation of the tags's contents, used for accessibility. Required if children is not a plain text string.
isDisabled?
Whether the tag is disabled.
children?
The children of the component. A function may be provided to alter the children based on component state.
className?
The CSS className for the element. A function may be provided to compute the class based on component state.
href?
A URL to link to. See MDN.
hrefLang?
Hints at the human language of the linked URL. SeeMDN.
target?
The target window for the link. See MDN.
rel?
The relationship between the linked resource and the current page. See MDN.
download?
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
ping?
A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy?
How much of the referrer to send when following the link. See MDN.
routerOptions?
Options for the configured client side router.
Migration Notes
TagGroup
Tag
Coming from Orbiter, you should be aware of the following changes:
- A dot is not supported
fluidis not supported.variantvalues are nowneutral|subdued|progress|positive|caution|negative|option1|option2|option3|option4|option5|option6and notsolid|outline.validationStateis not supported. UseisInvalidinstead.