Anatomy
- Label: Identifier for the displayed value
- Value: Can be a string, string type, highlighted value, text link, JSX, HTML; a single stacked label-value component can have one or more values
Subcomponents
See usage guidance for highlighted value
See usage guidance for text link
Usage
Use label value stacked to display labels and their associated values in areas with space constraints. The type you use depends on the metadata you want to display, the design layout, and the amount of space you have available. Compared to other label-value types, the label value stacked component has the best readability.
In this example, the record header uses the label-value pair (stacked) component to display secondary information for ease of scannability.
Variants
Learn about the attributes of label value stacked.
Types
There are multiple label-value types: tabbed, stacked, and inline. This guidance covers how to use the stacked type.
See usage guidance for label-value pair (tabbed)
See usage guidance for label-value pair (inline)
Sizes
Small
Label value stacked has the following sizes: small and medium. Use the small size for secondary or tertiary information in designs that have space constraints.
Medium
Use the medium size to provide supplemental information to primary content. Medium is the default size for label value stacked.
Configurations
Learn how to customize label value stacked by configuring the available properties.
Value types
The values you configure can be any of the following:
- String value
- Highlighted value
- Text link
- JSX
- HTML
String
You can display a string value as the value. This can be a single value or an array of values.
Previous value
One of the value items in a string can be a previous value. When defined, the previous value is crossed out and is preceded by the "was" label, which isn’t configurable. The “was” label is translatable.
Highlighted value
You can display a highlighted value as the value. All highlighted value configurations are still available within label value stacked. See the usage guidelines for details.
Text link
You can display a text link as the value. All text link configurations are still available within label value stacked.
JSX
You can display raw JSX as the value.
HTML
You can display raw HTML as the value.
Minimum width
By default, the minimum width of a stacked label-value pair is 50 pixels, but you can define a different width to accommodate the available space in your design.
Delimiters
Use delimiters to separate multiple values associated with a label. Delimiters can be commas, pipes, or slashes. A space is automatically added after each delimiter. However, if you need a space before and after the delimiter, you must manually add the space (e.g., Amy | Vice President). Be sure to use the same type of delimiter throughout your design to keep a consistent experience.
Commas
Use commas to separate similar items in a list. Commas are the default delimiter type for label value stacked.
You can use commas to separate names in a list.
Pipes
Use pipes (i.e. "vertical bars") for separating different values that may be related.
You can use a pipe to separate a name from a title.
Slashes
Like commas, you can use slashes to separate similar items in a list.
You can use a slash to separate names from one another.
Design recommendations
Learn how to apply label value stacked in your design.
Keep consistent spacing between label-value pairs, so that the user can clearly understand their relationship.
Don’t use inconsistent spacing between label-value pairs. When the spacing between different label-value pairs is inconsistent, it affects readability.
Add spaces after delimiters to differentiate values in the value string.
Don’t use delimiters without a space after it. Without spaces after delimiters, it's difficult to identify individual values.
Alignment and positioning
You can align multiple stacked label-value pairs in the following ways: vertical, horizontal, or horizontal equal.
Vertical
Vertical alignment displays multiple label-value pairs in a single column, one on top of the other.
Use vertical alignment for displaying label-value pairs in a column or spaces with limited width.
Horizontal
Horizontal alignment displays multiple label-value pairs side-by-side on the same line.
Use horizontal alignment in spaces with a constrained height. The side-by-side alignment saves vertical space and allows values to be easily scanned. Use this for displaying label-value in multiple columns or for associating label-values with a header or title.
In this example, the stacked label-value pairs use the horizontal alignment.
Horizontal equal
Horizontal equal alignment displays multiple label-value pairs side-by-side in a predefined parent container size. The pairs equally fills (both horizontally and vertically) the container based on its size.
In this example, the stacked label-value pairs use the horizontal equal alignment.
UI text guidelines
These are some recommendations for using text within label value stacked:
- Use short labels to avoid text wrapping to the next line
- You can use either present tense verbs or nouns in the label depending on the info you’re showing
- For example, “Contact was Abel Tuter” or “Assigned to Abel Tuter”
Behavior
Learn how label value stacked behaves when the display changes or a user interacts with the component.
Responsive behavior
Learn how label value stacked responds to changes in a container or display.
Overflow
As you select stacked label-values, consider how they will appear in constrained spaces. If multiple values do not fit in the same line, they adopt the overflow behavior. The line break occurs after each delimiter, and the next value wraps into the line below.
In this example, the “Assigned to” values wrap to the next line because of the constrained width.
Truncation
Avoid truncating labels or values because it creates a disjointed experience. When creating stacked label-value pairs, be mindful of text and string length to avoid truncation. Also consider the size of the container where the label-value pairs will appear. However, if the length of the labels or values is unknown due to configurability, truncation can be useful.
When a label or value truncates, it adopts the overflow behavior. An ellipsis signifies the truncated label or value, and a tooltip appears on hover to display the full string of characters.
Truncation isn't supported for raw HTML or JSX values.
Usability
Label value stacked complies with all internationalization and accessibility requirements.
Internationalization
When translating content to a right-to-left (RTL) language, the labels and values flip and align on the right.
Accessibility
Learn how to access the actionable elements of label value stacked through keyboard interactions and screen readers.
Keyboard interactions
If the value is a text link:
- Tab: Puts focus on the link
- Space or Enter: Launches the link
Note: An option in the user Preferences menu on the operating system sets a tab stop on non-interactive text that truncates in this component, such as a title or label, and makes that text a tooltip trigger. The user presses Enter or the spacebar to open the tooltip and view the entire content. To enable this feature, set the Enable keyboard focus on truncated text option to true in the Accessibility panel of the Preferences menu.