https://github.com/evgenyifedotov/string-mask-jedi
๐ This package allows you to create dynamic masks for the input field with the ability to control the cursor position.
https://github.com/evgenyifedotov/string-mask-jedi
create-mask hook mask react react-hook string-mask
Last synced: 6 months ago
JSON representation
๐ This package allows you to create dynamic masks for the input field with the ability to control the cursor position.
- Host: GitHub
- URL: https://github.com/evgenyifedotov/string-mask-jedi
- Owner: EvgenyiFedotov
- License: mit
- Created: 2018-11-30T20:56:42.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-27T04:34:59.000Z (over 2 years ago)
- Last Synced: 2025-04-10T20:20:45.781Z (6 months ago)
- Topics: create-mask, hook, mask, react, react-hook, string-mask
- Language: TypeScript
- Homepage:
- Size: 2.86 MB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ๐ String-mask-jedi
[](https://www.npmjs.com/package/string-mask-jedi)
[](https://bundlephobia.com/result?p=string-mask-jedi)
[](https://evgenyifedotov.github.io/string-mask-jedi)
This package allows you to create dynamic masks for the input field with the ability to control the cursor position.
## Install
```sh
# npm
npm install string-mask-jedi
# yarn
yarn add string-mask-jedi
```
## Usage
### Create mask
```ts
import { createMask } from "string-mask-jedi";
const phoneMask = createMask("+0 (ddd) ddd-dd-dd", { d: /\d/ });
console.log(phoneMask.run("9998887766").value);
// +0 (999) 888-77-66
```
_[[createMask]](#createMask)_
### React hook
```tsx
import * as React from "react";
import { createMask } from "string-mask-jedi";
import { useMask } from "string-mask-jedi/react";
const phoneMask = createMask("+0 (ddd) ddd-dd-dd", { d: /\d/ });
const App: React.FC = () => {
const { value, onChange, ref } = useMask(phoneMask);
return ;
};
```
_[[createMask]](#createMask)_
_[[useMask]](#useMask)_
### React hook with use effector
```tsx
import * as React from "react";
import { createMask } from "string-mask-jedi";
import { useMask } from "string-mask-jedi/react";
import { createEvent, restore } from "effector";
import { useStore } from "effector-react";
const phoneMask = createMask("+0 (ddd) ddd-dd-dd", { d: /\d/ });
const updateValue = createEvent();
const $value = restore(updateValue, { value: "", cursor: 0 });
const App: React.FC = () => {
const rawValue = useStore($value);
const { value, onChange, ref } = useMask(phoneMask, () => [
rawValue,
updateValue,
]);
return ;
};
```
_[[createMask]](#createMask)_
_[[useMask]](#useMask)_
_[[UseStateHandler]](#UseStateHandler)_
## API
### `createMask`
```ts
/**
* @param stringMask - mask format
* @param translations - object with letters witch need translating
* @param options - object with added options for mask
*/
type CreateMask = (
stringMask: string,
translations?: Translations,
options?: Partial>,
) => Mask;
```
_[[Translations]](#translation)_
_[[Config]](#config)_
_[[Mask]](#mask)_
### `Token`
Object witch cached value letter when process value after mask running.
```ts
interface Token {
value: string;
additional: boolean;
}
```
### `State`
Object current state mask in processing value after mask running.
```ts
interface State {
remainder: string;
tokens: Token[];
cursor: number;
}
```
_[[Token]](#token)_
### `GetMatch`
Method fot get `RegExp` for each token.
```ts
type GetMatch = (state: State, index: number) => RegExp;
```
### `Mask`
Restult `createMask`.
```ts
interface Mask {
run: MaskRun;
config: Config;
}
```
_[[MaskRun]](#maskrun)_
_[[Config]](#config)_
### `MaskResult`
Result run mask.
```ts
interface MaskResult {
value: string;
cursor: number;
}
```
### `TokenConfig`
Token config for each letter in created mask.
```ts
interface TokenConfig {
getMatch: GetMatch;
defaultValue: string;
additional: boolean;
}
```
_[[GetMatch]](#getmatch)_
### `Config`
Config for create mask.
> Please note. `createMask` automatically created config by `stringMask`, `translations` and `options`.
```ts
interface Config {
tokens: TokenConfig[];
converters: Converter[];
}
```
_[[TokenConfig]](#tokenconfig)_
_[[Converter]](#converter)_
### `Converter`
Method for converting result after
```ts
type Converter = (tokens: Token[], configTokens: TokenConfig[]) => void;
```
_[[Token]](#token)_
_[[TokenConfig]](#tokenconfig)_
---
### `Translation`
```ts
type Translation = string | RegExp | GetMatch | TokenConfig | Mask;
```
_[[GetMatch]](#getmatch)_
_[[TokenConfig]](#tokenconfig)_
### `Translations`
```ts
interface Translations {
[key: string]: Translation | Translation[];
}
```
_[[Translation]](#translation)_
### `MaskRun`
```ts
type MaskRun = (value: string, cursor?: number) => MaskResult;
```
_[[MaskResult]](#maskresult)_
## API for React
### `useMask`
React hook for use mask.
```ts
type useMask = (
mask: Mask,
useState: UseStateHandler = React.useState,
) => UseStringMaskResult;
```
_[[Mask]](#mask)_
_[[UseStateHandler]](#UseStateHandler)_
_[[UseStringMaskResult]](#UseStringMaskResult)_
### `UseStateHandler`
ะกtate management handler
```ts
type UseStateHandler = (
initialState: MaskResult,
) => [MaskResult, (state: MaskResult) => any];
```
### `UseStringMaskResult`
Result react hook `useMask`.
```ts
interface UseStringMaskResult {
value: string;
onChange: (
event: React.ChangeEvent,
) => void;
ref: React.RefObject;
}
```
## Examples
See storybook with examples code.
- [Date](https://evgenyifedotov.github.io/string-mask-jedi/?path=/story/date--init)
- [Time](https://evgenyifedotov.github.io/string-mask-jedi/?path=/story/time--init)
- [Phone](https://evgenyifedotov.github.io/string-mask-jedi/?path=/story/phone--init)
## Tests
```sh
# npm
npm install
npm run test
# yarn
yarn install
yarn test
```