Configuring UITextField using UITextContentType and UITextInputTraits
It can be easy to forget what a truly incredible and powerful class UITextField is, and what it gives you (more or less) for free. It handles input in a variety of languages (possibly including multiple at once!), dictation, bi-directional text, spell checking, auto-correcting, smart-quoting-and-dashing, and more, so that you don't really have to think about what's really going on behind the scenes too much.
Handling text input is a constant battle between flexibility, quick entry, validation, formatting. One of the many tools Apple has helpfully provided to make this a little better is
UITextContentType -- a simple concept that we can use to help create more consistency in our apps for how text input is handled. By using
UITextContentType and a few other related options, developers can greatly improve the user experience of working with text fields in their apps.
UITextContentType - What does the text entered represent?
In iOS 10, Apple introduced the concept of the "text content type" -- or to take it straight from the documentation:
Constants that identify the semantic meaning expected for a text-entry area.
This enabled the system to gain a better understanding of what text was being entered, and provide the user with better suggestions for auto-completing text. Most recently this has been extended in iOS 12 to help support generated password and 2-Factor "one-time code" auto-fills. You can read more about how to implement those in a number of other blog posts, but for now we'll focus primarily on the "basic" autocomplete functionality, which you've probably encountered at some point already.
When should I set a text content type on a text field?
You should be setting a relevant value on a text field anywhere the system may be able to help provide a relevant value on behalf of the user. This will save your users time, and help them move through your forms faster. As an added bonus, you'll likely see lower rates of people making mistakes along the lines of off-by-one-letter email domains and similar.
What does a text content type do for you?
It just helps the system provide smart suggestions for automatically filling out a form, and may help the system choose a keyboard style that matches the content type. I would suggest that you don't solely rely on this, and instead ensure that you are testing each field and ensuring behavior is what the user will get the most help from. In my personal testing, I found that almost none of the various semantic types offered a "better" keyboard than the default, with the lone exception being the "credit card" type, which did use the ascii capable number pad.
What doesn't a text content type do for you?
It doesn't validate or format, and it doesn't prevent users from entering erroneous data in to your field. Users may have external keyboards, use copy-and-paste, or find any number of strange ways you might not expect to put data in to text fields. Never assume that restricting the keyboard "type" will prevent bad input.
What are the text content types?
Below are all of the various text content types, grouped in to their more general semantic roles.
Click on any of the titles below to expand and see the related types.
Person Names and Name Parts
- Name Prefix
- Given Name
- Middle Name
- Family Name
- Name Suffix
Job / Work Information
- Job Title
- Organization Name
- Phone Number
Credentials / Login Information
- New Password
- One Time Code
Location / Address
- Full Street Address
- Street Address Line 1
- Street Address Line 2
- City and State
- Country Name
- Postal Code
URL and Credit Card Number
- Credit Card Number
What else should I consider to help users enter text faster and better?
UITextContentType is a part of a protocol called
UITextInputTraits which allows developers to describe the expected "support" provided from the system, such as:
- Automatic capitalization, spell checking, smart-quotes, smart-dashes and smart-spaces (when pasting text)
- What kind of software keyboard and return key should be shown, including a light or dark keyboard
- If the "return" key should automatically be enabled/disabled based on the field having content
- If the field is a "secure" text entry (where the contents are replaced by •s)
- The password rules for a password entry field, if autofill is requested
In many cases, the setting the semantic meaning (through the text content type) of the text field /should/ be enough to help the system provide a sensible set of defaults for a text field. However, you may also want to consider enabling or disabling other features as makes sense for your input fields.
Let's take a quick look at each of these in more detail:
Autocapitalization Type (UITextAutocapitalizationType)
Should this text field attempt to automatically capitalize words, and if so, how? Note that some keyboards don't support this feature, namely:
The default value for this property is
There are 4 types of automatic capitalization:
- None: Don't attempt to capitalize anything for the user. This is useful when requesting items that are commonly non-capitalized, such as email addresses, or any place where text might be "stylized" by a user.
- Words: Attempt to capitalize each new word. This is useful when requesting things like a first/last or full name, an address or a title.
- Sentences: Attempt to capitalize new sentences, which is the common case (in English) for writing long-form text
- All: SCREAMING FULL CAPS INPUT! Useful for working with mainframes, and dealing with US states, and other all-caps abbreviations.
Autocorrection Type (UITextAutocorrectionType)
Should this text field attempt to correct mistakes on behalf of the user. You might want to provide correction for a user's "Biography", but might annoy your user if attempting to auto-correct their website URL, name, or email.
The default value is Default, which means enabled as long as their is support for the current script system.
There are 3 values:
- Default: Generally this is the same as enabled, however some script systems don't support auto-correct.
- On: Enable autocorrection if available.
- Off: Disable autocorrection.
Spell Checking Type (UITextSpellCheckingType)
Should this text field attempt to correct spelling for the user? Similar to auto-correction, but not quite the same. Spell checking will show red lines under misspelled words, and allow the user to tap on the word to correct it.
The default value is Default which will enable spell checking if autocorrection is enabled.
- Default: Enabled if auto-correct is also enabled.
- On: Enable spell-checking if available.
- Off: Disable spell-checking.
Smart Quotes, Smart Dashes and Smart Insert/Delete
These options are about character replacement. The enums for
UITextSmartInsertDelete are all essentially the same:
Smart quotes will (essentially) take the "straight" quote characters
'and turn them in to the fancier, curved companions:
‘quote’(This is sensitive to the region that the current user has set in their environment, and may behave differently depending on what their region is.)
Smart dashes will turn multiple dashes in to longer, single-character dashes. Two dashes becomes en-dash, and three dashes becomes em-dash. (there are many dashes...
emdash, as well as
bar, if that interests you, check out the wikipedia page: Dash - Wikipedia ). This trait is impacted by the keyboard type when set to
Smart insert/delete During cut, copy and paste events, the system may opt to add or remove spaces. This trait is impacted by the keyboard type when set to
Is this a "light" or "dark" keyboard, if available. Apple suggests using
.dark for alert level inputs, but not particularly clearly or strongly. The default is always
Enables Return Key Automatically
Does what it says, and (when set to true) disables the return key until the user has provided some kind of input. This does not prevent the user from using the return key on a hardware keyboard however, and is only a UI improvement for the software keyboard.
Secure Text Entry
Is the text input data worth hiding from others who might also see the screen? The most common case is for password fields, but other sensitive inputs might also be worth hiding by default as well.
What are the required password rules that must be followed -- this helps the system generate a password for the user that follows the requirements for your organization. See this tool from Apple for more details on formatting the rules.
Return Key Type
What should the "return" key look like and say. There are a number of these, but many have been "simplified" away (e.g. the
We've already looked at the
UITextContentType field, so the final item to dig in to is also the most complicated:
UIKeyboardType enumeration is a very simple interface for a very complicated concept -- what kind of software keyboard best supports the text input that this field expects. There are some important caveats here that are worth highlighting:
- Setting this value on your text field doesn't actually restrict the input that a user may attempt to enter, and should only be considered a supporting feature. For example, a "dollar amount" field might use a decimal pad input, but that doesn't mean that a hardware keyboard can't still type in text. Validating the final input is still important!
- There are "holes" in the available keyboard types, and it would be wise to consider testing all supported languages and devices for a given app to ensure that reasonable things are happening. A prominent, and often frustrating example: The iPad doesn't support any digit-only keyboards, and instead uses the "numbers and punctuation" keyboard for number, phone and decimal pad inputs. Another, more interesting example: A number pad input may allow the user to input other characters than 0-9 if their current device language uses a different numeral system. The
asciiCapableNumberPadhowever, does restrict input to only ASCII numbers (0-9)
- Using the
phonePadinputs will force the user to use the built-in keyboards, and disable any custom keyboards they have installed for that field. You can also disable /all/ custom keyboards (if you really must) by using the app delegate method:
So when and how should you use each type of keyboard? It's hard to say with absolutely certainty because every application is different — but we can at least look at the behavior of each keyboard and offer some general suggestions:
- Default - This is "Default for the current language" -- not some specific, unique default keyboard, so don't make assumptions about this one. Usually, this will be close to what a hardware keyboard might look like for the given language and locale.
- ASCII Capable - As close to a "Stock, default keyboard" as you can likely get -- this will be a keyboard that allows only ASCII characters, so no diacritics, no numbers aside from 0-9, and so on. Run
man asciion your local machine to see the ASCII code chart. This is useful if you are working with some specific value that must be ASCII only (e.g. older backends that don't support UTF-8, or perhaps a serial number that can only consist of ASCII A-Z and 0-9). Don't use this for things like names unless you absolutely must -- there's a great big world out there and users want to put in their real name, not some close approximation.
- Numbers and punctuation - This keyboard is just what it says: A keyboard that prominently features numbers and punctuation. It essentially flips to the punctuation page of the
- URL - Geared toward entering URLs, this keyboard surfaces
.comwhere the space bar would be (since you shouldn't really be entering un-encode spaces in a URL anyway). The symbols/punctuation page also features a more limited set of keys, geared toward what you typically find in a valid URL. Use this when you expect the user to enter a true, correctly formatted URL (for example, a link to your users web site)
- Web Search - A less-capable version of the URL keyboard, the goal here is to help with entering a URL or a search term (as you see in Safari, by default). Holding down on the period key will provide autocomplete for commend TLDs (.com, .net and others). Use this keyboard like Safari does, for places where the user may type either a search term or a URL.
- Email Address - Also does just what it says - enables easier email address input by featuring the @ and . keys, as well as providing the long press TLD options on period. Also provides a smaller selection of special characters, similar to the URL keyboard.
- Twitter - Twitter made the hashtag so hot, it got a special keyboard style that brings the pound/hash/octothorp character to the front, as well as the @ sign. Useful for social media contexts, where @ and # are used frequently.
What about Number Pad, Phone Pad, Name Phone Pad, Decimal Pad and ASCII Capable Number Pad?
Entering numbers in iOS is a strange affair, and can get pretty confusing if you're not well-versed in the broad range of numeric input types that iOS supports with software keyboards. However, it's not as bad as the sheer number of options might make it seem.
We can break down the common and edge cases to get a better sense of what each of these input types does, and what it provides.
- When you want to allow a user to potentially enter a name, or a phone number (for example, a login field where either is a valid user identity), the
Defaultkeyboard, that flips in to a phone pad style when the user presses the "123" key.
- When you want to allow a user to enter a phone number, with all the extras (pause and wait,
#) you use the
phonePadtype. This is geared toward entering a phone number as though an actual phone call were being placed. This might be useful if your app enables users to enter a meeting call-in number that might interact with a phone tree.
- When you want to allow a user to enter any digits based on their locale ( 0-9, ۰-۹, ०-९ and others), you use the
numberPad. This is helpful for locale-aware apps that properly handle numeric values beyond 0-9 -- as a simpler example, perhaps your app allows entering a "quantity" value that will be displayed as-is in a native environment.
- When you want to enable a user to enter decimal numbers, with locale support, use the
decimalPad-- but be aware that this uses the same range of local specific digits as the number pad, so your user may provide a number that looks like this:
- When you want to allow a user to enter only the numbers 0-9 and nothing else, you can use the
asciiCapableNumberPadto get the phone style pad, but with no option for symbols or otherwise, and even in languages with alternate numerals the numbers on the pad will be ASCII 0-9 -- be careful when localizing that this keyboard type may exclude values that the user expects in some cases!
Finally, remember that none of these will do what you expect on iPads, and instead will show a
numbersAndPunctuation type keyboard.
Thinking more about input
There are a number of other complicating factors for how text is entered, including custom keyboard the user may have installed, assistive-input devices that help people with disabilities to enter text, copy-and-paste from outside your app, dictation and of course hardware keyboard support.
It is well worth experimenting with alternative keyboards and locale settings in a simulator to see what kind of differences you get. I strongly suggest adding the Arabic keyboard (this will move your text input to be right-to-left, and enable non-ASCII numeric input) at the very least, and testing your app with it from time to time.
Even if you don't localize your app, users may still use these keyboards and it is essentially beyond your control. You can validate and reject input, but that's not really a great experience for your users.
You might also consider testing your app using a tool that provides "dirty" input such as the open source Naughty Keyboard from Romain Pouclet (@Palleas). Naughty, in this case means that the strings are oriented around being mischievous, nothing actually NSFW.
Reflecting on an overwhelming amount of options
No doubt, this is a lot to take in. Text input is a really complicated topic, and there's a lot of nuance in display, inputting, validating and managing text. Don't let it overwhelm you! The system defaults provide a lot of help, and over time many of these things become second nature.
What's important is to always take the time to test your inputs, ideally with multiple locale/language settings, and external keyboards at the very least. Remember not to depend on the user or the system to truly "restrict" the values in your text, and make sure to set a semantic content type for your text fields anywhere the system can help the user enter data faster. If we're being honest, your users probably won't tell you how much they love that they didn't have to type out their email address for the millionth time, but making their lives easier will make them happier (even if it's just a little bit).