Text Input

Text input fields allow users to enter or edit text.

Standard Text Input Example


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.

Variations

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.

Variations

Multi-line Input

Multi-line inputs should be used when the length of information being asked for is unpredictable (e.g. description, general notes etc.). A multi-line input should adopt the standard length of surrounding form fields and automatically vertically input once the user reaches the right side of the form.


Single Line Input with Icon Example

Processing and actionable icons (dropdown arrows, progress indicator, clear icon, etc.) appear on the right side of the form field. Refer to Icons for further application.


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.


Type Ahead Input Examples

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)

When Not 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)

Input Validation Examples

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.

Email Input Validation


Password Strength Indicator


Character Count Examples

Character Count Input


Hard Character Count Input


Variable Height Textarea w/ Soft Character Count Example

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 down from the max number of characters. The characters being typed are reflected in the remaining balance. Once the counter reaches 0, no more characters may be entered and the number turns red.

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

<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>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Developer Notes

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.

Multi-line Input

<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>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Developer Notes

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">
  <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 class="spark-icon-airplane spark-icon--md"></i></div>
</label>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Developer Notes

Icon content should 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>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Developer Notes

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

Disabled Input Example

<label class="spark-input">
  <input class="spark-input__field" name="example1" placeholder="Enter First Name..." disabled role="textbox">
  <span class="spark-label">Not to be touched.</span>
</label>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Developer Notes

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">
  <span class="spark-input__placeholder"></span>
  <span class="spark-label">What is your phone number?</span>
</label>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

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">
  <span class="spark-input__placeholder"></span>
  <span class="spark-label">What is your SSN?</span>
</label>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Developer Notes

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).

Note: typeahead functionality is currently disabled on Android devices due to a defect in how Chrome reports keyboard events on that platform. A solution is in active development.

Email Input Validation

<label class="spark-input" data-error>
  <input class="spark-input__field" type="email" name="example1" placeholder="you@address.com" value="sdf@.com" required role="textbox">
  <span class="spark-label">What is your email?</span>
  <span class="spark-input__message">Invalid email format.</span>
</label>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Password Strength Indicator

<label class="spark-input" id="validate-password">
  <input type="password" class="spark-input__field" name="example1" placeholder="What is your password?" role="textbox">
  <span class="spark-label">This has a password strength indicator.</span>
  <span class="spark-input__message"></span>
</label>
// 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.');
    }
  }
});

// jQuery
$('.spark-input[type="password"]').sparkTextInput({
  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.');
    }
  }
});

Developer Notes

Serveral validation provided in different levels. validate is the overview validation callback function for Spark Text Input with a default implementation. It can be configured and override by user in constructor: new Spark.TextInput(el, {validate: function() { }});.

onValidate is another validate callback function which only available when the default validate callback function is not overriden. onValidate should be used with validatePattern together. validatePattern should be a custom regular expression whose result will be used as second argument in onValidate callback function. The arguments of onValidate are the instance of Spark Text Input, result of regular expression and the current value of Text Input.

Validation also can be performed by hooking into the Spark.TextInput JavaScript class. When instantiating the class, provide an options object with a callback function set to the onChange key as the second argument. Ex. new Spark.TextInput(el, {onChange: function(input, val) { }});

The callback function will be passed two parameters: the instance of Spark.TextInput and the current value of the input. Using the clearMessages, setSuccess, setWarning or setError methods on the Spark.TextInput instance, you can manipulate which kind of error (if any) is shown. Only one state can be set at any time.

If you don’t wish to or cannot use the Spark.TextInput JavaScript class, adding data-error="true", data-warning="true" or data-success="true" to .spark-input will affect the color of the input. Setting the content of .spark-input__message will change the message displayed below the input.

Character Count Input

<label class="spark-input" data-characters>
  <input class="spark-input__field" name="example1" placeholder="Where you're from, your interests, etc." value="test" role="textbox">
  <span class="spark-label">Tell us about yourself</span>
</label>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Hard Character Count Input

<label class="spark-input" data-characters-remaining>
  <input class="spark-input__field" name="example1" maxlength="20" placeholder="A tweet or something." role="textbox">
  <span class="spark-label">This has a firm remaining count.</span>
</label>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

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>
// Vanilla JS
var el = document.querySelector('.spark-input');
var inputInstance = new Spark.TextInput(el);

// jQuery
$('.spark-input').sparkTextInput();

Developer Notes

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.