Inputs

Input elements are used to gather information from users.

Base style

Inputs are normally paired with a label, but there times when they can be used without a label. Placeholder text should primarily be used as a content prompt and only provided when needed.

<div class="grid gs4 gsy fd-column">
    <div class="grid--cell">
        <label class="d-block s-label" for="example-item1">
            Full name
            <p class="s-description mt2">This will be shown only to employers and other Team members.</p>
        </label>
    </div>
    <div class="grid ps-relative">
        <input class="s-input" id="example-item1" type="text" placeholder="Enter your input here" />
    </div>
</div>

<div class="grid gs4 gsy fd-column ps-relative">
    <label class="grid--cell s-label" for="example-item2">Display name</label>
    <div class="grid ps-relative">
        <input class="s-input" id="example-item2" type="text" placeholder="Enter your input here" disabled />
        @Svg.Lock.With("s-input-icon fc-black-300")
    </div>
</div>

Accessibility

The best accessibility is semantic HTML. Most screen readers understand how to parse inputs if they're correctly formatted. When it comes to inputs, there are a few things to keep in mind:

  • All inputs should have an id attribute.
  • Be sure to associate the input’s label by using the for attribute. The value here is the input’s id.
  • If you have a group of related inputs, use the fieldset and legend to group them together.

For more information, please read Gov.UK's article, "Using the fieldset and legend elements".

Validation states

Validation states provides the user feedback based on their interaction (or lack of interaction) with an input. These styles are applied by applying the appropriate class to the wrapping parent container.

Validation classes

Class Applies Definition
.has-warning Parent wrapper for input Used to warn users that the value they've entered has a potential problem, but it doesn't block them from proceeding.
.has-error Parent wrapper for input Used to alert users that the value they've entered is incorrect, not filled in, or has a problem which will block them from proceeding.
.has-success Parent wrapper for input Used to notify users that the value they've entered is fine or has been submitted successfully.

Validation guidance

In most cases, validation states shouldn’t be shown until after the user has submitted the form. There are certain exceptions where it can be appropriate to show a validation state without form submission—after a sufficient delay. For example, validating the existence of a username can occur after the user has stopped typing, or when they’ve deselected the input.

Once the user is presented validation states, they can be cleared as soon as the user interacts with the form field. For example, the error state for an incorrect password should be cleared as soon as the user focuses the input to re-enter their password.

Validation examples

Warning

<div class="grid gs4 gsy fd-column has-warning">
    <label class="grid--cell s-label" for="example-warning">Username</label>
    <div class="grid ps-relative">
        <input class="s-input" id="example-warning" type="text" placeholder="" />
        @Svg.Alert.With("s-input-icon")
    </div>
    <p class="grid--cell s-input-message">Caps lock is on! <a>Having trouble entering your username?</a></p>
</div>

Caps lock is on! Having trouble entering your username?

Error

<div class="grid gs4 gsy fd-column has-error">
    <label class="grid--cell s-label" for="example-warning">Username</label>
    <div class="grid ps-relative">
        <input class="s-input" id="example-warning" type="text" placeholder="e.g. johndoe111" />
        @Svg.AlertCircle.With("s-input-icon")
    </div>
    <p class="grid--cell s-input-message">You must provide a username. <a>Forgot your username?</a></p>
</div>

You must provide a username. Forgot your username?

Success

<div class="grid gs4 gsy fd-column has-success">
    <label class="grid--cell s-label" for="example-warning">Username</label>
    <div class="grid ps-relative">
        <input class="s-input" id="example-warning" type="text" placeholder="e.g. johndoe111" />
        @Svg.Checkmark.With("s-input-icon")
    </div>
    <p class="grid--cell s-input-message">That name is available! <a>Why do we require a username?</a></p>
</div>

That name is available! Why do we require a username?

Icons

Stacks provides helper classes to consistently style an input used for search. First, wrap your search input in an element with relative positioning. Then, and add s-input__search to the input itself. Finally, be sure to add s-input-icon and s-input-icon__search to the search icon.

<div class="ps-relative">
    <input class="s-input s-input__search" type="text" placeholder="Search…" />
    @Svg.Search.With("s-input-icon s-input-icon__search")
</div>

Credit Card

<div class="ps-relative">
    <input class="s-input s-input__creditcard" type="text" />
    @Svg.CreditCard.With("s-input-icon s-input-icon__creditcard")
</div>

Sizes

Name Size Class Example
Small 12px .s-input__sm
Default 13px N/A
Medium 17px .s-input__md
Large 21px .s-input__lg
Extra Large 27px .s-input__xl

Input fills

Input fills are used to visually connect input text boxes with related content.

Prepended inputs

<div class="grid gs4 gsy fd-column">
    <label class="grid--cell s-label" for="website-url">Website URL</label>
    <div class="grid">
        <div class="grid--cell s-input-fill order-first">https://</div>
        <div class="grid fl1 ps-relative">
            <input class="grid--cell s-input blr0" type="text" id="website-url" placeholder="www.stackoverflow.com" />
        </div>
    </div>
</div>
https://

Appended inputs

<div class="grid gs4 gsy fd-column">
    <label class="grid--cell s-label" for="min-salary">Minimum Salary</label>
    <div class="grid">
        <div class="grid ai-center order-last s-input-fill">
            <div class="grid gs4 gsx ai-center">
                <input class="grid--cell s-checkbox" type="checkbox" id="need-visa" />
                <label class="grid--cell s-label s-label__sm fw-normal" for="need-visa">Need Visa Sponsorship</label>
            </div>
        </div>
        <div class="grid fl1 ps-relative">
            <input class="grid--cell s-input brr0" type="number" id="min-salary" placeholder="e.g. 125,000" />
        </div>
    </div>
</div>

Types

The most common input is type="text", yet there are many other input types that can be used depending on the content type being gathered. Below is a list of available types and when you should consider using them:

Type Description
color HTML5 Allows user to select a color and returns the hex value for that color. The color picker used is native to the OS or the browser.
date HTML5 Allows user to enter a date (year, month, and day) without a time.
datetime-local HTML5 Allows user to enter a date (year, month, and day) and a time, with no time zone.
email HTML5 Allows user to enter an email address. Some mobile devices will deliver custom keyboards specifically for entering email addresses.
file Allows user to select a file. To define the type of files that can be selected, use the accept="" attribute.
month HTML5 Allows user to enter a month and year with no time zone.
number HTML5 Limits user to entering only numbers. Some mobile devices will deliver a custom keyboard.
password Single-line text input whose value is obsecured. Use the minlength and maxlength attributes to specify the value length.
range HTML5 Allows user to enter a number who exact value isn't important.
search HTML5 Single-line text input for entering search strings. Some mobile devices will deliver a custom keyboard.
tel HTML5 Allows user to enter a telephone number. Some mobile devices will deliver a custom keyboard.
text Single-line text input field.
time HTML5 Allows user to enter a time value with no time zone.
url HTML5 Allows user to enter a website URL. Some mobile devices will deliver a custom keyboard.
week HTML5 Allows user to enter a date consisting of a week-year number and a week number with no time zone.

Attributes

There are a number of attributes available for inputs. These attributes allow you to help the user understand what data type or format you are requesting.

Attribute Description
accept If the type is file, then this attribute will indicate the file types that will be accepted. The value must be a comma-separated list.
autocomplete HTML5 Indicates if the control value can be automatically completed by the browser. For a full list of possible values, please visit MDN Inputs page.
autofocus HTML5 Lets you specify which form control should have input focus on page load. Only one element can have this attribute and it cannot be set on hidden elements.
capture If the type is file, then this Boolean attribute will indicate that the capture of media directly from the device's environment using a media capture mechanicism is preferred (e.g. taking a photo using a camera).
disabled Boolean attribute that indicates the input is not available for interaction.
form HTML5 This attribute associates the form element with the input element. The input value must be the form's id value within the same document. If this isn't specified, the input will use the closest ancestor form element. This attribute allows you to place inputs anywhere on the page, not just as a descendant within a form element. An input can only be associated with one form.
max HTML5 Maximum numeric or date-time value for this item, which cannot be lesser than the minimum value.
maxlength HTML5 If type is text, email, search, password, tel, or url; this attribute sets the maximum number of characters that can be entered.
min HTML5 Minimum numeric or date-time value for this item, which cannot be greater than the minimum value.
minlength HTML5 If type is text, email, search, password, tel, or url; this attribute sets the minimum number of characters that must be entered.
multiple HTML5 If type is email or file, this attribute allows for more than one value.
name Name of the control which is submitted with the form data.
placeholder HTML5 Provides a hint to the user of what can be entered into the control.
readonly HTML5 Indicates that the control cannot be modified by the user. This is ignored if the type attribute is hidden, range, color, checkbox, radio, or a button type.
required HTML5 Specifies that the user must provide a value for this control before submitting the form. This is ignored if the type attribute is hidden, image, or a button type.
selectionDirection HTML5 Specifies the direction in which a selection occurs.
selectionEnd The offset into the element's text content of the last selected character. If there's no selection, this value indicates the offset to the character following the current text input cursor position (that is, the position the next character typed would occupy).
selectionStart The offset into the element's text content of the first selected character. If there's no selection, this value indicates the offset to the character following the current text input cursor position (that is, the position the next character typed would occupy).
size The control's initial size.
spellcheck HTML5 Setting the value to true indicates that the element needs to have its spelling and grammar checked.
step HTML5 Works with min and max attributes to limit the increments at which a numeric or date-time value can be set.
tabindex HTML5 Position of the element in the tab navigation order for the current document.
value Initial value for the control.