FieldKit: A Simple Library for Complex Input Formatting

Written by Joe Taylor and Brian Donovan.

To create the best user experience, we strive to build a beautiful and simple interface for our products. So when we set out to build a checkout flow for our online store, we wanted customers to have the same great experience they’d have on native apps when entering credit card and contact information. This would require a lot of work, but we knew we needed to banish the “no dashes or spaces” message often seen on websites. We did this with FieldKit.

FieldKit provides real-time, text field formatting as users type. It simplifies input formatting and creates a more polished experience for users, while outputting standardized data. Fortunately, this is now easy for anyone to implement, because we’ve open sourced FieldKit.

Take Control Of Your Text Fields

You can download the latest version of FieldKit and include the .js file. You can use also use npm to install FieldKit for use in your project’s npm-based build system.

$ npm install field-kit — save

By default, FieldKit provides FieldKit.TextField as a simple base class that wraps a text field without changing its behavior.

<input type="text" id="text-field-example" />

<script>
  var field = new FieldKit.TextField(document.getElementById('text-field-example'));
</script>

FieldKit also enables you to listen on some basic events over the lifetime of an input. Throughout the life of an input, there might be some actions taken on it, like textFieldDidBeginEditing or textDidChange. FieldKit notifies you when this happens.

<input type="text" id="text-field-example" maxlength=”20” />

<script>
  var field = new FieldKit.TextField(document.getElementById('text-field-example'));
  field.setDelegate({
    textFieldDidBeginEditing: function(field) {
      console.log(field.value());
    },
    textFieldDidEndEditing: function(field) {
      console.log(field.value());
    },
    textDidChange: function(field) {
      console.log(field.value());
    }
  });
</script>

FieldKit is most useful when it’s used with formatters. We have formatters for credit card numbers, expiry dates, phone numbers, localized currency, and Social Security numbers. FieldKit also provides the building blocks to create custom formatters.

<input type="text" id="social-security-number" />
<input type="text" id="text-field-example-2" />

<script>
  var ssnField = new FieldKit.TextField(
    document.getElementById('social-security-number'),
    new FieldKit.SocialSecurityNumberFormatter()
  );
</script>

With formatters, you can:

• Control the data that’s allowed to be entered into an input;
• Insert extra characters — that were not typed by the user — into the input to standardize the format;
• And, use custom formatting logic that changes based on the situation.

Alongside formatters, we have a few different field types that add additional functionality to specific use cases. For example we have a CardTextField. This field automatically uses the AdaptiveCardFormatter, exposes a Luhn Check method, and blurs the full card number to only show the last 4 digits.

<input type="text" id="card-number" placeholder="1234 5678 9012 3456">
<div id="card-type">Card type: <span id="card-type-span">unknown</span></div>


<script>
  var field = new FieldKit.CardTextField(document.getElementById('card-number'));
  field.setCardMaskStrategy(FieldKit.CardTextField.CardMaskStrategy.DoneEditing);
  field.setDelegate({
    textDidChange: function() {
      document.getElementById('card-type-span').innerHTML = (field.cardType() || 'unknown');
    }
  });
</script>

The other field we’re including is the expiry date field. For more information into any of these areas, please head over to the source code and wiki.

tl;dr

FieldKit is a tool that can be used to create a custom input experience for your application. Being able to customize the data input, including how it’s formatted and parsed, will allow for a safer and more consistent user experience.

FieldKit has been used for years at Square in just about every web project. Now, we’re excited to see where you take it. Please help us improve FieldKit and make web inputs a better place. Joe Taylor *Love Life :: Do What You Love :: Love What You Do ::*medium.com Brian Donovan - Profile *I build digital things for @Square, mostly web sites.*medium.com