Text Input

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.

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.

  Additional accessibility test and build content is coming soon, in a new format.

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>

Aria Label

Use the visible label property for nearly every field. It provides a visible, programmatically associated label, which is what most forms need and is required for accessibility.

Use the ariaLabel property only for narrow cases where a visible label genuinely doesn't fit the pattern, such as a standalone "other" input next to a checkbox. It gives the field an accessible name for screen readers without rendering visible label text.

If a visible label (or description) is provided, it takes precedence and ariaLabel is ignored. Do not use placeholder as a substitute for either, as it is not exposed as an accessible label.

<nys-textinput ariaLabel="Other reason" placeholder="Other reason"></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. Note: The showError attribute is a boolean that toggles automatically based on other validation. setting showError to true manually will only set the error message to be visible on initial render, once the user interacts with the component, showError will toggle based on validation rules (e.g., required, pattern, etc.)

<nys-textinput errorMessage="This is an error message" showError label="Label with error"></nys-textinput>

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

<nys-textinput errorMessage="This is an error message" showError label="Label with error"></nys-textinput>

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

Usage

Properties

Form Prop

The form property associates this component with a <form> element by ID, even if the component is not a descendant of that form. See Form Patterns for details on form association and ElementInternals.

Style Overrides

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.

Event details

The nys-input event includes a detail object with the following properties:

• id (string): The id of the textinput.
• value (string): The currently selected text.

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) => {
  const { id, value } = event.detail;
  console.log(`Text input (${id}) changed:`, value);
});