The Placer Toolkit alpha has arrived! 🎉
Plenty of changes are coming your way—some big, some breaking, some even nuclear! Beware the changelog…

Bring it on!

Input

<pc-input>

0.4.0

experimental

Inputs collect data from the user.

<pc-input></pc-input>

Code

Edit

This component works well with standard <form> elements. Please refer to the form controls page to learn more about form submission and client‐side validation.

Demos#

Labels#

Use the label attribute to give the input an accessible label. For labels that contain HTML, use the label slot instead.

<pc-input label="What’s your name?"></pc-input>

Code

Edit

Hints#

Add a descriptive hint to an input with the hint attribute. For hints that contain HTML, use the hint slot instead.

<pc-input
    label="Nickname"
    hint="What would you like people to call you?"
></pc-input>

Code

Edit

Placeholders#

Use the placeholder attribute to add a placeholder.

<pc-input placeholder="Type something…"></pc-input>

Code

Edit

Clearable#

Add the clearable attribute to add a clear button when the input has content.

<pc-input placeholder="Clearable" clearable></pc-input>

Code

Edit

Password toggle#

Add the password-toggle attribute to add a toggle button that will show the password when activated.

<pc-input type="password" placeholder="Password" password-toggle></pc-input>

Code

Edit

Filled#

Add the filled attribute to draw a filled input.

<pc-input placeholder="Type something…" filled></pc-input>

Code

Edit

Disabled#

Use the disabled attribute to disable the input.

<pc-input placeholder="Disabled" disabled></pc-input>

Code

Edit

Size#

Use the size attribute to change the input’s size.

<pc-input size="small" placeholder="Small"></pc-input>

<br />

<pc-input size="medium" placeholder="Medium"></pc-input>

<br />

<pc-input size="large" placeholder="Large"></pc-input>

Code

Edit

Pill#

Use the pill attribute to give inputs a pill‐shaped look.

<pc-input size="small" placeholder="Small" pill></pc-input>

<br />

<pc-input size="medium" placeholder="Medium" pill></pc-input>

<br />

<pc-input size="large" placeholder="Large" pill></pc-input>

Code

Edit

Input types#

Use the type attribute to control the input type that the browser renders.

<pc-input type="email" placeholder="E‐mail"></pc-input>

<br />

<pc-input type="number" placeholder="Number"></pc-input>

<br />

<pc-input type="date" placeholder="Date"></pc-input>

Code

Edit

Prefixes and suffixes#

Use the prefix and suffix slots to add presentational icons and text. Avoid slotting in interactive elements, such as buttons and links.

<pc-input size="small" placeholder="Small">
    <pc-icon
        library="default"
        icon-style="solid"
        name="house"
        slot="prefix"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="message"
        slot="suffix"
    ></pc-icon>
</pc-input>

<br />

<pc-input size="medium" placeholder="Medium">
    <pc-icon
        library="default"
        icon-style="solid"
        name="house"
        slot="prefix"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="message"
        slot="suffix"
    ></pc-icon>
</pc-input>

<br />

<pc-input size="large" placeholder="Large">
    <pc-icon
        library="default"
        icon-style="solid"
        name="house"
        slot="prefix"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="message"
        slot="suffix"
    ></pc-icon>
</pc-input>

Code

Edit

Properties#

Name	Description	Default
`type`	The type of input. Works the same as a native `<input>` element, but only a subset of types are supported. Type: `"date" \| "datetime-local" \| "email" \| "number" \| "password" \| "search" \| "tel" \| "text" \| "time" \| "url"`	`"text"`
`name`	The name of the input, submitted as a name/value pair with form data. Type: `string`	`""`
`value`	The current value of the input, submitted as a name/value pair with form data. Type: `string`	`""`
`defaultValue`	The default value of the input. Primarily used for resetting the input. Type: `string`	`""`
`size`	The input’s size. Type: `"small" \| "medium" \| "large"`	`"medium"`
`filled`	Draws a filled input. Type: `boolean`	`false`
`pill`	Draws a pill‐style input. Type: `boolean`	`false`
`label`	The input’s label. If you need to display HTML, use the `label` slot instead. Type: `string`	`""`
`hint`	The input’s hint. If you need to display HTML, use the `hint` slot instead. Type: `string`	`""`
`clearable`	Adds a clear button when the input is not empty. Type: `boolean`	`false`
`disabled`	Disables the input. Type: `boolean`	`false`
`placeholder`	Placeholder text to show as a hint when the input is empty. Type: `string`	`""`
`readonly`	Makes the input readonly. Type: `boolean`	`false`
`passwordToggle` `password-toggle`	Adds a button to toggle the password’s visibility. Only applies when the input’s `type` is set to `password`. Type: `boolean`	`false`
`passwordVisible` `password-visible`	Determines whether or not the password is visible by default. Only applies when the input’s `type` is set to `password`. Type: `boolean`	`false`
`noSpinButtons` `no-spin-buttons`	Hides the browser’s built‐in increment and decrement spin buttons. Only applies when the input’s `type` is set to `number`. Type: `boolean`	`false`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. Type: `string`	`""`
`required`	Indicates if the input must be filled in or not. Type: `boolean`	`false`
`pattern`	A RegEx pattern to validate the input against. Type: `string \| undefined`	‐
`minlength`	The minimum length of input that will be considered valid. Type: `number \| undefined`	‐
`maxlength`	The maximum length of input that will be considered valid. Type: `number \| undefined`	‐
`min`	The input’s minimum value. Only applies when the input’s `type` is set to `date` or `number`. Type: `number \| string \| undefined`	‐
`max`	The input’s maximum value. Only applies when the input’s `type` is set to `date` or `number`. Type: `number \| string \| undefined`	‐
`step`	Specifies the granularity that the value must adhere to, or the special value `any` which means no stepping is implied, allowing any numeric value. Only applies when the input’s `type` is set to `date` or `number`. Type: `number \| "any" \| undefined`	‐
`autocapitalize`	Controls whether and how text input is automatically capitalised as it is entered by the user. Type: `"off" \| "none" \| "on" \| "sentences" \| "words" \| "characters"`	`"none"`
`autocorrect`	Indicates whether the browser’s autocorrect feature is on or off. Type: `boolean`	`false`
`autocomplete`	Specifies what permission the browser has to provide assistance in filling out form field values. Refer to this page on MDN for available values. Type: `string \| undefined`	‐
`autofocus`	Indicates that the input should receive focus on page load. Type: `boolean`	‐
`enterkeyhint`	Used to customise the label or icon of the Enter key on virtual keyboards. Type: `"enter" \| "done" \| "go" \| "next" \| "previous" \| "search" \| "send"`	`"enter"`
`spellcheck`	Enables spellcheck on the input. Type: `boolean`	`true`
`inputmode`	Tells the browser what type of data will be entered by the user, allowing virtual keyboards to display the correct keyboard type to the user. Type: `"none" \| "text" \| "decimal" \| "numeric" \| "tel" \| "search" \| "email" \| "url"`	`"text"`
`valueAsDate`	Gets or sets the current value as a `Date` object. Returns `null` fi the value can’t be converted. This will use the native `<input type="{{type}}" />` implementation and may result in an error.	‐
`valueAsNumber`	Gets or sets the current value as a number. Returns `NaN` if the value can’t be converted.	‐
`validity`	Gets the validity state object.	‐
`validationMessage`	Gets the validation message.	‐
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about attributes and properties.

Slots#

Name	Description
(default)	The input’s label. Alternatively, you can use the `label` attribute.
`prefix`	A presentational prefix icon or similar element.
`suffix`	A presentational suffix icon or similar element.
`clear-icon`	An icon to use to replace the default clear icon.
`show-password-icon`	An icon to use to replace the default show password icon.
`hide-password-icon`	An icon to use to replace the default hide password icon.
`hint`	Text that describes how to use the input. Alternatively, you can use the `hint` attribute.

Learn more about using slots.

Methods#

Name	Description	Arguments
`focus()`	Focuses the input.	`options: FocusOptions`
`blur()`	Unfocuses the input (i.e., blurs it).	‐
`select()`	Selects all the text in the input.	‐
`setSelectionRange()`	Sets the start and end positions of the text selection (0‐based).	`selectionStart: number`, `selectionEnd: number`, `selectionDirection: "forward" \| "backward" \| "none"`
`setRangeText()`	Replaces a range of text with a new string.	`replacement: string`, `start: number`, `end: number`, `selectMode: "select" \| "start" \| "end" \| "preserve"`
`showPicker()`	Displays the browser picker for an input element. This only works if the browser supports it for the input type.	‐
`stepUp()`	Increments the value of a numeric input type by the value of the step attribute.	‐
`stepDown()`	Decrements the value of a numeric input type by the value of the step attribute.	‐
`checkValidity()`	Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.	‐
`getForm()`	Gets the associated form, if one exists.	‐
`reportValidity()`	Checks for validity and shows the browser’s validation message if the input is invalid.	‐
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`

Learn more about methods.

Events#

Name	Description	Event detail
`pc-change`	Emitted when an alteration to the input’s value is committed by the user.	‐
`pc-input`	Emitted when the input receives input.	‐
`pc-focus`	Emitted when the input gains focus.	‐
`pc-blur`	Emitted when the input loses focus (i.e., is blurred).	‐
`pc-clear`	Emitted when the clear button is activated.	‐
`pc-invalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	‐

Learn more about events.

Parts#

Name	Description
`form-control`	The form control that wraps the label, input and hint.
`label`	The input’s label.
`input`	The input.
`hint`	The input’s hint.
`combobox`	The container the wraps the prefix, suffix, input and clear icon.
`prefix`	The container that wraps the prefix slot.
`suffix`	The container that wraps the suffix slot.
`display-input`	The element that displays the input.
`clear-button`	The clear button.

Learn more about customising CSS parts.

Importing#

If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/input/input.js"></script>

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/input/input.js";

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

import "placer-toolkit/dist/components/input/input.js";

Dependencies#

This component automatically imports these components:

Icon