✨ Help support the maintenance of this package by sponsoring me.
This packages provide a custom x-mask directive and $mask magic variable, powered by Cleave.js.
This package only supports Alpine v3.x.
Include the following <script> tag in the <head> of your document, just before Alpine.
<script
src="https://cdn.jsdelivr.net/npm/@ryangjchandler/alpine-mask@0.x.x/dist/cdn.min.js"
defer
></script>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();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.
<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>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.
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.
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.
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.
Since Cleave.js stores the formatted value on the input instead of the raw value, the use of x-model could potentially have unintended side-effects.
When you update the value in the input, the raw value will be stored in the data property but Cleave.js won't be able to format the value again since Alpine.js will be setting input.value too.
To work around this problem, this packages provide an x-mask:model directive that can be used to specify a property on your component, just like x-model.
<div x-data="{ raw: 2000 }">
<input x-mask.numeral x-mask: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.
NOTE:
x-mask:modelmust be placed after otherx-maskdirectives to ensure Cleave.js has been initialised on the element.x-mask:modelcurrently only works with shorthandx-maskdirectives.
This projects follow the Semantic Versioning guidelines.
Copyright (c) 2021 Ryan Chandler and contributors
Licensed under the MIT license, see LICENSE.md for details.