Polarity Integration Component Library

Key Value Component

Displays a key-value pair inline, with multiple ways to provide the value content. Hides itself when no content is available.

The value can be provided in several ways (priority order, highest first):

1. Slot — use <slot name="value"> for arbitrary rich content (links, icons, badges).
2. Link — set the link property to render a pi-external-link as the value.
3. Text — set the value property for plain text (supports date formatting and truthy/falsy mapping).
4. Default — set default-value to display a fallback when value is null/undefined/empty.

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>

<!-- Link as value (with label) -->
<pi-key-value key="Source" link="https://virustotal.com" link-label="VirusTotal"></pi-key-value>

<!-- Link without label (URL displayed, link tooltip disabled) -->
<pi-key-value key="URL" link="https://example.com/path/to/resource"></pi-key-value>

<!-- Rich value via slot -->
<pi-key-value key="Source">
  <pi-external-link slot="value" href="https://virustotal.com">VirusTotal</pi-external-link>
</pi-key-value>

API Reference

Properties

| Property | Type | Default | Description | | -------------- | ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | | key | string | '' | The label displayed before the value | | value | string \| null \| undefined | undefined | Text value to display. Ignored when a value slot or link is provided. Component hides when empty unless default-value is set | | defaultValue | string | '' | Fallback string when value is null, undefined, or empty | | date | boolean | false | When true, formats value as a date using MM/dd/yyyy HH:mm:ss | | dateFormat | string | '' | Custom date format string using date-fns format syntax. Implies date=true. | | 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") | | link | string | '' | A well-formed URL (including scheme) to render as a pi-external-link value. Takes priority over the value property | | linkLabel | string | '' | Display label for the link. When omitted, the URL is shown and the link tooltip is disabled | | unsafeLink | boolean | false | Allow non-https:///http:// URL schemes for the link property. Set only when a non-standard scheme is intentionally needed | | 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 |

Slots

| Name | Description | | ------------- | --------------------------------------------------------------------------------------------------- | | value | Optional slot for rich value content (links, icons, badges). When provided, all other value sources are ignored. | | _pi-tooltip | Internal slot used by nested pi-tooltip components. Do not use directly. |

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