mirror of
https://github.com/tabler/tabler.git
synced 2026-10-12 21:27:06 +04:00
96 lines
3.6 KiB
Plaintext
96 lines
3.6 KiB
Plaintext
---
|
|
title: Input mask
|
|
order: 11
|
|
summary: An input mask formats what the user types to a pattern, such as a phone number or a date, which makes the expected format clear and cuts validation errors.
|
|
description: Format user input automatically with input masks for dates, phone numbers, and other patterns to reduce validation errors.
|
|
docs-libs: [imask]
|
|
related: [/ui/forms/elements]
|
|
---
|
|
|
|
import Example from '@components/Example.astro'
|
|
import TabsPackage from '@components/TabsPackage.astro'
|
|
import CodeDocs from '@components/CodeDocs.astro';
|
|
|
|
## Installation
|
|
|
|
Install the imask library:
|
|
|
|
<TabsPackage name="imask" />
|
|
|
|
And import or require:
|
|
|
|
```javascript
|
|
import IMask from 'imask'
|
|
```
|
|
|
|
Or include it from a CDN:
|
|
|
|
```html
|
|
<script src="https://cdn.jsdelivr.net/npm/imask"></script>
|
|
```
|
|
|
|
The [IMask documentation](https://imask.js.org/guide.html#installation) covers other ways to install it.
|
|
|
|
## Default markup
|
|
|
|
Use an input mask where the value has a fixed format, such as a phone number, a date or a card number.
|
|
|
|
To create an input mask, add the `data-mask` attribute to the input element:
|
|
|
|
```html
|
|
<input
|
|
type="text"
|
|
name="input-mask"
|
|
class="form-control"
|
|
data-mask="(00) 0000-0000"
|
|
placeholder="(00) 0000-0000"
|
|
autocomplete="off"
|
|
/>
|
|
```
|
|
|
|
<Example column>
|
|
<label class="form-label">Telephone mask</label>
|
|
<label class="form-label" for="mask-phone">Phone number</label>
|
|
<input type="text" id="mask-phone" name="input-mask" class="form-control" data-mask="(00) 0000-0000" data-mask-visible="true" placeholder="(00) 0000-0000" autocomplete="off" />
|
|
</Example>
|
|
|
|
## More examples
|
|
|
|
If you need more examples of input masks, you can find them in the [IMask documentation](https://imask.js.org/guide.html#masked-input).
|
|
|
|
## JavaScript
|
|
|
|
Tabler wraps the plugin in an `InputMask` component that works like the Bootstrap components: it is created once per element and stored on it. On page load Tabler creates one for every element with `data-mask`. This is the code that runs:
|
|
|
|
<CodeDocs name="input-mask-init" file="core/js/src/input-mask.ts" />
|
|
|
|
Create the component yourself for a field added later. The pattern comes from `data-mask`, or from the config object, which wins:
|
|
|
|
```js
|
|
const phone = new tabler.InputMask(document.getElementById('phone'), { mask: '(00) 0000-0000' });
|
|
```
|
|
|
|
`data-mask-visible="true"` shows the pattern before the user types. In the config object that is `lazy: false`.
|
|
|
|
The `mask` getter returns the IMask instance, so everything from the [IMask API](https://imask.js.org/guide.html#api) is available:
|
|
|
|
```js
|
|
const phone = tabler.InputMask.getOrCreateInstance(document.getElementById('phone'));
|
|
console.log(phone.mask.unmaskedValue);
|
|
```
|
|
|
|
| Method | Description |
|
|
| --- | --- |
|
|
| `update()` | Re-applies the mask after the value was changed from code. |
|
|
| `mask` | Getter. The IMask instance, or `null` when the library is not loaded. |
|
|
| `dispose()` | Removes the mask and the component from the element. |
|
|
| `getInstance(element)` | Static. Returns the component for the element, or `null`. |
|
|
| `getOrCreateInstance(element, config)` | Static. Returns the component for the element and creates it when needed. |
|
|
|
|
## Accessibility
|
|
|
|
- A mask changes what the field accepts as the user types, which is easy to lose track of without sight. Say the expected format in a hint tied to the field with `aria-describedby`.
|
|
- Keep a real `label`. The placeholder shows the pattern, and it disappears as soon as typing starts.
|
|
- Do not block paste. A masked field that rejects a pasted phone number is a dead end for anyone using a password manager or a switch device.
|
|
- Use the right `type` and `autocomplete`, so the browser can still fill the field and the phone keyboard matches.
|