@ryangjchandler/alpine-mask
v0.2.0
Published
A clean Cleave integration for Alpine.js.
Downloads
1,308
Readme
✨ Help support the maintenance of this package by sponsoring me.
Alpine Mask
This packages provide a custom x-mask directive and $mask magic variable, powered by Cleave.js.
This package only supports Alpine v3.x.
Installation
CDN
Include the following <script> tag in the <head> of your document, just before Alpine.
<script
src="https://cdn.jsdelivr.net/npm/@ryangjchandler/[email protected]/dist/cdn.min.js"
defer
></script>NPM
npm install @ryangjchandler/alpine-maskAdd the x-mask directive and $mask magic property to your project by registering the plugin with Alpine.
import Alpine from "alpinejs";
import Mask from "@ryangjchandler/alpine-mask";
Alpine.plugin(Mask);
window.Alpine = Alpine;
window.Alpine.start();Usage
To mask an input, add the x-mask directive to your element.
<input x-data x-mask="{ ...allMyCleaveOptionsHere }">By default, the x-mask directive will expect a configuration object. This gives you full control over the Cleave.js instance.
There's also a list of convenience modifiers below that configure Cleave.js for you with sensible defaults.
Credit Cards
<input x-mask.card>This will format your input as a credit card input. By default, it will separate each section of the card number into blocks separated by a space.
If you would like to support 19-digit PANs, you can add the .strict modifier to the directive.
<input x-mask.card.strict>Date
To format your input as a date, use the .date modifier.
<input x-mask.date>By default, Cleave will format your data in a d/m/Y pattern. If you wish to change this, provide a custom pattern inside of the directive expression.
<input x-mask.date="['Y', 'm', 'd']">The input will now be formatted as Y/m/d.
Time
To format your input as a time, use the .time modifier.
<input x-mask.time>By default, Cleave will format your time with the h:m:s pattern. If you wish to change this, provide a custom pattern inside of the directive expression.
<input x-mask.date="['h', 'm']">The input will now be formatted as h:m.
Numeral / Numeric
If you would like to format a number inside of your input, you can use the .numeral modifier.
To format your input as a date, use the .date modifier.
<input x-mask.date>By default, Cleave will format your data in a d/m/Y pattern. If you wish to change this, provide a custom pattern inside of the directive expression.
<input x-mask.numeral>By default, Cleave formats your number using a comma (,) as the thousands-separator and a full-stop (.) as the decimal-separator.
If you would to change the thousands delimiter, you can provide either .delimiter.dot or .delimiter.comma.
<input x-mask.numeral.delimiter.dot>The number 100,000 will now be formatted as 100.000.
If you would to provide a custom prefix (money fields, etc), you can use the .prefix modifier followed by your prefix of choice.
<input x-mask.numeral.prefix.£>This will prefix your input with £.
NOTE: HTML attributes are case-insensitive. If you would like to use a more complex prefix or configuration, I recommend using
x-maskwith a custom configuration object.
Blocks
If you would like to segment your input and format the data in blocks, you can use the .blocks modifier and provide a list of block lengths as the directive expression.
<input x-mask.blocks="[3, 4, 5]">This would input the following input 333444455555 as 333 4444 55555.
Two-way data binding
<div x-data="{ raw: 2000 }">
<input x-mask.numeral x-model="raw" >
</div>When this input is initialised, raw will be formatted and the value will be set on the input. Anytime the input is updated, the raw value will be synced back to the raw property.
All changes made to the raw property outside of Cleave.js (other functions, etc) will also sync back and be formatted.
Versioning
This projects follow the Semantic Versioning guidelines.
License
Copyright (c) 2021 Ryan Chandler and contributors
Licensed under the MIT license, see LICENSE.md for details.