Key Value Pair

Key value pairs consist of properties (keys) each paired with their respective values.

Key-value pairs help present a pair of data in a structured way. They are useful for displaying data in an organized manner, making it easier to understand and process information on the screen.

A key acts as an identifier of the value. It should be short and easy to understand.

Following can be the variants of key:

• Icon
• Text
• Icon and text

[1] Textual Key, [2] Textual key with icon on left, [3] Textual key with icon on right, [4] Icon as key

A value represents the actual content corresponding to the key. Values can be more varied in type and length than keys.

Here are the common variants:

• Text
• Icon and text
• Avatar and text
• Status
• Link
• Array of items
• Custom

Various variants of value

Key-value pairs can be arranged in two ways: Top-Bottom and Left-Right.

In a Top-Bottom arrangement, the key is positioned above the value, creating a strong visual connection between the two. This layout is suitable for narrow containers or vertical layouts, providing ample space for both keys and values.

• Length of Key: If the keys are long, a top-bottom arrangement can accommodate longer keys in a single line without truncation.


• Length of Value: When values are lengthy or require more space, a vertical layout handles this well without disrupting the flow.


• Scannability: Users tend to scan content from top to bottom, especially in narrower containers. A top-bottom arrangement aligns with this natural scanning pattern, making it easier for users to quickly locate the information they need.

Top bottom arrangement of key value pairs

In a Left-Right key-value pair arrangement, the key is positioned on the left, while the corresponding value is placed on the right. This layout is typically suitable for wider containers or horizontal layouts, maximizing the utilization of horizontal space and minimizing the need for vertical scrolling.

• Comparison of Similar Items: This arrangement facilitates quick scanning across rows, allowing for easy comparison of similar pieces of information.


• Variation in Values: It preserves visual hierarchy, especially when there is significant variation in the lengths of the values.


• Emphasis on Values: If the values hold more importance than the keys, a left-right arrangement can draw attention to the values by positioning them prominently on the right side of the keys.


• Compact Design: The layout conserves vertical space, making it suitable for interfaces where space is limited and extensive information needs to be displayed without excessive scrolling.

Left right arrangement of key value pairs

Choosing between a left-right and a top-bottom arrangement often depends on the context, user preferences, and the amount of information to be presented. Here are some points to consider while doing so:

Both the key and the values can share the same width. Keep the key short to prevent it from spanning multiple lines and disrupting the layout. The value can wrap to the next line to ensure all information is visible.

Key and value has same width

The key should occupy about 40% of the available width, with the remaining 60% allocated to the value.

For wide containers, if 40% makes the keys too wide, adjust the width to suit the use case, and allocate the remaining width to the values.

If only one or two keys are too wide, adjust the width of the key column to suit the remaining keys and wrap the wider keys to the next line.

Note: Both the key and the values can span multiple lines if needed.

Key occupying 40% of the space, including padding, and value occupying 60%.

Below are guidelines for utilizing various key-value pair arrangements based on the available container size.

Note: These are our recommendations; feel free to adjust the layouts as needed.

For containers around 200px, opt for Top-Bottom key-value pairs to maintain most content within a single line.

Top bottom alignment in small containers

For widths around 400px, Left-Right key-value pairs are advisable, as keys and values can now have ample space.

Left right alignment in medium containers

Widths exceeding 400px allow for the utilization of single or multiple column layouts.

Single column layouts

When dealing with complex values or array of multiple values where scanning is a priority, opt for Left-Right key-value pairs.

Note: Avoid the use of multiple columns for key-value pairs in this context.

Left right alignment in a single column layout

Multiple column layouts

For simple and mostly similar values, the top-bottom arrangement is ideal as it occupies minimal space.
In such layouts, key-value pairs can align to either fixed or variable width columns.
Note: In a row, the keys should always be top aligned.

1. Column with fixed width

This approach is most effective when displaying multiple rows, either within the same container or across multiple vertically stacked containers.

Key value pairs aligned to fixed width columns

2. Column with variable width

This approach is most efficient when you only need to display a single row, as it occupies the least horizontal space.

Key value pairs aligned to variable width columns

Ensure adequate spacing between entities to maintain readability and avoid a cluttered UI.

Minimum Padding

Recommended minimum padding between key and [left] textual value vs [right] complex value

Minimum Margin

Recommended minimum horizontal and vertical margin between two key-value pairs

Other Layouts

Here are some recommended layouts to make sure users can scan the information easily. Feel free to go beyond these suggestions to best suit your use case.

Other recommended layouts for top-bottom arrangement

Minimum Padding

Recommended minimum padding between key and value

Minimum Margin

Recommended minimum vertical margin between two key-value pairs