Textinput

The <nys-textinput> is a reusable web component for use in New York State digital products. It allows users to input data to be collected.

Options

Width

If no width is provided, the <nys-textinput> will default to full. Supported widths are sm, md, lg, and full.

Width full will take up the full width of the parent container.

If an invalid option is assigned to width, it will be ignored and default to full.

<nys-textinput width="sm" label="This label is sm"></nys-textinput>

Type

Accepted types are: text, email, number, password, search, tel, url

Any other input defaults to type="text"

<nys-textinput type="password" label="Password"></nys-textinput>

Placeholder

<nys-textinput label="Placeholder" placeholder="this is a placeholder"></nys-textinput>

Disabled

<nys-textinput label="Disabled" disabled></nys-textinput>

Readonly

<nys-textinput readonly label="Readonly" value="Read only value"></nys-textinput>

Min Max and step

max, min, and step only apply when type="number"

<nys-textinput type="number" min="0"  max="100" step="10" label="Max/Min Example" description="Must be between 0 and 100" ></nys-textinput>

Maxlength

<nys-textinput maxlength="10" label="Max Length" description="You cannot type more than 10 characters in the below field"></nys-textinput>

Pattern

Takes any valid regex value.

<nys-textinput placeholder="N00000000" pattern="N[0-9]{8}" label="Please enter your Employee number" description="include the N prefix" maxlength="9" id="nID"></nys-textinput>

Required

Set required to <nys-textinput> to make it mandatory.

<nys-textinput name="myTextInput7" required label="label"></nys-textinput>

Optional

Adding the optional prop will add an optional flag to the input.

<nys-textinput name="myTextInput7" optional label="label"></nys-textinput>

Slotted Description

Add a description using the description prop for plain text, or use the description slot to include custom HTML for more flexibility. Takes any valid regex value.

<nys-textinput name="descriptionSlot" label="Label">
  <label slot="description">Slot: description</label>
</nys-textinput>

Slotted Button

You can add a button to the input by adding a slot="startButton" or slot="endButton". This will add a button to the left or right of the input respectively.

Note: Use a <nys-button> for the slotted button. Do not use both startButton and endButton on the same input.

Note: The slotted button will automatically be size="sm" and variant="filled" and support the disabled state of the input.

Note: Use width="lg" or width="full" on <nys-textinput> to give users enough space to enter text when a button is present.

<nys-textinput 
  name="searchInput"
  type="search" 
  placeholder="Search"
  id="searchInput"
>
  <nys-button
  slot="endButton"
  type="submit"
  label="Search"
  prefixIcon="search"
  id="searchButton"
  ></nys-button>
</nys-textinput>

Error Message

Set an error message and choose to activate it. The error message will appear ONLY when the showError attribute is set to true. Setting only errorMessage will not display the error message by default.

<nys-textinput showError errorMessage="Cannot be left blank" label="Full Name"></nys-textinput>

Usage

When to use this component

• To collect short, single-line text input from the user (e.g., names, email addresses, or short descriptions).
• For open-ended, user-specific input.

When to consider something else

• If you need to collect multiple lines of input, use textarea instead.
• If the input can be chosen from predefined options, use select, radiobutton, or checkbox.

Accessibility

The <nys-textinput> component includes the following accessibility-focused features:

• Proper ARIA roles and attributes to ensure screen readers can interpret the label correctly.
• Keyboard navigation support, allowing users to tab into the input using the keyboard.
• Visual focus indicators to help users navigate the component.
• Include a label property to provide accessible text for screen readers.

Properties

CSS Variables

Events

The <nys-textinput> component emits three custom Javascript events:

1. nys-input – Fired when the textinput state changes.
2. nys-focus – Fired when the textinput gains focus.
3. nys-blur – Fired when the textinput loses focus.

You can listen to these events using JavaScript:

// Select the textinput component
const textinput = document.querySelector('nys-textinput');
// Listen for the 'nys-input' event
textinput.addEventListener('nys-input', (event) => {
  console.log('Text input changed:', event.detail.value);
});