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.

Example Code 
<nys-textinput label="This is a text input"></nys-textinput>

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.

Example Code 
<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"

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

Placeholder

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

Disabled

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

Readonly

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

Min Max and step

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

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

Maxlength

Example Code 
<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.

Example Code 
<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>

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.

Example Code 
<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.

Do

  • Use clear and concise labels to describe the input required.
  • Provide helper text to guide the user, but don’t rely on placeholders as a substitute for labels.
  • Validate input in real-time to catch errors early (e.g., invalid email formats).

Don't

  • Don't use single-line text inputs for collecting long or detailed text responses (use a textarea).
  • Don't overwhelm users with too many single-line inputs; group similar fields when possible.

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

Property Type
label string
value string
id string
name string
type string ("email", "number", "password", "search", "tel", "text", "url")
description string
placeholder string
disabled boolean
readonly boolean
required boolean
form string
pattern REGEX
maxlength integer
width string ('sm", "md", "lg", "full")
step integer
min integer
max integer
showError boolean
errorMessage string

CSS Variables


Events

The nys-textinput component emits three custom Javascript events:

  1. nys-checkValidity – Fired when the textinput state changes.
  2. focus – Fired when the textinput gains focus.
  3. 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-checkValidity' event
textinput.addEventListener('nys-checkValidity', (event) => {
  console.log('Text input changed:', event.target.value);
});