https://github.com/metonym/svelte-pincode
Declarative pincode component for Svelte
https://github.com/metonym/svelte-pincode
input lockbox pincode svelte svelte-component
Last synced: 6 months ago
JSON representation
Declarative pincode component for Svelte
- Host: GitHub
- URL: https://github.com/metonym/svelte-pincode
- Owner: metonym
- License: mit
- Created: 2021-01-01T22:51:57.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-13T02:34:52.000Z (over 1 year ago)
- Last Synced: 2025-04-28T11:15:52.032Z (6 months ago)
- Topics: input, lockbox, pincode, svelte, svelte-component
- Language: Svelte
- Homepage: https://metonym.github.io/svelte-pincode/
- Size: 215 KB
- Stars: 32
- Watchers: 2
- Forks: 10
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# svelte-pincode
[![NPM][npm]][npm-url]
> Declarative pin code component for Svelte.
A pin code is a short sequence of characters (usually numeric) used for verification. It differs from a password in that it is typically ephemeral and is not predetermined by the user.
Try it in the [Svelte REPL](https://svelte.dev/repl/2841eef46bfb49c4a848a2a063602e5d).
---
## Installation
```sh
# npm
npm i -D svelte-pincode
# pnpm
pnpm i -D svelte-pincode
# Bun
bun i -D svelte-pincode
# Yarn
yarn add -D svelte-pincode
```
## Usage
### Basic
Bind to either the `code` or `value` prop.
- **code** (`string[]`): Array of input values. An empty string represents an undefined value.
- **value** (`string`): `code` joined as a string.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
let code = [];
let value = '';
code: {JSON.stringify(code)}
value: {JSON.stringify(value)}
```
### Select text on focus
Set `selectTextOnFocus` to `true` for the input value text to be selected when focused.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
let input;
input.focus()}>
Focus input
```
### Numeric variant
By default, this component accepts alphanumeric values.
Set `type` to `"numeric"` to only allow numbers.
```svelte
```
### Initial values
Define intitial input values by using the `code` prop or `value` prop on `PincodeInput`.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
let pincode = ["1", "", "3"];
code: {JSON.stringify(pincode)}
```
### Validating upon completion
Actual validation is left to the consumer.
This example illustrates how you can validate the code once all inputs have a value by binding to the `complete` prop.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
const correctCode = "1234";
let inputValue = '';
let complete = false;
$: success = complete && inputValue === correctCode;
$: error = complete && !success;
{#if !complete}
Enter {correctCode.length - inputValue.length} more digit(s)...
{/if}
{#if success}Correct code{/if}
{#if error}Incorrect code{/if}
```
Use the dispatched "complete" event as an alternative to binding the `complete` prop.
```svelte no-eval
```
### Programmatic usage
`code` can be set programmatically.
In the following example, type some initial values and try setting or clearing the code.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
let passcode = [];
code: {JSON.stringify(passcode)}
passcode = ['1', '2', '3', '4']}>
Set code
passcode = ['', '', '', '']}>
Clear code
```
### Focusing the first input
To programmatically focus the first input, invoke the `focusFirstInput` method in a component reference.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
let ref;
Focus first input
```
### Focusing the next empty input
To focus the next input with no value, invoke the `focusNextEmptyInput` method.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
let pincodeRef;
Focus next empty input
```
### Focusing the last input
To focus the last input, invoke the `focusLastInput` method.
```svelte
import { Pincode, PincodeInput } from "svelte-pincode";
let passcodeRef;
Focus last input
```
## Styling
### Customization
This component is minimally styled; override the default styles by targeting the `data-pincode` selector:
```css
/** Pincode **/
:global([data-pincode]) {
display: inline-flex;
border: 1px solid #e0e0e0;
}
/** PincodeInput */
:global([data-pincode] input) {
width: 3rem;
padding: 0.5rem 1rem;
margin: 0;
border: 0;
border-radius: 0;
text-align: center;
}
:global([data-pincode] input:focus) {
z-index: 1;
}
:global([data-pincode] input:not(:last-of-type)) {
border-right: 1px solid #e0e0e0;
}
```
### Unstyled components
Use the unstyled components located in the `svelte-pincode/unstyled` folder if you prefer to style the components from scratch.
```html
import Pincode from "svelte-pincode/unstyled/Pincode.svelte";
import PincodeInput from "svelte-pincode/unstyled/PincodeInput.svelte";
```
## API
### Pincode
#### Props
| Name | Type | Default value |
| :---------------- | :------------------------------ | :--------------- |
| code | `string[]` | `[]` |
| value | `string` | `""` |
| type | `"alphanumeric"` or `"numeric"` | `"alphanumeric"` |
| selectTextOnFocus | `boolean` | `false` |
#### Accessors
- `focusFirstInput`
- `focusNextEmptyInput`
- `focusLastInput`
#### Dispatched Events
- **on:complete**: fired when all inputs have a value
- **on:clear**: fired when no inputs have a value
```svelte no-eval
```
### PincodeInput
#### Props
| Name | Type | Default value |
| :--- | :----------------- | :------------------------------------- |
| id | `string` | `"input" + Math.random().toString(36)` |
| ref | `HTMLInputElement` | `null` |
#### Forwarded Events
- on:focus
- on:blur
- on:keydown
## Changelog
[CHANGELOG.md](CHANGELOG.md)
## License
[MIT](LICENSE)
[npm]: https://img.shields.io/npm/v/svelte-pincode.svg?style=for-the-badge&color=%23ff3e00
[npm-url]: https://npmjs.com/package/svelte-pincode