mirrors/maska
2
0
Fork 0
mirror of https://github.com/tenrok/maska.git synced 2026-06-14 18:42:27 +03:00
Code Activity

docs: updated docs for v3

Browse Source
This commit is contained in:
Alexander Shabunevich
2024-05-28 22:24:39 +03:00
parent 7921676276
commit c659a3d585
28 changed files with 1107 additions and 884 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/v3/README.md
+23
View File
@@ -0,0 +1,23 @@
<object data="../maska.svg" type="image/svg+xml" style="max-width: 90%"></object>
---
**Maska** is a simple zero-dependency input mask library.
You can use it with vanilla javascript or with your favorite framework. Out of the box there is integration with Vue 2/3, Svelte and Alpine.js, but you can integrate it into any framework.
> ❤️ [Please support](https://boosty.to/beholdr) Maska future development!
## Main components
- `Mask` — class for mask processing (can be used to mask any string)
- `MaskInput` — handles interaction with the `<input>` element
- Directives `vMaska` for Vue, `xMaska` for Alpine.js and `maska` action for Svelte
## Live Demo
<iframe height="300" style="width: 100%;" scrolling="no" title="Maska demo" src="https://codepen.io/beholdr/embed/QWREEMY?default-tab=html%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
See the Pen <a href="https://codepen.io/beholdr/pen/QWREEMY">
Maska demo</a> by Alexander (<a href="https://codepen.io/beholdr">@beholdr</a>)
on <a href="https://codepen.io">CodePen</a>.
</iframe>
docs/v3/_sidebar.md
+12
View File
@@ -0,0 +1,12 @@
- [Introduction](/)
- [Upgrade from v2](/upgrade)
- Usage
- [Vanilla](/vanilla)
- [Vue](/vue)
- [Alpine](/alpine)
- [Svelte](/svelte)
- Details
- [Options](/options)
- [Tokens](/tokens)
- [Hooks & Events](/hooks)
- [Known Issues](/issues)
docs/v3/alpine.md
+88
View File
@@ -0,0 +1,88 @@
# Usage with Alpine.js
## Installation
<!-- tabs:start -->
### **With NPM**
```sh
npm install @maskajs/alpine@3
```
And then register it:
```js
import Alpine from 'alpinejs'
import { xMaska } from '@maskajs/alpine'
Alpine.plugin(xMaska)
...
```
### **From CDN**
You can use Maska directly from CDN using simple script tag with `data-init` attribute, just make sure to include it BEFORE Alpine's core JS file:
```html
<!-- Maska Plugin -->
<script data-init src="https://cdn.jsdelivr.net/npm/@maskajs/alpine@3/dist/maska.umd.js"></script>
<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
```
This will automatically register Maska plugin inside Alpine.
<!-- tabs:end -->
## Directive signature
Maska provides custom Alpine.js directive for use with input:
```html
<input x-maska:argument.modifier="options">
```
- `argument` is a name of the bound variable (see example below)
- `modifier` modifier for bound variable value, could be one of:
- `masked` (default): variable will get a masked value (as in v-model)
- `unmasked`: variable will get an unmasked (raw) value
- `completed`: variable will be boolean, showing that mask is completed
- `options` is object with default options
## Minimal example
Apply `xMaska` directive to the input along with `data-maska` attribite:
```html
<input x-maska data-maska="#-#">
```
## Set mask options
To set default [options](/options) for the mask, pass options via **directive value**:
```html
<div x-data="{ options: { mask: '#-#', eager: true }}">
<input x-maska="options" data-maska-reversed>
</div>
```
You can override default options with `data-maska-` attributes on the input. In the example above we set **eager** mode using options and **reversed** mode using `data-maska-reversed` attribute.
## Bind value
To get masked value you can use standard `x-model` directive on the input. But if you want to access an unmasked (raw) value or get to know when mask is completed, you can use **directive argument** and (optionally) **directive modifier**:
```html
<div x-data="{ maskedvalue: '', unmaskedvalue: '' }">
<input x-maska:unmaskedvalue.unmasked data-maska="#-#" x-model="maskedvalue">
Masked value: <span x-text="maskedvalue"></span>
Unmasked value: <span x-text="unmaskedvalue"></span>
</div>
```
!> For correct work as directive argument, name of the bounded variable should be in **lower case**. So instead of `unmaskedValue` use `unmaskedvalue` or `unmasked_value`.
docs/v3/hooks.md
+116
View File
@@ -0,0 +1,116 @@
# Hooks & Events
## Hooks
Use hooks to transform masking value:
- `preProcess` hook is called before the mask processing
- `postProcess` hook is called after the mask processing, but before the input's value is set
For example, you can use it to check for a maximum length of a masked string:
```js
new MaskInput("input", {
postProcess: (value: string) => value.slice(0, 5)
})
```
## Events
You can subscribe to `maska` event that fires after each mask processing.
Event will contain `detail` property with a given structure:
<!-- tabs:start -->
### **Description**
- `masked`: masked value
- `unmasked`: unmasked value
- `completed`: flag that current mask is completed
### **Types**
```typescript
interface MaskaDetail {
masked: string
unmasked: string
completed: boolean
}
```
<!-- tabs:end -->
```js
const onMaska = (event: CustomEvent<MaskaDetail>) => {
console.log({
masked: event.detail.masked,
unmasked: event.detail.unmasked,
completed: event.detail.completed
})
}
```
<!-- tabs:start -->
## **Vanilla JS**
```js
document.querySelector("input").addEventListener("maska", onMaska)
```
## **Vue**
```vue
<input v-maska data-maska="#-#" @maska="onMaska" />
```
## **Alpine**
```html
<input x-maska data-maska="#-#" x-on:maska="onMaska" />
```
## **Svelte**
```svelte
<input use:maska data-maska="#-#" on:maska={onMaska} />
```
<!-- tabs:end -->
Alternatively, you can pass a callback function directly using the `onMaska` option:
<!-- tabs:start -->
### **Vanilla JS**
```js
new MaskInput("input", {
onMaska: (detail: MaskaDetail) => console.log(detail.completed)
})
```
### **Vue**
```vue
<script setup lang="ts">
const options = {
onMaska: (detail: MaskaDetail) => console.log(detail.completed)
}
</script>
<template>
<input v-maska="options">
</template>
```
### **Alpine**
```html
<div x-data="{ options: { onMaska: (detail) => console.log(detail.completed) }}">
<input x-maska="options">
</div>
```
### **Svelte**
```svelte
<script lang="ts">
const options = {
onMaska: (detail: MaskaDetail) => console.log(detail.completed)
}
</script>
<input use:maska={options}>
```
<!-- tabs:end -->
docs/v3/index.html
+81
View File
@@ -0,0 +1,81 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1.0, shrink-to-fit=no, viewport-fit=cover">
<title>maska v3 docs</title>
<link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 128 128%22><text y=%220.9em%22 font-size=%22120%22>*️⃣</text></svg>">
<!-- Themes (light + dark) -->
<link rel="stylesheet" media="(prefers-color-scheme: dark)" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">
<link rel="stylesheet" media="(prefers-color-scheme: light)" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-versioned-plugin@0.0.1/styles.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mingchyuanko/docsify-plugin-page-toc/dist/toc.css">
<style>
:root {
--theme-hue: 281;
--heading-h1-font-size: var(--modular-scale-3);
--heading-h2-font-size: var(--modular-scale-2);
--heading-h3-font-size: var(--modular-scale-1);
}
.sidebar > .app-name {
display: none;
}
.sidebar-nav > ul > li:has(ul) {
margin-top: 18px;
font-size: 0.8em;
text-transform: uppercase;
letter-spacing: 0.1ex;
font-weight: bold;
}
.sidebar-nav > ul > li > ul {
margin-left: 0;
margin-top: 6px;
font-size: 1rem;
text-transform: none;
letter-spacing: normal;
font-weight: normal;
}
@media screen and (max-width: 500px) {
.markdown-section {
padding-left: 16px;
padding-right: 16px;
}
}
</style>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'maska',
repo: 'beholdr/maska',
maxLevel: 2,
auto2top: true,
loadSidebar: true,
versionSelectorLabel: 'Version',
versions: [
{ folder: 'v3', label: 'v3', default: true },
{ folder: 'v2', label: 'v2', default: false }
]
}
</script>
<!-- Required -->
<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/js/docsify-themeable.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-versioned-plugin@0.0.1/index.js"></script>
<!-- Recommended -->
<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-tabs@1"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
<script src="https://cdn.jsdelivr.net/npm/@mingchyuanko/docsify-plugin-page-toc/dist/toc.min.js"></script>
</body>
</html>
docs/v3/issues.md
+22
View File
@@ -0,0 +1,22 @@
# Known issues
## Unsupported input types
Please use Maska only for inputs of the following types: `text`, `search`, `URL`, `tel` and `password`.
If you need a numeric keyboard, use `type="text"` with attribute `inputmode="numeric"`:
```html
<input type="text" inputmode="numeric">
```
## Vuetify and other UI frameworks
Some frameworks with custom components may not pass `data-` attributes to native input elements. In such cases, you will need to set the mask and other options using directive value:
```vue
<script setup>
const options = { mask: '#-#' }
</script>
<input v-maska="options">
```
docs/v3/options.md
+206
View File
@@ -0,0 +1,206 @@
# Options
There are two main components that you can customize: the `Mask` class and the `MaskInput` class. You typically work directly with the latter, but since `MaskInput` options extend `Mask` options, you can configure both using a single object.
## `Mask` options
To set options for a `Mask` class you can pass an object when creating the class:
```js
new Mask({ mask: "#-#", eager: true, number: { locale: 'de' }})
```
Options passed in this way will be used as default values and can be overridden by `data-maska-` attributes of a given input element.
<!-- tabs:start -->
### **Description**
<table>
<tr>
<th>Option / data-attribute</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td><code>mask</code><br><code>data-maska</code></td>
<td><code>—</code></td>
<td>Mask to apply (string, array of strings or function). If you pass an empty string or <code>null</code> it will disable a mask</td>
</tr>
<tr>
<td><code>tokens</code><br><code>data-maska-tokens</code></td>
<td><code>—</code></td>
<td>Custom tokens object. See tokens page</td>
</tr>
<tr>
<td><code>tokensReplace</code><br><code>data-maska-tokens-replace</code></td>
<td><code>false</code></td>
<td>If custom tokens should replace default tokens (if not set, they will merge)</td>
</tr>
<tr>
<td><code>eager</code><br><code>data-maska-eager</code></td>
<td><code>false</code></td>
<td>Eager mode will show static characters before you type them, e.g. when you type <code>1</code>, eager mask <code>#-#</code> will show <code>1-</code> and non-eager will show <code>1</code></td>
</tr>
<tr>
<td><code>reversed</code><br><code>data-maska-reversed</code></td>
<td><code>false</code></td>
<td>In reversed mode mask will grow backwards, e.g. for numbers</td>
</tr>
<tr>
<td><code>number.locale</code><br><code>data-maska-number-locale</code></td>
<td><code>en</code></td>
<td>Locale for number mode. Determine the national format for the number</td>
</tr>
<tr>
<td><code>number.fraction</code><br><code>data-maska-number-fraction</code></td>
<td><code>0</code></td>
<td>Fraction digits for the number (<code>0</code> allows only integer numbers)</td>
</tr>
<tr>
<td><code>number.unsigned</code><br><code>data-maska-number-unsigned</code></td>
<td><code>false</code></td>
<td>Unsigned mode for the number: if you want to accept only positive numbers</td>
</tr>
</table>
### **Types**
```typescript
interface MaskOptions {
mask?: MaskType
tokens?: MaskTokens
tokensReplace?: boolean
eager?: boolean
reversed?: boolean
number?: MaskNumber
}
type MaskType = string | string[] | ((input: string) => string) | null
interface MaskToken {
pattern: RegExp
multiple?: boolean
optional?: boolean
repeated?: boolean
transform?: (char: string) => string
}
type MaskTokens = Record<string, MaskToken>
interface MaskNumber {
locale?: string
fraction?: number
unsigned?: boolean
}
```
<!-- tabs:end -->
## `MaskInput` options
`MaskInput` options can only be set when creating a class, as they are too complex to use `data-maska-` attributes for them. Along with `MaskInput` options you can also pass any `Mask` class options (or set them using `data-maska-` attributes):
```js
new MaskInput("input", {
onMaska: (detail) => console.log(detail.completed)
mask: "#-#",
reversed: true,
})
```
<!-- tabs:start -->
### **Description**
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>onMaska</code></td>
<td>Сallback (event analog), called after every mask processing</td>
</tr>
<tr>
<td><code>preProcess</code></td>
<td>Hook called before mask processing</td>
</tr>
<tr>
<td><code>postProcess</code></td>
<td>Hook called after mask processing</td>
</tr>
</table>
### **Types**
```typescript
interface MaskInputOptions extends MaskOptions {
onMaska?: (detail: MaskaDetail) => void
preProcess?: (value: string) => string
postProcess?: (value: string) => string
}
interface MaskaDetail {
masked: string
unmasked: string
completed: boolean
}
```
<!-- tabs:end -->
?> Examples on this page use vanilla version of Maska. The framework specific versions have the same options, but should be passed in a different way: for example, as a directive value.
## Number mask
Number mode makes it easy to format numbers according to the selected locale.
You can enable the number mode using `number` option or `data-maska-number-` attributes.
In that case you don't need to set `mask` or any other options. All number options are optional:
<!-- tabs:start -->
### **By data-attributes**
```html
<!-- Minimal example -->
<input data-maska-number>
<!-- Full example -->
<input
data-maska-number-locale="ru"
data-maska-number-fraction="2"
data-maska-number-unsigned
>
```
### **By option**
```js
// minimal example
new MaskInput("input", {
number: {}
})
// full example
new MaskInput("input", {
number: {
locale: "ru",
fraction: 2,
unsigned: true
}
})
```
<!-- tabs:end -->
?> Under the hood Maska uses [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) for number formatting.
## Dynamic masks
Pass `mask` as **array** or **function** to make it dynamic:
- With **array** a suitable mask will be chosen by length (smallest first)
- With **function** you can select mask with custom logic using value
```js
new MaskInput("input", {
mask: (value: string) => value.startsWith('1') ? '#-#' : '##-##'
})
```
docs/v3/svelte.md
+61
View File
@@ -0,0 +1,61 @@
# Usage with Svelte
## Installation
You can install Maska with following command:
```sh
npm install @maskajs/svelte@3
```
And then use it in your `.svelte` component:
```svelte
import { maska } from '@maskajs/svelte'
<input use:maska data-maska="#-#" />
```
## Action signature
Maska provides simple Svelte action for use with input:
```html
<input use:maska={options}>
```
- `options` is object with default options
## Minimal example
Apply `maska` action to the input along with `data-maska` attribite:
```svelte
<script>
import { maska } from '@maskajs/svelte'
</script>
<input use:maska data-maska="#-#">
```
## Set mask options
To set default [options](/options) for the mask, pass options via **directive value**:
```svelte
<script>
import { maska } from '@maskajs/svelte'
const options = {
mask: "#-#",
eager: true
}
</script>
<input use:maska={options} data-maska-reversed>
```
You can override default options with `data-maska-` attributes on the input. In the example above we set **eager** mode using options and **reversed** mode using `data-maska-reversed` attribute.
docs/v3/tokens.md
+91
View File
@@ -0,0 +1,91 @@
# Tokens
## Default tokens
There are 3 tokens defined by default:
```js
{
'#': { pattern: /[0-9]/ }, // digits
'@': { pattern: /[a-zA-Z]/ }, // letters
'*': { pattern: /[a-zA-Z0-9]/ }, // letters & digits
}
```
?> Use `!` before token to escape symbol. For example `!#` will render `#` instead of a digit.
## Custom tokens
Add custom tokens via `data-maska-tokens` attribute or by `tokens` option:
<!-- tabs:start -->
### **By data-attributes**
When using `data-maska-tokens`, there are two possible formats:
- **JSON form** should be a valid JSON-string (but can use both single and double quotes) with pattern in a string format without delimiters
- **Simple form** should be a string in format: `T:P:M|...` where:
- `T` is token
- `P` is pattern in string form
- `M` is optional modifier (see below)
- `|` is separator for multiple tokens
```html
<input data-maska="Z-Z" data-maska-tokens="{ 'Z': { 'pattern': '[A-Z]' }}">
<input data-maska="Z-Z" data-maska-tokens="Z:[A-Z]">
<input data-maska="Z-z" data-maska-tokens="Z:[A-Z]|z:[a-z]:multiple">
```
?> You can’t set the `transform` function for a token using `data-maska-tokens` attribute.
If you need to do this, you should use the `tokens` option instead.
### **By option**
```js
new MaskInput("[data-maska]", {
mask: "A-A",
tokens: {
A: { pattern: /[A-Z]/, transform: (chr: string) => chr.toUpperCase() }
}
})
```
!> When using `tokens` option, pattern should be a valid regular expression object.
<!-- tabs:end -->
## Token modifiers
Every token can have a modifier, for example:
```js
{
0: { pattern: /[0-9]/, optional: true },
9: { pattern: /[0-9]/, repeated: true },
}
```
- `optional` for optional token
- `multiple` for token that can match multiple characters till the next token starts
- `repeated` for token that should be repeated. This token will match only one character, but the token itself (or group of such tokens) can be repeated any number of times
| Modifier | Example usage | Mask | Tokens
| --- | --- | --- | ---
| `optional` | IP address | `#00.#00.#00.#00` | `0:[0-9]:optional`
| `multiple` | CARDHOLDER NAME | `A A` | `A:[A-Z]:multiple`
| `repeated` | Money (1 234,56) | `9 99#,##` <small>reversed</small> | `9:[0-9]:repeated`
## Transform tokens
For custom tokens you can define `transform` function, applied to a character before masking.
For example, transforming letters to uppercase on input:
```js
{
A: { pattern: /[A-Z]/, transform: (chr: string) => chr.toUpperCase() }
}
```
?> You can also use [hooks](/hooks) for transforming whole value before/after masking.
docs/v3/upgrade.md
+76
View File
@@ -0,0 +1,76 @@
# Upgrade from v2
## New package for Vue
Maska v2 was a universal package for both vanilla JS and Vue version. Maska v3 is separated to several different packages:
- package `maska` is for vanilla version
- package `@maskajs/vue` is for Vue version
If you used Maska with Vue you need to delete `maska` package and install `@maskajs/vue` package.
?> If you used Maska without a framework, just upgrade package to `maska@3` version.
## New directive format
### Bind value
To bind a masked value with Maska v2 you used the **directive value** with a bound variable as an object:
```vue
<script setup>
const boundObject = reactive({
masked: '',
unmasked: '',
completed: false
})
</script>
<template>
<input v-maska="boundObject">
</template>
```
With v3, you need to use a **directive argument** and (optionally) a **directive modifier**:
```vue
<script setup>
const boundobject = ref('')
</script>
<template>
<input v-maska:boundobject.unmasked>
</template>
```
### Mask options
To pass mask options with v2 you have used the **directive argument**:
```vue
<script setup>
const options = reactive({
mask: "#-#",
eager: true
})
</script>
<template>
<input v-maska:[options]>
</template>
```
With v3, you need to use for this a **directive value**:
```vue
<script setup>
const options = reactive({
mask: "#-#",
eager: true
})
</script>
<template>
<input v-maska="options">
</template>
```
docs/v3/vanilla.md
+116
View File
@@ -0,0 +1,116 @@
# Usage without a framework
## Installation
<!-- tabs:start -->
### **With NPM**
```sh
npm install maska@3
```
And then import it in your code:
```js
import { Mask, MaskInput } from 'maska'
new MaskInput("[data-maska]") // for masked input
const mask = new Mask({ mask: "#-#" }) // for programmatic use
```
### **From CDN / UMD**
You can use Maska directly from CDN with simple script tag. Library API will be exposed on the global `Maska` object:
```html
<script src="https://cdn.jsdelivr.net/npm/maska@3/dist/maska.umd.js"></script>
<script>
const { Mask, MaskInput } = Maska
new MaskInput("[data-maska]") // for masked input
const mask = new Mask({ mask: "#-#" }) // for programmatic use
</script>
```
### **From CDN / ES**
For modern browsers you can use ES modules build with (optional) [import maps](https://caniuse.com/import-maps):
```html
<script type="importmap">
{
"imports": {
"maska": "https://cdn.jsdelivr.net/npm/maska@3/dist/maska.mjs"
}
}
</script>
<script type="module">
import { Mask, MaskInput } from 'maska'
new MaskInput("[data-maska]") // for masked input
const mask = new Mask({ mask: "#-#" }) // for programmatic use
</script>
```
?> Notice that we are using `<script type="module">` in this case.
<!-- tabs:end -->
## Minimal example
Add to your input element `data-maska` attribute:
```html
<input data-maska="#-#">
```
Then import and initialize `MaskInput`, passing input element(s) or `querySelector` expression as first argument:
```js
import { MaskInput } from "maska"
// init with query selector
new MaskInput("[data-maska]")
// or with element
const input = document.querySelector('[data-maska]')
new MaskInput(input)
```
## Set mask options
Usually you set mask via `data-maska` attribute. But you can pass mask and other [options](/options) via second argument. It will be a default options that can be overriden by `data-maska-` attributes:
```js
new MaskInput(input, { mask: "#-#" })
```
## Programmatic use
You can use mask function programmatically by importing `Mask` class.
There are three methods available:
- `masked(value)` returns masked version of given value
- `unmasked(value)` returns unmasked version of given value
- `completed(value)` returns `true` if given value makes mask completed
```js
import { Mask } from "maska"
const mask = new Mask({ mask: "#-#" })
mask.masked("12") // = 1-2
mask.unmasked("12") // = 12
mask.completed("12") // = true
```
## Destroy mask
To destroy mask use `destroy()` method:
```js
const mask = new MaskInput(input)
mask.destroy()
```
docs/v3/vue.md
+252
View File
@@ -0,0 +1,252 @@
# Usage with Vue
## Installation
<!-- tabs:start -->
### **With NPM**
```sh
npm install @maskajs/vue@3
```
And then import it in your `.vue` component:
```js
import { vMaska } from '@maskajs/vue'
```
### **From CDN / UMD**
You can use Maska directly from CDN with simple script tag. Library API will be exposed on the global `Maska` object:
```html
<script src="https://cdn.jsdelivr.net/npm/@maskajs/vue@3/dist/maska.umd.js"></script>
<script>
const { vMaska } = Maska
Vue.createApp({ directives: { maska: vMaska }}).mount('#app')
</script>
```
### **From CDN / ES**
For modern browsers you can use ES modules build with (optional) [import maps](https://caniuse.com/import-maps):
```html
<script type="importmap">
{
"imports": {
"maska": "https://cdn.jsdelivr.net/npm/@maskajs/vue@3/dist/maska.mjs"
}
}
</script>
<script type="module">
import { vMaska } from 'maska'
Vue.createApp({ directives: { maska: vMaska }}).mount('#app')
</script>
```
?> Notice that we are using `<script type="module">` in this case.
<!-- tabs:end -->
## Directive signature
Maska provides custom Vue directive for use with input:
```html
<input v-maska:argument.modifier="options">
```
- `argument` is a name of the bound variable (see example below)
- `modifier` modifier for bound variable value, could be one of:
- `masked` (default): variable will get a masked value (as in v-model)
- `unmasked`: variable will get an unmasked (raw) value
- `completed`: variable will be boolean, showing that mask is completed
- `options` is object with default options
## Minimal example
Import `vMaska` directive and apply it to the input along with `data-maska` attribite:
<!-- tabs:start -->
### **Composition API**
```vue
<script setup>
import { vMaska } from "maska"
</script>
<template>
<input v-maska data-maska="#-#">
</template>
```
### **Options API**
```vue
<script>
import { vMaska } from "maska"
export default {
directives: { maska: vMaska }
}
</script>
<template>
<input v-maska data-maska="#-#">
</template>
```
<!-- tabs:end -->
## Set mask options
To set default [options](/options) for the mask, pass options via **directive value**:
<!-- tabs:start -->
### **Composition API**
```vue
<script setup>
import { reactive } from "vue"
import { vMaska } from "maska"
// could be plain object too
const options = reactive({
mask: "#-#",
eager: true
})
</script>
<template>
<input v-maska="options" data-maska-reversed>
</template>
```
### **Options API**
```vue
<script>
import { vMaska } from "maska"
export default {
directives: { maska: vMaska },
data: () => ({
options: {
mask: "#-#",
eager: true
}
})
}
</script>
<template>
<input v-maska="options" data-maska-reversed>
</template>
```
<!-- tabs:end -->
You can override default options with `data-maska-` attributes on the input. In the example above we set **eager** mode using options and **reversed** mode using `data-maska-reversed` attribute.
?> Sometimes using directive value is the only way to configure a mask, because you don't have access to the input element: for example, when using Maska with Vuetify.
## Bind value
To get masked value you can use standard `v-model` directive on the input. But if you want to access an unmasked (raw) value or get to know when mask is completed, you can use **directive argument** and (optionally) **directive modifier**:
<!-- tabs:start -->
### **Composition API**
```vue
<script setup>
import { ref } from "vue"
import { vMaska } from "maska"
const maskedvalue = ref('')
const unmaskedvalue = ref('')
</script>
<template>
<input v-maska:unmaskedvalue.unmasked data-maska="#-#" v-model="maskedvalue">
Masked value: {{ maskedvalue }}
Unmasked value: {{ unmaskedvalue }}
</template>
```
### **Options API**
```vue
<script>
import { vMaska } from "maska"
export default {
directives: { maska: vMaska },
data: () => ({
maskedvalue: "",
unmaskedvalue: ""
})
}
</script>
<template>
<input v-maska:unmaskedvalue.unmasked data-maska="#-#" v-model="maskedvalue">
Masked value: {{ maskedvalue }}
Unmasked value: {{ unmaskedvalue }}
</template>
```
<!-- tabs:end -->
!> For correct work as directive argument, name of the bounded variable should be in **lower case**. So instead of `unmaskedValue` use `unmaskedvalue` or `unmasked_value`.
## Usage with Nuxt
To use Maska in Nuxt 3 you can make a simple plugin. Create file `maska.ts` in `plugins` folder:
```js
import { vMaska } from "maska"
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.directive("maska", vMaska)
})
```
Now you can use v-maska directive in your app:
```html
<input v-model="value" v-maska data-maska="#-#" />
```
## Global registration of directive
<!-- tabs:start -->
### **Vue 3**
```js
import { createApp } from "vue"
import { vMaska } from "maska"
createApp({}).directive("maska", vMaska)
// or in case of CDN load
Vue.createApp({}).directive("maska", Maska.vMaska)
```
### **Vue 2**
```js
import Vue from "vue"
import { vMaska } from "maska"
Vue.directive("maska", vMaska)
// or in case of CDN load
Vue.directive("maska", Maska.vMaska)
```
<!-- tabs:end -->