Polarity Integration Component Library

Key Value Component

Displays a key-value pair with optional date formatting, boolean value mapping, and info-icon tooltips, hiding itself when the value is empty unless a default value is provided.

Installation

npm install @polarityio/pi-key-value

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-key-value';

<!-- Basic key-value pair -->
<pi-key-value key="Status" value="Active"></pi-key-value>

<!-- With default value fallback -->
<pi-key-value key="Description" default-value="N/A"></pi-key-value>

<!-- Date formatting -->
<pi-key-value key="Created" value="2024-01-15T10:30:00Z" date></pi-key-value>

<!-- Custom date format in UTC -->
<pi-key-value key="Updated" value="2024-01-15T10:30:00Z" date-format="MM/dd/yyyy" utc></pi-key-value>

<!-- Boolean value mapping -->
<pi-key-value key="Enabled" value="true" truthy-value="Yes" falsy-value="No"></pi-key-value>

API Reference

Properties

| Property | Type | Default | Description | | -------------- | ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- | | key | string | '' | The label displayed before the value | | value | string \| null \| undefined | undefined | The value to display. Component is hidden when null/undefined/empty unless defaultValue is set | | defaultValue | string | '' | Fallback string when value is null, undefined, or empty | | date | boolean | false | When true, formats value as a date using yyyy-MM-dd HH:mm | | dateFormat | string | '' | Custom date format string using date-fns format syntax. Implies date=true. Takes precedence over format. | | format | 'datetime' \| '' | '' | Named date-fns format preset. Implies date=true. Currently the only preset is datetime (MM/dd/yyyy HH:mm:ss). | | utc | boolean | false | When true, displays the date in UTC instead of local timezone | | truthyValue | string | '' | String to display when value is truthy | | falsyValue | string | '' | String to display when value is falsy (empty string, "0", or "false") | | keyTooltip | string | '' | Tooltip text for an info icon displayed after the key label | | valueTooltip | string | '' | Tooltip text for an info icon displayed after the value |

Theming

Customize the appearance using CSS custom properties. This component uses design tokens from @polarityio/pi-shared for consistent theming across the component library.

CSS Custom Properties

| Property | Default | Description | | ----------------------------------- | ------------------------------ | ------------------------------ | | --pi-key-value-color | var(--pi-color-font-primary) | Color of the value text | | --pi-key-value-tooltip-icon-color | var(--pi-color-font-secondary) | Color of the tooltip info icon |

<!-- Custom value color -->
<pi-key-value key="Status" value="Active" style="--pi-key-value-color: var(--pi-color-font-success);"></pi-key-value>
<pi-key-value key="Severity" value="Critical" style="--pi-key-value-color: var(--pi-color-font-danger);"></pi-key-value>

Tooltips

Use key-tooltip and/or value-tooltip to display an info icon (ℹ) with hover tooltip text next to the key or value.

<!-- Info icon after the key -->
<pi-key-value key="Risk Score" value="87" key-tooltip="Calculated from multiple threat feeds"></pi-key-value>

<!-- Info icon after the value -->
<pi-key-value key="Status" value="Active" value-tooltip="This entity is currently being monitored"></pi-key-value>

<!-- Both key and value tooltips -->
<pi-key-value
  key="Threat Score"
  value="92"
  key-tooltip="Aggregated score from all sources"
  value-tooltip="Scores above 80 are critical">
</pi-key-value>

License

MIT