{"id":16515654,"url":"https://github.com/insin/inputmask-core","last_synced_at":"2025-04-12T21:23:14.099Z","repository":{"id":29080901,"uuid":"32609056","full_name":"insin/inputmask-core","owner":"insin","description":"Standalone input mask implementation, independent of any GUI","archived":false,"fork":false,"pushed_at":"2018-01-24T04:33:45.000Z","size":69,"stargazers_count":303,"open_issues_count":28,"forks_count":52,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-05-20T19:44:40.495Z","etag":null,"topics":["inputmask","javascript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/insin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-20T21:55:30.000Z","updated_at":"2024-04-17T15:58:41.000Z","dependencies_parsed_at":"2022-09-05T13:00:18.404Z","dependency_job_id":null,"html_url":"https://github.com/insin/inputmask-core","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insin%2Finputmask-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insin%2Finputmask-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insin%2Finputmask-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insin%2Finputmask-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/insin","download_url":"https://codeload.github.com/insin/inputmask-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248632645,"owners_count":21136735,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["inputmask","javascript"],"created_at":"2024-10-11T16:17:54.067Z","updated_at":"2025-04-12T21:23:14.066Z","avatar_url":"https://github.com/insin.png","language":"JavaScript","readme":"# inputmask-core [![Build Status](https://secure.travis-ci.org/insin/inputmask-core.png)](http://travis-ci.org/insin/inputmask-core)\n\nA standalone input mask implementation, which is independent of any GUI.\n\n`InputMask` encapsulates editing operations on a string which must conform to a fixed-width pattern defining editable positions and the types of characters they may contain, plus optional static characters which may not be edited.\n\n## Install\n\n```\nnpm install inputmask-core\n```\n\n## Usage\n\nImporting and creating an instance:\n\n```javascript\nvar InputMask = require('inputmask-core')\n\nvar mask = new InputMask({pattern: '11/11/1111'})\n```\n\nExamples of editing a mask:\n\n```javascript\n/*  Invalid input is rejected */\nmask.input('a')\n// → false\n\n/* Valid input is accepted */\nmask.input('1')\n// → true\nmask.getValue()\n// → '1_/__/____'\n\n/* Editing operations update the cursor position */\nmask.selection\n// → {start: 1, end: 1}\n\n/* Pasting is supported */\nmask.paste('2345678')\n// → true\nmask.getValue()\n// → '12/34/5678'\n\n/* Backspacing is supported */\nmask.backspace()\n// → true\nmask.getValue()\n// → '12/34/567_'\n\n/* Editing operations also know how to deal with selected ranges */\nmask.selection = {start: 0, end: 9}\nmask.backspace()\n// → true\nmask.getValue()\n// → '__/__/____'\n\n/* Undo is supported */\nmask.undo()\n// → true\nmask.getValue()\n// → '12/34/567_'\nmask.selection\n// → {start: 0, end: 9}\n\n/* Redo is supported */\nmask.redo()\nmask.getValue()\n// → '__/__/____'\nmask.selection\n// → {start: 0, end: 0}\n```\n\n## API\n\n## `InputMask(options: Object)`\n\nConstructs a new `InputMask` - use of `new` is optional, so these examples are equivalent:\n\n```javascript\nvar mask = new InputMask({pattern: '1111-1111', value: '1234-5678'})\n```\n```javascript\nvar mask = InputMask({pattern: '1111-1111', value: '1234-5678'})\n```\n\n## ``InputMask`` options\n\n### `pattern`\n\nA masking pattern must be provided and must contain at least one editable character, or an `Error` will be thrown.\n\nThe following format characters define editable parts of the mask:\n\n* `1` - number\n* `a` - letter\n* `A` - letter, forced to upper case when entered\n* `*` - alphanumeric\n* `#` - alphanumeric, forced to upper case when entered\n\nIf you need to include one of these characters as a static part of the mask, you can escape them with a preceding backslash:\n\n```javascript\nvar mask = new InputMask({pattern: '\\\\A11 \\\\1AA', value: 'A99 1ZZ'})\nmask.getValue()\n// → 'A99 1ZZ'\n```\n\nIf you need to include a static backslash in a pattern, you must escape it:\n\n```javascript\nvar mask = new InputMask({pattern: '\\\\\\\\A11\\\\\\\\', value: 'Z98'})\nmask.getValue()\n// → '\\\\Z98\\\\'\n```\n\nOtherwise, all other characters are treated as static parts of the pattern.\n\n#### Example patterns\n\n* Credit card number: `1111 1111 1111 1111`\n* Date: `11/11/1111`\n* ISO date: `1111-11-11`\n* Time: `11:11`\n* Canadian postal code: `A1A 1A1`\n* Norn Iron license plate: `AAA 1111`\n\n### `formatCharacters`\n\nAn object defining additional custom format characters to use in the mask's pattern.\n\nWhen defining a new format character, a `validate()` function is required and a `format()` function can optionally be defined to modify the validated character before adding it to the mask's value.\n\nFor example this is how you would define `w` as a new format character which accepts word character input (alphanumeric or underscore) and forces it to lower case when entered:\n\n```javascript\nvar mask = new InputMask({\n  pattern: 'Awwwww', // An uppercase letter followed by 5 word characters\n  formatCharacters: {\n    'w': {\n      validate: function(char) { return /\\w/.test(char) }\n      transform: function(char) { return char.toLowerCase() }\n    }\n  }\n})\n```\n\nTo override a built-in format character, pass its character as a property of this object along with the new definition.\n\nTo disable a built-in format character, pass its character as a property of this object with a `null` value:\n\n```javascript\nvar mask = new InputMask({\n  pattern: 'A1111', // Treats the 'A' as static\n  formatCharacters: {\n    'A': null\n  }\n})\n```\n\n### `placeholderChar` : `string`\n\nThe character which is used to fill in editable slots for which there is no input yet when getting the mask's current value.\n\nDefaults to `'_'`; must be a single character.\n\n```javascript\nvar mask = new InputMask({pattern: '11/11/1111', placeholderChar: ' '})\nmask.input('1')\n// → true\nmask.getValue()\n// → '1 /  /    '\n```\n\n### `value` : `string`\n\nAn optional initial value for the mask.\n\n### `selection` :  `{start: number; end: number}`\n\nAn optional default selection - defaults to `{start: 0, end: 0}`, placing the cursor before the first character.\n\n### `isRevealingMask` : `boolean`\n\nAn optional property that, if true, progressively shows the mask as input is entered. Defaults to `false`\n\nExample:\nGiven an input with a mask of `111-1111 x 111`, a value of `47`, and `isRevealingMask` set to `true`, then the input's value is formatted as `47`\nGiven the same input but with a value of `476`, then the input's value is formatted as `476-`\nGiven the same input but with a value of `47 3191`, then the input's value is formatted as `47_-3191 x `\n\n## `InputMask` editing methods\n\nEditing methods will not allow the string being edited to contain invalid values according to the mask's pattern.\n\nAny time an editing method results in either the `value` or the `selection` changing, it will return `true`.\n\nOtherwise, if an invalid (e.g. trying to input a letter where the pattern specifies a number) or meaningless (e.g. backspacing when the cursor is at the start of the string) editing operation is attempted, it will return `false`.\n\n### `input(character: string)` : `boolean`\n\nApplies a single character of input based on the current selection.\n\n* If a text selection has been made, editable characters within the selection will be blanked out, the cursor will be moved to the start of the selection and input will proceed as below.\n\n* If the cursor is positioned before an editable character and the input is valid, the input will be added. The cursor will then be advanced to the next editable character in the mask.\n\n* If the cursor is positioned before a static part of the mask, the cursor will be advanced to the next editable character.\n\nAfter input has been added, the cursor will be advanced to the next editable character position.\n\n### `backspace()` : `boolean`\n\nPerforms a backspace operation based on the current selection.\n\n* If a text selection has been made, editable characters within the selection will be blanked out and the cursor will be placed at the start of the selection.\n\n* If the cursor is positioned after an editable character, that character will be blanked out and the cursor will be placed before it.\n\n* If the cursor is positioned after a static part of the mask, the cursor will be placed before it.\n\n### `paste(input: string)`: `boolean`\n\nApplies a string of input based on the current selection.\n\nThis behaves the same as - and is effectively like - calling `input()` for each character in the given string *with one key difference* - if any character within the input is determined to be invalid, the entire paste operation fails and the mask's value and selection are unaffected.\n\nPasted input may optionally contain static parts of the mask's pattern.\n\n## `InputMask` history methods\n\nAn `InputMask` creates a new history snapshot each time you:\n\n* Perform a different type of editing operation to the previous editing operation.\n* Perform an editing operation with the cursor in a different position from where it was left after a previous editing operation.\n* Perform an editing operation with a text selection.\n\nHistory methods allow you to step backwards and forwards through these snapshots, updating `value` and `selection` accordingly.\n\nIf you perform an editing operation while stepping backwards through history snapshots, all snapshots after the current one will be disposed of.\n\nA history method returns `true` if a valid history operation was performed and `value` and `selection` have been updated.\n\nOtherwise, if an invalid history operation is attempted (e.g. trying to redo when you've already reached the point undoing started from) it will return `false`.\n\n### `undo()` : `boolean`\n\nSteps backwards through history snapshots.\n\n### `redo()` : `boolean`\n\nSteps forwards through history snapshots.\n\n## `InputMask` public properties, getters \u0026 setters\n\n### `emptyValue` : `string`\n\nThe value the mask will have when none of its editable data has been filled in.\n\n### `selection` : `{start: number; end: number}`\n\nThe current selection within the input represented as an object with `start` and `end` properties, where `end \u003e= start`.\n\nIf `start` and `end` are the same, this indicates the current cursor position in the string, otherwise it indicates a range of selected characters within the string.\n\n`selection` will be updated as necessary by editing methods, e.g. if you `input()` a valid character, `selection` will be updated to place the cursor after the newly-inserted character.\n\nIf you're using `InputMask` as the backend for an input mask in a GUI, make sure `selection` is accurate before calling any editing methods!\n\n### `setSelection(selection: {start: number; end: number})` : `boolean`\n\nSets the selection and performs an editable cursor range check if the selection change sets the cursor position (i.e. `start` and `end` are the same).\n\nIf the mask's pattern begins or ends with static characters, this method will prevent the cursor being placed prior to a leading static character or beyond a tailing static character. Only use this method to set `selection` if this is the behaviour you want.\n\nReturns `true` if the selection needed to be adjusted as described above, `false` otherwise.\n\n### `getValue()` : `string`\n\nGets the current value in the mask, which will always conform to the mask's pattern.\n\n### `getRawValue()` : `string`\n\nGets the current value in the mask without non-editable pattern characters.\n\nThis can be useful when changing the mask's pattern, to \"replay\" the user's input so far into the new pattern:\n\n```javascript\nvar mask = new InputMask({pattern: '1111 1111', value: '98781'})\nmask.getValue()\n// → '9878 1___'\nmask.getRawValue()\n// → '98781'\n\nmask.setPattern('111 111', {value: mask.getRawValue()})\nmask.getValue()\n// → '987 81_'\n```\n\n### `setValue(value: string)`\n\nOverwrites the current value in the mask.\n\nThe given value will be applied to the mask's pattern, with invalid - or missing - editable characters replaced with placeholders.\n\nThe value may optionally contain static parts of the mask's pattern.\n\n### `setPattern(pattern: string, options: ?Object)`\n\nSets the mask's pattern. The mask's value and selection will also be reset by default.\n\n#### `setPattern` options\n\n##### `value` : `string`\n\nA value to be applied to the new pattern - defaults to `''`.\n\n##### `selection` : `{start: number; end: number}`\n\nSelection after the new pattern is applied - defaults to `{start: 0, end: 0}`.\n\n## MIT Licensed\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsin%2Finputmask-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsin%2Finputmask-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsin%2Finputmask-core/lists"}