Polarity Integration Component Library

Input Component

A text input component supporting multiple input types with validation, clearable functionality, password visibility toggle, and comprehensive error state management.

Installation

npm install @polarityio/pi-input

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-input';

<!-- Basic text input -->
<pi-input label="Username" placeholder="Enter your username"></pi-input>

<!-- Password input with toggle visibility -->
<pi-input type="password" label="Password" placeholder="Enter password"></pi-input>

<!-- Clearable input -->
<pi-input clearable placeholder="Search..." value="some text"></pi-input>

<!-- Number input with constraints -->
<pi-input type="number" label="Quantity" min="0" max="100" step="1"></pi-input>

<!-- Input with error message -->
<pi-input label="Email" type="email" error error-message="Please enter a valid email"></pi-input>

<!-- With prefix and suffix slots -->
<pi-input placeholder="Amount">
  <span slot="prefix">$</span>
  <span slot="suffix">.00</span>
</pi-input>

Handling Events

const input = document.querySelector('pi-input');

input.addEventListener('pi-input', (e) => {
  console.log('Current value:', e.detail.value);
});

input.addEventListener('pi-change', (e) => {
  console.log('Committed value:', e.detail.value);
});

input.addEventListener('pi-clear', () => {
  console.log('Input cleared');
});

API Reference

Properties

| Property | Type | Default | Description | | -------------- | --------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- | | type | 'text' \| 'number' \| 'password' \| 'email' \| 'search' \| 'tel' \| 'url' | 'text' | Input type | | value | string | '' | Current input value | | placeholder | string | '' | Placeholder text displayed when input is empty | | label | string | '' | Label text displayed above the input | | name | string | '' | HTML name attribute for form submission | | disabled | boolean | false | Disables the input and hides action buttons | | readonly | boolean | false | Makes the input read-only | | clearable | boolean | false | Shows a clear button when the input has a value | | error | boolean | false | Sets error state styling on the input | | errorMessage | string | '' | Error message displayed below the input. Setting this also activates the error state. | | min | string \| undefined | undefined | Minimum value (for number inputs) | | max | string \| undefined | undefined | Maximum value (for number inputs) | | step | string \| undefined | undefined | Step value for number inputs | | maxlength | number \| undefined | undefined | Maximum character length | | minlength | number \| undefined | undefined | Minimum character length | | pattern | string \| undefined | undefined | Regex pattern for validation | | autocomplete | string | 'off' | HTML autocomplete attribute |

Events

| Event Name | Detail | Description | | ----------- | ------------------- | ------------------------------------------------------ | | pi-input | { value: string } | Fired on each keystroke in the input field | | pi-change | { value: string } | Fired when the value changes and the input loses focus | | pi-clear | (none) | Fired when the clear button is clicked |

Slots

| Slot Name | Description | | --------- | -------------------------------------------------------------------------- | | prefix | Content displayed to the left of the input (e.g., icons, currency symbols) | | suffix | Content displayed to the right of the input (e.g., units, icons) |

CSS Custom Properties

| Property | Default | Description | | -------------------------- | ----------------------------------------------- | -------------------------------- | | --pi-input-line-height | 1.75em | Height of the input wrapper | | --pi-input-padding | 4px 8px | Padding inside the input wrapper | | --pi-input-border | 1px solid var(--pi-input-border-color) | Border definition | | --pi-input-border-color | var(--pi-color-border-element) | Border color | | --pi-input-border-radius | var(--pi-size-radius-base, 4px) | Border radius | | --pi-input-background | var(--pi-color-background-container-base) | Background color | | --pi-input-text-color | var(--pi-color-font-primary) | Text color | | --pi-input-disabled-bg | var(--pi-color-background-container-disabled) | Background when disabled |

CSS Parts

| Part Name | Description | | ----------------- | ----------------------------------------------------------------------------- | | wrapper | The main flex container holding the input and action buttons | | input | The native HTML <input> element | | clear-button | The clear (×) button shown when clearable is true and the input has a value | | password-toggle | The password visibility toggle button (eye icon) for password inputs | | error-message | The error message container below the input |

Public Methods

| Method | Description | | ------------------------------- | ------------------------------------------------- | | focus(options?: FocusOptions) | Programmatically focuses the native input element | | select() | Selects all text in the input field |

Theming

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

pi-input {
  --pi-input-border-radius: 8px;
  --pi-input-padding: 8px 12px;
}

pi-input::part(input) {
  font-size: 1rem;
}

License

MIT