# xpl-input A flexible form input that supports multiple `type` values: `text`, `number`, `password`, `date`, `time`, `file`, `color`, `phone`, and `search`. Each type delegates to a dedicated sub-component (`xpl-input-date`, `xpl-input-time`, `xpl-input-phone`, `xpl-input-search`, etc.) while sharing a common label, description, and error-message wrapper. For `type="phone"`, the value is always emitted in **E.164** format (e.g. `+14155551234`). See [`xpl-input-phone`](xpl-input-phone) for full phone-input documentation. ## Design Tokens The `xpl-input` component uses Apollo Foundation tokens for consistent theming across light and dark modes: | Element | Property | Token | |---------|----------|-------| | Input wrapper border (default) | `border-color` | `var(--xpl-border-default)` | | Input wrapper border (focus) | `border-color` | `var(--xpl-border-focus)` | | Input wrapper border (error) | `border-color` | `var(--xpl-border-negative)` | | Input wrapper background (default) | `background-color` | `var(--xpl-background-surface-default)` | | Input/textarea background | `background-color` | `var(--xpl-background-surface-transparent-0)` | | Disabled/readonly wrapper background | `background-color` | `var(--xpl-background-action-disabled)` | | Post element background | `background-color` | `var(--xpl-background-surface-subtle)` | | Input text | `color` | `var(--xpl-text-default)` | | Disabled/readonly text | `color` | `var(--xpl-text-disabled)` | | Label text | `color` | `var(--xpl-text-strong)` | | Description text | `color` | `var(--xpl-text-subdued)` | | Error text | `color` | `var(--xpl-text-negative)` | | Character counter background (default) | `background-color` | `var(--xpl-background-surface-default)` | | Character counter background (disabled/readonly) | `background-color` | `var(--xpl-background-action-disabled)` | | Character counter text | `color` | `var(--xpl-text-subdued)` | | Calendar/password icon | `color` | `var(--xpl-icon-default)` | ### Spacing Tokens | Element | Property | Token | |---------|----------|-------| | Input | `padding-right` | `var(--xpl-space-8)` | | Textarea | `padding-top` | `var(--xpl-space-12)` | | Textarea | `padding-bottom` | `var(--xpl-space-8)` | | Wrapper | `padding-left` | `var(--xpl-space-12)` | | Pre element (leading icon/text) | `padding-right` | `var(--xpl-space-8)` | | Post element (trailing unit / AM-PM) | `padding-left`, `padding-right` | `var(--xpl-space-12)` | | Label | `padding-bottom` | `var(--xpl-space-4)` | | Character counter | `padding` | `var(--xpl-space-8) var(--xpl-space-12)` | | Error message | `padding`, `gap` | `var(--xpl-space-4)` | | Calendar icon | `right` | `var(--xpl-space-12)` | | Password button | `padding-left`, `padding-right` | `var(--xpl-space-12)` | ### Dimension Tokens | Element | Property | Token | |---------|----------|-------| | Input | `height` | `var(--xpl-size-250)` (40px; matches Figma `form/height`) | | Textarea | `min-height` | `var(--xpl-size-250)` (40px) | | Textarea | `height` | `var(--xpl-size-700)` (112px; rounded up from 98px) | | Wrapper | `border-width` | `var(--xpl-border-small)` | | Wrapper | `border-radius` | `var(--xpl-border-radius-small)` (4px; matches Figma `border/radius/small`) | | Post element | `height` | `var(--xpl-size-250)` (40px; vertically centered via flex) | | Post element | `border-left-width` | `var(--xpl-border-small)` | ### Delegated types (`search`, `phone`, `date`, `time`, …) `valueChange`, `inputEvent`, `focusEvent`, and `blurEvent` are emitted by the inner component and **bubble** to ``. For **`type="search"`**, **`focusEvent`** and **`blurEvent`** are **re-emitted from ``** (parent uses **`onFocusEvent`** / **`onBlurEvent`** on **``** with **`stopPropagation`**) so **`event.target`** matches **`type="text"`**. For **`valueChange`** and **`inputEvent`** on search, events still **bubble** from **`xpl-input-search`** without parent re-emission; **`event.target`** may be the inner host—prefer **`event.detail`** (the string) or **`event.currentTarget`** when you attach the listener on **``**. Other delegated types follow the same **`event.detail`** / **`event.currentTarget`** guidance. For **`type="search"`** commit: **``** defines a Stencil **`@Event() search`** (trimmed query in **`detail`**). **``** listens with **`onSearch`** on the inner tag, **`stopPropagation`s**, then **`this.search.emit(detail)`** so the canonical **`search`** **`@Event`** stays on **``** and listeners are not doubled. **`setFocus()`** on **``** uses a **`ref`** to the inner component to delegate focus. ## Properties | Property | Attribute | Description | Type | Default | | --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------- | | `_id` | `_id` | Because `id` is a reserved HTMLElement attribute, we prefix it with an underscore here so that it doesn't get automatically applied to the outer container. Applies to all input types. | `string` | `undefined` | | `accept` | `accept` | The accepted file types for the file input. Corresponds to the `accept` attribute on the input element. Example: 'image/*' for all image types, '.pdf' for PDF files, etc. Applies to file inputs. | `string` | `''` | | `allowCustomOption` | `allow-custom-option` | For time inputs, whether to allow custom option in the input even if not available in the dropdown. Example: A step of 30 minutes will allow 15:03, 15:37, etc. Applies to time inputs. | `boolean` | `false` | | `ariaLabel` | `aria-label` | Accessible name for search inputs when there is no visible `label` (after trim). Ignored for naming when a visible label is shown. Defaults to `''`; whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed when there is no visible label. Applies to search inputs (`type="search"`). | `string` | `''` | | `autocomplete` | `autocomplete` | Hint for form autofill feature Applies to text, password, number, and search inputs. | `string` | `undefined` | | `dateFormat` | `date-format` | The date format to use for the datepicker input. This is used by flatpickr to format the date. Default is 'Y-m-d' (e.g., 2023-10-01). See https://flatpickr.js.org/formatting/ for more details. Applies to date inputs. | `string` | `'Y-m-d'` | | `defaultCountry` | `default-country` | Default country code (ISO 3166-1 alpha-2) when value is empty, e.g. "US". Applies to phone inputs. | `string` | `'US'` | | `description` | `description` | Optional text that appears below the input label. Applies to all input types. | `string` | `undefined` | | `disabled` | `disabled` | Whether the field is disabled Applies to all input types. | `boolean` | `undefined` | | `error` | `error` | If an empty string (attribute present with no value), will display visually as an error. If a string is included, will display visually as an error and include the value as an error message. Applies to all input types. | `string` | `undefined` | | `hideAcceptText` | `hide-accept-text` | Hides the "Accept" text that indicates the accepted file types This is useful for cases where you want to hide the "Accept" text. Applies to file inputs. | `boolean` | `false` | | `hideEyeDropper` | `hide-eye-dropper` | Hide eye dropper Applies to color inputs. | `boolean` | `undefined` | | `hideFileNames` | `hide-file-names` | Hides the file names in the file upload component This is useful for cases where you want to hide the file names after selection. Applies to file inputs. | `boolean` | `false` | | `hideTriggerOnSelect` | `hide-trigger-on-select` | Hides the trigger element when a file is selected. This is useful for cases where you want to hide the trigger after a file is selected. Applies to file inputs. | `boolean` | `false` | | `isInternational` | `is-international` | Enables international mode with country selector for phone inputs. When false, the phone input is locked to defaultCountry with no country picker. | `boolean` | `true` | | `label` | `label` | Label text for the field Applies to all input types. | `string` | `undefined` | | `max` | `max` | Maximum value for the input. Applies to number, time, and date inputs. If the input is a time input, the value must be in 24 hour format, ex: 18:25 for 6:25 PM | `number \| string` | `undefined` | | `maxCharacterCount` | `max-character-count` | For multiline inputs, a max. character count will display along with the current character count, and will automatically render as an error if the character count exceeds the max. This is only applicable if `multiline` is `true`. | `number` | `undefined` | | `min` | `min` | The minimum value for the input. Applies to number, time, and date inputs. If the input is a time input, the value must be in 24 hour format, ex: 05:25 for 5:25 AM | `number \| string` | `undefined` | | `mode` | `mode` | For datepicker inputs, whether to allow only a single date or a range of dates. (Multiple non-consecutive dates planned to be supported in the future.) Applies to date inputs. | `"range" \| "single"` | `'single'` | | `multiline` | `multiline` | Whether to render as a singleline text input or as a multiline textarea. (If `true`, `pre` and `post` values will be ignored, if present.) Applies to text inputs. | `boolean` | `false` | | `multiple` | `multiple` | Whether the user can select multiple files at once. Corresponds to the `multiple` attribute on the input element. Applies to file inputs. | `boolean` | `false` | | `name` | `name` | Most inputs are used in forms, and should have a `name` associated with the input for handling form data. Applies to all input types. | `string` | `undefined` | | `placeholder` | `placeholder` | Placeholder text that appears when the field has no value Applies to text, password, number, date, and search inputs. | `string` | `undefined` | | `post` | `post` | A string (recommended max 3 characters) that gets shown visually to the left of (before) the input. Applies to text, password, number, and date inputs. Note: This will be ignored if `multiline` is `true`. | `string` | `undefined` | | `pre` | `pre` | A string (recommended max 8 characters) that gets shown visually to the right of (after) the input. Applies to text, password, number, and date inputs. Note: This will be ignored if `multiline` is `true`. | `string` | `undefined` | | `preferredCountries` | -- | Country codes to show at the top of the country list, e.g. ["US", "CA", "GB"]. Applies to phone inputs. | `string[]` | `undefined` | | `readonly` | `readonly` | Whether the input is editable Applies to text, password, number, date, and search inputs. | `boolean` | `undefined` | | `required` | `required` | Whether the input is required Applies to all input types. | `boolean` | `undefined` | | `shape` | `shape` | Shell corner radius for search inputs: `rounded` (pill) or `box` (rounded rectangle). Applies to search inputs (`type="search"`). | `"box" \| "rounded"` | `undefined` | | `step` | `step` | The granularity that the value in a `number` input must adhere to when incrementing or decrementing. The default stepping value for number inputs is 1 Applies to number and time inputs. | `number` | `undefined` | | `timeFormat` | `time-format` | The time format to display for the input. Applies to time inputs. If 12h is selected, the value will be displayed in 12 hour format, ex: 05:25 PM for 17:25 If 24h is selected, the value will be displayed in 24 hour format, ex: 17:25 for 17:25 | `"12h" \| "24h"` | `'24h'` | | `type` | `type` | The type of form control | `"color" \| "date" \| "file" \| "number" \| "password" \| "phone" \| "search" \| "text" \| "time"` | `'text'` | | `value` | `value` | Including a `value` will pre-populate the input with the given string. Applies to text, password, number, date, and search inputs. | `string` | `undefined` | ## Events | Event | Description | Type | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | | `blurEvent` | The event handler for the blur event | `CustomEvent` | | `focusEvent` | The event handler for the focus event | `CustomEvent` | | `inputEvent` | Event that emits the current value of the input Applies to text-like inputs and search inputs. | `CustomEvent` | | `search` | Emitted when the user commits a search (Enter with no enclosing form owner, or submit of the internal search form). `event.detail` is the trimmed query string. Applies to search inputs (`type="search"`). | `CustomEvent` | | `valueChange` | Event that emits the current value of the input (including search fields). | `CustomEvent` | ## Methods ### `setFocus() => Promise` Moves keyboard focus to the native control (text field, textarea, or search inner input). #### Returns Type: `Promise` ## Dependencies ### Used by - [xpl-input-color](xpl-input-color) - [xpl-input-phone](xpl-input-phone) - [xpl-input-time](xpl-input-time) ### Depends on - [xpl-input-file](xpl-input-file) - [xpl-input-color](xpl-input-color) - [xpl-input-date](xpl-input-date) - [xpl-input-time](xpl-input-time) - [xpl-input-phone](xpl-input-phone) - [xpl-input-search](xpl-input-search) - [xpl-icon](../xpl-icon) ### Graph ```mermaid graph TD; xpl-input --> xpl-input-file xpl-input --> xpl-input-color xpl-input --> xpl-input-date xpl-input --> xpl-input-time xpl-input --> xpl-input-phone xpl-input --> xpl-input-search xpl-input --> xpl-icon xpl-input-file --> xpl-icon xpl-input-color --> xpl-input xpl-input-date --> xpl-icon xpl-input-time --> xpl-input xpl-dropdown --> xpl-dropdown-group xpl-dropdown --> xpl-dropdown-option xpl-dropdown-group --> xpl-dropdown-group xpl-dropdown-group --> xpl-dropdown-option xpl-dropdown-group --> xpl-dropdown-heading xpl-dropdown-option --> xpl-icon xpl-input-phone --> xpl-input xpl-input-search --> xpl-icon style xpl-input fill:#f9f,stroke:#333,stroke-width:4px ``` ---------------------------------------------- *Built with [StencilJS](https://stenciljs.com/)*