Props
Usage guidelines
- When selecting and/or comparing categories with an accompanying chart or graph view that displays at-a-glance data for a user to quickly view key metrics
Best practices
Choose the right background to help it stand out in dense data interfaces. For example, set baseColor=secondary
when using TagData against a gray background.
Match TagData fill with the surrounding background color. Using the same color can make it unclear that TagData is selectable.
Use the same variants of TagData in a group, depending on the type of behavior TagData should have.
Mix TagData variants in the same group. This creates an unclear pattern for the user to understand which TagDatas are removable or not.
Use short and clear labels for easier comprehension — ideally one or two words.
Use long sentences in the text
prop, since the text in TagData truncates as needed to preserve the max width.
Accessibility
Users should be able to navigate or activate TagData using a keyboard or other input modalities. Be sure to include an accessibilityRemoveIconLabel
and tooltip.accessibilityLabel
for the screen reader with the onRemove
prop and tooltip
prop.
Localization
Be sure to localize accessibilityRemoveIconLabel
,tooltip.accessibilityLabel
, and text
props in TagData.
When the text
of TagData reaches its max width, either intentionally or through localization, the text will be truncated with ellipses as needed to preserve the max-width. Keep this in mind when selecting wording for TagData. Note that localization can lengthen text by 20 to 30 percent.
Variants
Size
TagData is available in 3 fixed sizes.
- lg has height of 48px. Text has a fixed size of 16px.
- md has height of 40px. Text has a fixed size of 14px.
- sm has height of 32px. Text has a fixed size of 14px.
import { Flex, TagData } from 'gestalt'; export default function Example() { return ( <Flex justifyContent="center" alignItems="center" height="100%" width="100%" direction="column" gap={2} > <TagData text="Small TagData" size="sm" showCheckbox /> <TagData text="Medium TagData" size="md" showCheckbox /> <TagData text="Large Tagdata" size="lg" showCheckbox /> </Flex> ); }
Base Color
By default, TagData uses a light gray fill, which is suitable for placement on a white background. When used on a gray background, use baseColor="secondary"
for a white fill.
import { Box, Flex, TagData } from 'gestalt'; export default function Example() { return ( <Flex justifyContent="center" alignItems="center" height="100%" width="100%" > <Box width="50%" height="100%" display="flex" justifyContent="center" alignItems="center" > <TagData text="Small TagData" size="sm" baseColor="primary" /> </Box> <Box width="50%" height="100%" display="flex" justifyContent="center" alignItems="center" color="secondary" > <TagData text="Small TagData" size="sm" baseColor="secondary" /> </Box> </Flex> ); }
Colors
TagData is available in the colors from our data visualization color palette. Match each TagData's color
to its respective data line, which will be visible when TagData is selected.
import { useState } from 'react'; import { Box, Flex, TagData } from 'gestalt'; export default function Example() { const allColors = [ '01', '02', '03', '04', '05', '06', '08', '09', '10', '11', '12', ]; const [selectedColors, setSelectedColors] = useState(allColors); return ( <Box overflow="scrollY" height="90%" padding={2}> <Flex gap={4} wrap justifyContent="center"> {allColors.map((color) => ( <TagData id={color} key={color} color={color} selected={selectedColors.includes(color)} onTap={({ id: selectedId, selected }) => { if (!selectedId) { return; } setSelectedColors((currSelectedColors) => !selected ? currSelectedColors.filter((tileId) => tileId !== color) : currSelectedColors.concat([color]) ); }} text={`Color ${color}`} showCheckbox /> ))} </Flex> </Box> ); }
Group
Use TagData's showCheckbox
prop to display a checkbox. This is useful when presenting the user with a multi-select experience.
import { useState } from 'react'; import { Flex, TagData } from 'gestalt'; export default function Example() { const dataSources = [ { id: 'data-1', name: 'Monthly Active', color: '01', tooltip: 'Monthly active users', }, { id: 'data-2', name: 'Weekly Active', color: '02', tooltip: 'Weekly active users', }, { id: 'data-3', name: 'Daily Active', color: '03', tooltip: 'Daily active users', }, ]; const allIds = dataSources.map(({ id }) => id); const [selectedItems, setSelectedItems] = useState(allIds); return ( <Flex justifyContent="center" alignItems="center" height="100%" width="100%" gap={2} > {dataSources.map(({ id, color, tooltip, name }) => ( <TagData key={id} id={id} showCheckbox onTap={({ id: selectedId, selected }) => { if (!selectedId) { return; } setSelectedItems((currSelectedIds) => !selected ? currSelectedIds.filter((tileId) => tileId !== selectedId) : currSelectedIds.concat([selectedId]) ); }} selected={selectedItems.includes(id)} color={color} tooltip={{ text: tooltip }} text={name} /> ))} </Flex> ); }
Dismissible
Provide an onRemove
callback to make TagData dismissible. Tags are dismissible by the "X" affordance, which triggers the onRemove
callback. onRemove
should be used to update the external state that is keeping track of TagDatas. If your app uses DefaultLabelProvider, a default accessibility label for the remove icon will be used. This can be overridden with a more specific label if desired.
import { useState } from 'react'; import { Flex, TagData } from 'gestalt'; export default function Example() { const dataSources = [ { id: 'data-1', name: 'Monthly Active', color: '01', tooltip: 'Monthly active users', }, { id: 'data-2', name: 'Weekly Active', color: '02', tooltip: 'Weekly active users', }, { id: 'data-3', name: 'Daily Active', color: '03', tooltip: 'Daily active users', }, ]; const allIds = dataSources.map(({ id }) => id); const [data, setData] = useState(dataSources); const [selectedItems, setSelectedItems] = useState(allIds); return ( <Flex justifyContent="center" alignItems="center" height="100%" width="100%" gap={2} > {data.map(({ id, color, tooltip, name }) => ( <TagData key={id} id={id} color={color} showCheckbox onTap={({ id: selectedId, selected }) => { if (!selectedId) { return; } setSelectedItems((currSelectedIds) => !selected ? currSelectedIds.filter((tileId) => tileId !== selectedId) : currSelectedIds.concat([selectedId]) ); }} onRemove={({ id: selectedId }) => { if (!selectedId) { return; } setData((currData) => currData.filter((tile) => tile.id !== selectedId) ); }} selected={selectedItems.includes(id)} tooltip={{ text: tooltip }} text={name} /> ))} </Flex> ); }
Tooltip
Use tooltip
to display clarifying information on hover or focus. We recommend using tooltips to provide the user additional context/details.
import { useState } from 'react'; import { Flex, TagData } from 'gestalt'; export default function Example() { const [isSelected, setSelected] = useState(false); return ( <Flex justifyContent="center" alignItems="center" height="100%" width="100%" > <TagData showCheckbox text="CPM" size="lg" selected={isSelected} onTap={() => { setSelected((selected) => !selected); }} onRemove={() => {}} tooltip={{ text: 'Average cost per 1K paid impressions' }} /> </Flex> ); }
Disabled
Disabled TagData cannot be interacted with using the mouse or keyboard. This is commonly used to disable interaction when there are pending permissions or data prerequisites have not been met.
import { useState } from 'react'; import { Flex, TagData } from 'gestalt'; export default function Example() { const [isSelected, setSelected] = useState(true); return ( <Flex justifyContent="center" alignItems="center" height="100%" width="100%" > <TagData disabled text="CPM" size="lg" onRemove={() => {}} showCheckbox selected={isSelected} onTap={() => { setSelected((selected) => !selected); }} tooltip={{ text: 'Average cost per 1K paid impressions' }} /> </Flex> ); }
Component quality checklist
Quality item | Status | Status description |
---|---|---|
Figma Library | Ready | Component is available in Figma for web and mobile web. |
Responsive Web | Ready | Component responds to changing viewport sizes in web and mobile web. |
Related
Tag
Tags are objects that hold text and have a delete icon to remove them. They can appear within TextFields, TextAreas, ComboBox or as standalone components.
TileData
TileData is a flexible, visually rich component that can be used as single or multiple selections on should be only used with data visualizations.