Polarity Integration Component Library

Error Component

An error alert component that displays error information with a close button, optional title and icon, automatic message resolution from error objects, expandable JSON details, and clipboard copy.

Installation

npm install @polarityio/pi-error

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-error';

Basic Error

<pi-error open error-title="Error" message="An unexpected error occurred."></pi-error>

No Title (Message-Only Header)

When no error-title is provided, the message is displayed inline in the header row. This is useful for compact, single-line error alerts.

<pi-error open message="Something went wrong. Please try again."></pi-error>

With an Error Object

When an error object is provided, the component resolves the message automatically:

1. If the error has a detail property, it is displayed as the message.
2. Otherwise, if the error has a message property, that is displayed.

The full error object is available in the expandable "View Details" section and can be copied to the clipboard.

import { html } from 'lit';

html`
  <pi-error
    open
    error-title="Request Failed"
    .error=${{
      status: 500,
      detail: 'The upstream service returned an invalid response.',
      requestId: 'abc-123-def-456'
    }}
  ></pi-error>
`;

Explicit Message Override

When both a message property and an error object are provided, the explicit message takes priority over the error's detail or message fields.

import { html } from 'lit';

html`
  <pi-error
    open
    error-title="API Error"
    message="This explicit message overrides the error object."
    .error=${{ detail: 'Original detail', status: 403 }}
  ></pi-error>
`;

Warning Variant

<pi-error
  open
  variant="warning"
  error-title="Warning"
  message="This action may have unintended consequences."
></pi-error>

Custom Prefix Icon

import { html } from 'lit';
import { faBug } from '@fortawesome/free-solid-svg-icons';

html`
  <pi-error open error-title="Bug Detected" message="An internal error was detected." .prefixIcon=${faBug}></pi-error>
`;

No Prefix Icon

Set prefixIcon to null to hide the icon entirely.

import { html } from 'lit';

html` <pi-error open error-title="Error" message="No icon displayed." .prefixIcon=${null}></pi-error> `;

No Title and No Icon

Combine both to show a minimal message-only alert with no icon.

import { html } from 'lit';

html` <pi-error open message="Something went wrong. Please try again." .prefixIcon=${null}></pi-error> `;

API Reference

Properties

| Property | Attribute | Type | Default | Description | | ------------ | ------------- | ------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | open | open | boolean | false | Controls the visibility of the error component. | | variant | variant | 'danger' \| 'warning' | 'danger' | Visual style variant. Controls background, border, and accent colors. | | errorTitle | error-title | string | '' | Title text displayed in the error header. Leave empty to show only the message in the header row. | | prefixIcon | — | IconDefinition \| null | faCircleExclamation | FontAwesome icon displayed before the title. Set to null to hide. | | error | — | Record<string, unknown> | undefined | The error object. If it has a detail property, that is used as the message. Otherwise message is used. The full object is shown in the expandable details section. | | message | message | string | '' | Explicit message text. Overrides any message derived from the error object. |

Events

| Event Name | Detail | Description | | ------------------------- | ----------------------- | -------------------------------------------------------- | | pi-error-close | {} | Fired when the close button is clicked. | | pi-error-details-toggle | { expanded: boolean } | Fired when the details section is expanded or collapsed. |

CSS Custom Properties

| Property | Default | Description | | ------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --pi-error-background | (variant token) | Override the container background color. | | --pi-error-border-color | (variant token) | Override the container border color. | | --pi-error-border-radius | var(--pi-size-radius-lg, 8px) | Container border radius. | | --pi-error-icon-size | 1em | Title icon size. | | --pi-error-icon-color | (variant token) | Override the title icon color. | | --pi-error-title-color | (variant token) | Override the title text color. | | --pi-error-message-color | var(--pi-color-font-primary) | Message text color. | | --pi-error-details-max-height | 300px | Maximum height of the details section before scrolling. The details section is vertically resizable — dragging the resize handle past the max-height removes the cap. |

Scrollable Details

The "View Details" section automatically uses a thin scrollbar and is vertically resizable. Override the default max-height with --pi-error-details-max-height:

<pi-error
  open
  error-title="Error"
  style="--pi-error-details-max-height: 150px;"
  .error=${{ status: 502, detail: 'Bad Gateway', stack: '...' }}
></pi-error>

Accessibility

• The error container has role="alert" to announce content to screen readers.
• The close button is a pi-button with icon-only and a label of "Close Error", providing full keyboard and screen reader accessibility.
• The View Details / Hide Details button is a standard pi-button with visible text.
• Copy button provides a "Copied error" success message.

Theming

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

The danger variant uses --pi-color-*-danger tokens and the warning variant uses --pi-color-*-warning tokens. You can override individual styles via the --pi-error-* CSS custom properties listed above.

License

MIT