Skip Navigation

Text Input

Text input fields allow users to enter or edit text.

Available in React

Standard Text Input


When to Use

  • Use when there is not a predefined set of answers from which a user can choose.
  • Use when a user may prefer to paste in a response.

When Not to Use

  • Do not use when there is a limited set of options from which a user can choose. Instead, consider a select input in these instances to minimize errors caused by incorrect formatting and typing.

Examples

Usage

  • Place labels inside the input field to allow users to quickly scan the label and enter corresponding data.
  • Use hint text (also called ghost text) when there is a required format for entering data or when additional information may be needed to guide the user’s response. Hint text animates in as soon as the user clicks/taps into the field (see example below). This provides additional details when the user is focused on the field without cluttering the page when he/she is not.
  • Mask sensitive information (such as passwords). Consider adding a control to allow users to unmask data that they have just typed. This is helpful on mobile devices where users tend to make more typing errors.

Examples

Input Validation

Input validation occurs only after a user interacts with a field (meaning the user progressed to another field). Immediate inline validation only occurs when the input is directly correlated with levels of success (e.g. password strength indicator). Error recognition and validation communicates why the input is incorrect along with how to fix the issue. See Voice and Tone for guidance on writing clear and friendly messaging.

Error Messages

Use error messages to indicate something that the user must correct to move forward.


Error and Status Messages

Use error and status messaging to provide immediate feedback to users.


Optional vs. Required Field Indicators

Avoid asking the user to input information that is not required, as this creates an unnecessary burden for the user and decreases completion rates (in sign-up/purchase scenarios). When optional fields can’t be avoided, indicate that they are optional by displaying “Optional” to the right of the label.


Single Line Input with Icon

Actionable icons (dropdown arrows, progress indicator, clear icon, etc.) appear on the right side of the form field. Refer to Icons for additional information.


Disabled Input

Disabled inputs display if information is required prior to completing that particular form field. The visual distinction is important in helping guide the user’s inputs and creating transparency within the form elements.


Multi-line Input

A multi-line input expands vertically as the user reaches the right side of the input field. A character count may also be displayed if there is a limit on the number of characters that may be entered.


When to Use

  • The length of information being asked for is unpredictable (e.g. description, general notes etc.).

Type-Ahead Input

Type-Ahead Phone


Type-Ahead Social Security


When to Use

  • Use Type-Ahead when you want to provide an example of an acceptable input. This is important when a very specific format is required to successfully fill out a form (for example a 10-digit phone number or Social Security Number)

Character Count

Character Count Input


Hard Character Count Input


Variable Height Textarea w/ Soft Character Count

Soft character count will allow the user to keep adding input, but just display an error by how many characters they are over.


When to Use

  • Use a character counter in fields in which a character restriction is in place, or it is useful to know how many characters have been typed.

Additional Guidelines

  • Limiting input length can be useful in scenarios in which design and layout principles limit the amount of content that can be displayed.
  • The character count works its way up to the max number of characters. The characters being typed are reflected in the current count. Once the counter reaches a maximum value, no more characters may be entered and the number turns red.

Developer Notes

Use of the text input requires a JavaScript helper. It can be instantiated using new Spark.TextInput(el). It implements the Messaging and Validation mixins, and provides mechanisms for getting and setting the value.

Order Matters

The <input> element must be the first item inside of the text input container, otherwise the disabled state will not work properly.

The placeholder text will not be immediately visible. Any vital text should instead be placed into the .spark-label field.

The following options may be passed when using new Spark.TextInput(el, {});:

Name Type Default Description
validate function null A function to run to validate the state of the input. It should call onValidate with the parameters outlined below.
validatePattern string null If supplied, this regular expression pattern will be used in the default validate method to determine if an input is in a valid state.
onValidate function null A callback function run after validation has completed. Callback arguments are isValid, newValue, instance.
onChange function null A callback function run when the input value changes. Callback arguments are newValue, instance.
onFocus function null A callback function run when the input gains focus. Callback arguments are newValue, instance.
onBlur function null A callback function run when the input loses focus. Callback arguments are newValue, instance.

For all available methods and full API, refer to the component code on Bitbucket.

Single Line Input

<label class="spark-input">
  <input class="spark-input__field" name="example1" placeholder="Enter Full Name..." role="textbox">
  <span class="spark-label">What is your name?</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Multi-line Input

<label class="spark-input" data-characters-remaining>
  <textarea class="spark-input__field" name="example1" data-maxlength-soft="140" placeholder="Please provide a detailed description of approximately 140 characters." role="textbox"></textarea>
  <span class="spark-label">Description</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Any textarea element inside of the .spark-input-container automatically adjusts its content height if the input has the associated JavaScript applied.

Single Line Input with Icon

<label class="spark-input spark-input--addon">
  <input class="spark-input__field" name="example1" placeholder="Enter First Name..." role="textbox">
  <span class="spark-label">Where are you going? <span class="spark-thin">(Optional)</span></span>
  <div class="spark-input__addon"><i aria-hidden="true" class="spark-icon-location spark-icon--md"></i></div>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

When looking to include an icon within the Text Input, ensure that both the spark-input and spark-input--addon classes are set on the input container. Icon content should then be placed inside an element with a class of spark-input__addon. It is also possible to add an icon class directly to the .spark-input__addon element.

Optional vs. Required Field Indicators

<label class="spark-input">
  <input class="spark-input__field" name="example1" placeholder="Enter Full Name..." role="textbox">
  <span class="spark-label">What is your name? <span class="spark-thin">(Optional)</span></span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Use a class of spark-thin around the optional text to differentiate from the label text.

Disabled Input

<label class="spark-input active">
  <input class="spark-input__field" name="example1" placeholder="Enter First Name..." disabled role="textbox" value="Disabled value">
  <span class="spark-label">Disabled Label</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Adding the disabled attribute to the input element inside of the input container will style the related elements accordingly.

Type Ahead Phone

<label class="spark-input">
  <input type="phone" class="spark-input__field" name="example1" placeholder="(555) 555-5555" data-typeahead data-typeahead-format="(\d\d\d) \d\d\d-\d\d\d\d" role="textbox" required>
  <span class="spark-input__placeholder"></span>
  <span class="spark-label">What is your phone number?</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Type Ahead Social Security

<label class="spark-input">
  <input type="phone" class="spark-input__field" name="example1" placeholder="000-00-0000" data-typeahead data-typeahead-format="\d\d\d-\d\d-\d\d\d\d" role="textbox" required>
  <span class="spark-input__placeholder"></span>
  <span class="spark-label">What is your SSN?</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

The format of the type ahead must be defined in two ways. First, set the placeholder attribute in the proper format you would like to enforce. Then, add the data-typeahead attribute as well as the data-typeahead-format attribute. The format should be the same as what is defined in the placeholder with numbers substituted for the digit escape character (\d).

Error Messages

<label class="spark-input spark-input-email-example">
  <input class="spark-input__field" type="email" name="example1" placeholder="name@domain.com" value="@test.com" required role="textbox">
  <span class="spark-label">Email Address</span>
  <span class="spark-input__message">Invalid email format.</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Error and Status Messages

<label class="spark-input spark-input-password-example">
  <input type="password" class="spark-input__field" name="example1" placeholder="A minimum of 6 characters is required" role="textbox" required>
  <span class="spark-label">Create a password</span>
  <span role="button" aria-label="Show or Hide Password" tabindex="0" class="spark-input__addon spark-input__password-toggle">
    <i class="spark-input__password-show spark-icon--md spark-icon-password-view"></i>
    <i class="spark-input__password-hide spark-icon--md spark-icon-password-hide"></i>
  </span>  
  <span class="spark-input__message"></span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input[type="password"]');
var inputInstance = new Spark.TextInput(el, {
  onChange: function(inst, newVal) {
    if (val.length === 0) {
      inst.clearMessages();
    }
    else if (val.length > 6) {
      inst.setSuccess('<b>NAILED IT!</b> But will you remember it?');
    }
    else if (val.length <= 6 && val.length > 3) {
      inst.setWarning('<b>AVERAGE</b> (at best).');
    }
    else if (val.length <= 3) {
      inst.setError('<b>SHOCKINGLY BAD.</b> Try again.');
    }
  }
});

Character Count Input

<label class="spark-input" data-characters>
  <input class="spark-input__field" name="example1" placeholder="Please provide a detailed description of approximately 140 characters." role="textbox">
  <span class="spark-label">Description</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Hard Character Count Input

<label class="spark-input" data-characters-remaining>
  <input class="spark-input__field" name="example1" maxlength="140" placeholder="Please provide a detailed description. You may include a maximum of 140 characters." role="textbox">
  <span class="spark-label">Description</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

Variable Height Textarea w/ Soft Character Count

<label class="spark-input" data-characters-remaining>
  <textarea class="spark-input__field" name="example1" data-maxlength-soft="140" placeholder="A tweet or something." role="textbox"></textarea>
  <span class="spark-label">This has a variable-height text area with a soft remaining count.</span>
</label>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

To implement a soft character count, simply add the data-characters attribute to the .spark-input-container element. This will count up from 0. To implement a hard character count that counts down from the maximum number allowed, add the data-characters-remaining attribute to the .spark-input-container element and utilize the maxlength property on the corresponding input element.

Accessibility Notes

Text Inputs with Character Counts

Usage of the Text Input components with Character Counts require additional steps to make the character count fully accessible to assistive technologies. This is done through the use of ARIA Live Regions that provide additional context to users as they interact with the component. This feature is NOT included in the Spark Library as your product’s requirements, context or language might be different.

To see how the example below works, turn on your assistive technology such as JAWS or Apple VoiceOver and navigate to the text input and begin to type in characters into the field. As you do so, the assistive technology will read out the number indicated in the counter followed by the word “character” or “characters” depending on how much has been typed into the field.

0 characters 
<style>
#live-region-text {
  clip: rect(0 0 0 0);
  height: 1px;
  left: 0;
  overflow: hidden;
  position: absolute;
  top: 0;
  width: 100%;
}
</style>
<label id="aria-live-example" class="spark-input" data-characters>
  <input aria-describedby="live-region-text" class="spark-input__field" name="example1" placeholder="Please provide a detailed description of approximately 140 characters." role="textbox">
  <span class="spark-label">Description</span>
</label>

<span id="live-region-text" aria-live="polite">0 characters</span>
var ariaLiveEl = document.querySelector('#aria-live-example');
if (ariaLiveEl) {
  var ariaLiveElInst = new Spark.TextInput(ariaLiveEl, {
    onChange: function(val, inst){
      if ( inst.el.attributes['data-characters'] ) {
        var chars = inst.el.attributes['data-characters'].value;
        var liveRegion = document.querySelector('#live-region-text');
        var liveRegionSuffix = (chars === '1' || chars === 1) ? 'character' : 'characters';
        liveRegion.innerHTML = chars + ' ' + liveRegionSuffix;
      }
    }
  });
}

The example above has an additional element with an id="live-region-text" that will be the live region that is read out by assistive technologies. This element is added right after the Text Input within the HTML markup and is accessible to assistive technologies but is visually hidden on the screen. Sample styling code is provided above to show one possible way of hiding the element from the screen without affecting the space around the text input.

The value of the id attribute of the live region is the same as the value of the aria-describedby attribute of the input element to indicate the connection between the two elements. An aria-live attribute is also set on the live region element with a value of polite so that the assistive technology reads out the text once a user has stopped interacting with the field. Javascript is then used to change the value that is read out by the assistive technologies each time a user types in a value using the onChange functionality provided by the Text Input component.

Text Inputs with Icons

When an actionable Icon is placed within a Text Input component, it should be able to receive focus particularly when a user is navigating via keyboard, have the appropriate :hover, :focus and :active states, and have an aria-label attribute set to allow assistive technologies to convey the purpose of the control to users.

If the icon is not actionable, it should have an aria-hidden attribute set as it is a presentational element and the CSS-generated content should not be announced to users.