Data Pair

<sl-data-pair> | SlDataPair
Since 1.0 stable

A data pair is the easiest way to visually represent any data.

<sl-data-pair label="Top label" value="Value"></sl-data-pair>

Examples

Label

The label is a slot that can be positioned either top, bottom or inline. Labels indicate what the user needs to put into the field. For labels that contain HTML, use the label slot instead. 

<div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 24px;">
  <sl-data-pair
    label="Top label"
    value="Value"
    align="left"
    label-position="top"
    icon="circle-info"
  ></sl-data-pair>
  
  <sl-data-pair
    label="Bottom label"
    value="Value"
    align="left"
    label-position="bottom"
  ></sl-data-pair>
  
  <sl-data-pair
    label="In line label"
    value="Value"
    align="left"
    label-position="inline"
  ></sl-data-pair>
</div>

Custom Label Width

When using an inline label, you can set a custom width for the label container by using the --form-control-label-width CSS custom property. If the label text is longer than the specified width, it will wrap to a new line by default. 

<sl-data-pair
  label="This is a very very very very very very very very long label that will wrap because the container is smaller than the text."
  value="Value"
  label-position="inline"
  style="--form-control-label-width: 10rem;"
></sl-data-pair>

Label styles

Label style uses the label tokens, this is to align with other form components.

<div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 24px;">
  <sl-data-pair
    label="Default label"
    value="Value"
  ></sl-data-pair>
  
  <sl-data-pair
    label="Label"
    value="Value"
    label-position="inline"
  ></sl-data-pair>
</div>

Top/Bottom alignment

Top & bottom data pairs can be aligned in three ways: start, center, and end.

<div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 24px;">
  <sl-data-pair
    label="Start-aligned"
    value="Value"
    align="left"
  ></sl-data-pair>
  
  <sl-data-pair
    label="Center-aligned"
    value="Value"
    align="center"
  ></sl-data-pair>

  <sl-data-pair
    label="End-aligned"
    value="Value"
    align="right"
  ></sl-data-pair>
</div>

Label-suffix

Label-suffix is a slot that sits next to the label. Icons with tooltips are typically used to provide additional context. 

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
  <sl-data-pair label="Label" value="Value">
    <sl-icon slot="suffix" name="circle-info"></sl-icon>
  </sl-data-pair>

  <sl-data-pair label="Label" value="Value" label-position="inline">
    <sl-icon slot="suffix" name="circle-info"></sl-icon>
  </sl-data-pair>
</div>

Label-prefix

Label-prefix is a slot that sits next to the label. Icons or legend colour keys are typically used to provide additional context. 

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
  <sl-data-pair label="In progress" value="3" align="right">
    <sl-icon slot="prefix" name="spinner" library="system"></sl-icon>
  </sl-data-pair>

  <sl-data-pair label="Mobile number" value="+61 456 789" label-position="inline">
    <sl-icon slot="prefix" name="phone"></sl-icon>
  </sl-data-pair>
</div>

Inline label sizes

By default, the inline label container will hug width. Otherwise, there are multiple fixed widths to provide visual balance when stacking a group of inputs. Determine what size to use based on the length of label texts. 

<div style="display: grid; gap: 24px;">
  <sl-data-pair
    label="Hug width"
    value="Value"
    align="center"
    label-position="inline"
    inline-label-size="hug"
    label-wrap="false"
  ></sl-data-pair>

  <sl-data-pair
    label="XS - xs size"
    value="Value"
    align="center"
    label-position="inline"
    inline-label-size="xs"
    label-wrap="false"
  ></sl-data-pair>
  
  <sl-data-pair
    label="sm - inline label sm size"
    value="Value"
    align="center"
    label-position="inline"
    inline-label-size="sm"
    label-wrap="false"
  ></sl-data-pair>

  <sl-data-pair
    label="md - an inline label to show md size"
    value="Value"
    align="center"
    label-position="inline"
    inline-label-size="md"
    label-wrap="false"
  ></sl-data-pair>

  <sl-data-pair
    label="lg - this is an inline label to demonstrate lg size"
    value="Value"
    align="center"
    label-position="inline"
    inline-label-size="lg"
    label-wrap="false"
  ></sl-data-pair>

  <sl-data-pair
    label="xl - this is an inline label example to demonstrate the xl size"
    value="Value"
    align="center"
    label-position="inline"
    inline-label-size="xl"
    label-wrap="false"
  ></sl-data-pair>
</div>

Example of a data pair list using md inline label

<div style="display: grid; gap: 24px;">
  <sl-data-pair
    label="Name"
    value="Robert Burton"
    align="left"
    label-position="inline"
    inline-label-size="md"
  ></sl-data-pair>

  <sl-data-pair
    label="Email"
    value="robert.burton@email.com"
    align="left"
    label-position="inline"
    inline-label-size="md"
  ></sl-data-pair>

  <sl-data-pair
    label="Phone"
    value="0412345678"
    align="left"
    label-position="inline"
    inline-label-size="md"
  ></sl-data-pair>

  <sl-data-pair
    label="Preferred contact"
    value="Email"
    align="left"
    label-position="inline"
    inline-label-size="md"
  ></sl-data-pair>
</div>

Long Inline Labels

Label width as mentioned above can come in multiple-fixed widths to provide visual balance. In the cases that long-labels exceed the desired length or the specified maximum width, the label should wrap OR truncate. Default is wrapping but which method to use should be specified by the designer. This is an edge case because best practice is to keep labels short and concise.

To truncate the label, set the truncate-label attribute to the maximum number of characters to display. 

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
  <sl-data-pair
    label="Long inline labels - this is an inline label example to demonstrate labels that exceed the xl width size. The label should wrap."
    value="Value"
    label-position="inline"
    inline-label-size="xl"
  ></sl-data-pair>

  <sl-data-pair
    label="Long inline labels - this is an inline label example to demonstrate labels that exceed the xl width size. The label should wrap."
    value="Value"
    label-position="inline"
    inline-label-size="xl"
    label-wrap="false"
  ></sl-data-pair>
</div>

Value

Value is a slot for the accompanying data. Default value is text but custom HTML and other components can be used. 

<div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 24px;">
  <sl-data-pair
    label="Label"
    value="Value"
  ></sl-data-pair>

  <sl-data-pair
    label="Value"
    value="Label"
  ></sl-data-pair>

    <sl-data-pair
    label="Label"
    value=12345
    label-position="inline"
  ></sl-data-pair>
</div>

Value - Prefix & Suffix slots

There are multiple slots within the value field to account for icons, dollar signs, percentages, or any other similar element. 

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
  <sl-data-pair
    label="Rollover amount"
    value="$10,000"
    label-position="bottom"
  >
    <sl-icon name="circle-check" slot="suffix" style="color: var(--hds-color-success-600)"></sl-icon>
  </sl-data-pair>

  <sl-data-pair
    label="Account name"
    value="Wkfjsfcmnsjdfsjfisf"
    label-position="inline"
  >
    <sl-icon name="triangle-exclamation" slot="suffix" style="color: var(--hds-color-danger-600)"></sl-icon>
  </sl-data-pair>

    <sl-data-pair
    label="Account status"
    value="Active"
    label-position="top"
  >
    <sl-icon name="check" slot="prefix" style="color: var(--hds-color-success-600)"></sl-icon>
  </sl-data-pair>
</div>

Value - custom HTML or other components

Value doesn’t only have to be text, it could be anything from other components to images/videos. This can be done using the value slot.

A placeholder image A placeholder image 
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
  <sl-data-pair label="My Image">
    <img
      slot="value"
      src="https://placehold.co/200x100"
      alt="A placeholder image"
      style="height: 100px; width: 200px; border-radius: var(--hds-radius-medium);"
    />
  </sl-data-pair>

    <sl-data-pair label="My Image" label-position="inline">
    <img
      slot="value"
      src="https://placehold.co/200x100"
      alt="A placeholder image"
      style="height: 100px; width: 200px; border-radius: var(--hds-radius-medium);"
    />
  </sl-data-pair>
</div>

Value - Multi-line values

Similar to labels, multi-line values should wrap or truncate depending on the design.

<div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 24px;">
  <sl-data-pair
    label="Label"
    value="Long values - this is a long value example to demonstrate values that are multi-lined."
  >
    <sl-icon name="circle-check" slot="suffix" style="color: var(--hds-color-success-600)"></sl-icon>
  </sl-data-pair>

  <sl-data-pair
    label="Label"
    value="Long values - this is a long value example to demonstrate values that are multi-lined."
    label-position="bottom"
  ></sl-data-pair>

  <sl-data-pair
    label="Label"
    value="Long values - this is a long value example to demonstrate values that are multi-lined."
    label-position="inline"
  >
    <sl-icon name="circle-check" slot="suffix" style="color: var(--hds-color-success-600)"></sl-icon>
  </sl-data-pair>
</div>

States

Data pair is a read-only component and doesn’t require interactive states. Any interactive components slotted in should retain their interactive states but should be specified by the designer if that is the intent.

[component-metadata:sl-data-pair]

Slots

Name Description
label The label slot, if not provided the label property will be used.
prefix A slot for content to be placed before the label.
suffix A slot for content to be placed after the label.
(default) The default slot, used for the value.
prefix A slot for content to be placed before the value.
suffix A slot for content to be placed after the value.

Learn more about using slots.

Properties

Name Description Reflects Type Default
size The size of the data pair 'small' | 'medium' | 'large' 'medium'
align The alignment of the content 'left' | 'center' | 'right' 'left'
labelPosition
label-position 		The position of the label relative to the value 'top' | 'bottom' | 'inline' 'top'
inlineLabelSize
inline-label-size 		The fixed width of the inline label container. 'hug' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' 'hug'
labelWrap
label-wrap 		Determines whether the label is allowed to wrap. boolean true
label The label text string ''
value The value to display string | number ''
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Custom Properties

Name Description Default
--form-control-label-width The width of the label when label-position is ‘inline’.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.
label The label element.
value The value element.

Learn more about customizing CSS parts.