Consider using a NameValueList for the following use cases:

• Displaying a list of name and value pairs.
• Presenting metadata in a clear, scannable and consistent way.
• Decreasing the time taken to review data.

A NameValuePair is a set of two related elements: a name, which identifies a data item, and a value, which is the description of that data.

1. Name
   A name is a unique indentifier or term referring to a data item. This is typically a constant. In general, name labels are displayed in sentence case (the first letter is a capital and the following words are in lowercase).

2. Value
   Value is the description of data or a pointer to the location of that data. The format of the value can vary, depending on the data set. Content can include: single line description, multi line description, anchors, array or list of items.

3. Supporting icons/visuals (optional)
   Icons may be included to visually support the name or value. It is recommended not to use icons for both name and value at the same time. This can cause unnecessary visual noise and distract from vital information.

The pairProps direction determines how the name and value are aligned. If you want the name to be on top of the value, apply pairProps={{direction: 'column'}}.

In some cases, NameValuePairs may be used as read-only display for text inputs that are editable inline. Here, the name and value text styling should match the Text Input component (sans border).

When presenting a value as a list of items, the list may be truncated and accompanied by a Button to expand it, displaying all items.

When delimited, content exceeding 192 characters should be truncated.

For vertical lists:

• 7+ items should be truncated, displaying the first 3 items with a "Show all" button.
• For 6 or fewer items, show all items and do not truncate.

If the value of a name-value pair is empty, use -- in place of where a value would appear. This visual indicator aids the user in identifying fields that do not have values, without increasing cognitive load.

To inform assistive-technology users of an empty state, add an a11yTitle="No value" to the Text component that would otherwise render the data.

Depending on the use case, it may or may not be necessary to render a name-value pair with an empty value to the user.

In certain scenarios, it is important to display to a user that a certain name-value pair does not have a value. These scenarios include:

Review/Edit pages - when a user has made configuration selections (such as in a Wizard) or is editing configurations (such as settings), all name-value pairs should be visible so the user knows which options they have and have not configured.

Detail pages - these kinds of pages provide the most granular level of information about a device, server, etc. and should display all name-value pairs.

In certain scenarios, it is not necessary to display name-value pairs that don’t have a value. These scenarios include:

Public-facing profiles - For instances where a profile is outwardly facing, only name-value pairs with values should be displayed. The complete list of possible entries should only be viewable when a user goes to edit their profile.

Summaries (such as dashboard cards) - Summaries are intended to display information-salient content, often in areas with restricted screen real estate. Given this, name-value pairs without a value should be omitted.

A successful NameValueList is scannable and easy to grasp. Consider the following methods to imply hierarchy: order, headings, scale, font weight, color.

• Having a logical order of a name-value list ensures a more scannable display of data.
• Depending on content displayed, consider ordering by name (alphabetical order) or by importance of information (most relevant to less relevant).
• Always establish the structure of your data upfront.

• Use headings to define a name-value List and/or for grouping multiple name-value lists within a single screen.
• For accessibility reasons, always ensure semantically correct heading levels are applied. See best practices for applying headings.

• Default font size for a NameValueList is “medium” (18px).
• Font-size options for displaying name and value include small, medium and large.
• Additional sizes xl and xxl can be opted for displaying value content, depending on styling needs (such as for displaying on a dashboard page layout).
• The size of name can differ from value.
• Name should never be scaled bigger than its value.

Making the font bolder or thinner is another way to create hierarchy that’s easily identifiable.

• Typically, use a bold weight on names to increase scanability within the list
• In some cases, a value may be displayed in a bold weight to draw the reader’s attention. An example of this application might be a dashboard page.
• Don’t use bold text for both name and value at the same time.
• Don’t use a bold font-weight for any long format content as this can be very hard to read and overwhelm the user.

Options for text color include the default text (default for Name-Value pairs) and text-strong .

All types of NameValueLists will change to a single column NameValueList on smaller viewports. View this behavior by reducing your window screen until the layout of an example shifts to single column.

By default, both the name and the value are left aligned. This can be changed through nameProps and valueProps by setting align to the desired value, such as end. No matter what alignment is chosen, always opt for a consistent presentation across a single NameValueList or NameValueLists on a single page.

The width of name is set to "small" by default to accommodate a reasonable width for common data names. However, if all names are short, it may be appropriate to adjust the name width to something smaller. This can be easily changed through nameProps. For example nameProps={{width: 'xsmall'}}. The width of value is set to medium by default to aid readability of content. However, if necessary, the width of value can also be adjusted with valueProps. For example, valueProps={{width: 'large'}}