npm package: @kodav.dev/svelte5-qrcode
Description: QR Code generator component for Svelte & SvelteKit with runes support
Author: Kodav
Latest version: 1.0.0

<div align="center">

# `@kodav.dev/svelte5-qrcode`

[![npm.badge]][npm] [![download.badge]][download] [![repl.badge]][repl] [![contribution.badge]][contribution]

QR Code generator for Svelte 5 & SvelteKit with runes support, with no dependencies
</div>

## Install

Use your package manager to install:

```bash
npm install @kodav.dev/svelte5-qrcode
```

## Quick Start

```svelte
<script>
  import { QRCode } from '@kodav.dev/svelte5-qrcode';
</script>

<QRCode data="Hello world!" />
```

![Alt text](https://github.com/kodav-dev/svelte5-qrcode/blob/main/readme/sample-hello-world.svg?sanitize=true)

## Features

- ✅ **Svelte 5 Compatible** - Full support for Svelte 5 and runes
- ✅ **No Dependencies** - Lightweight and fast
- ✅ **TypeScript Support** - Full type safety
- ✅ **Customizable** - Colors, shapes, sizes, logos
- ✅ **Download Support** - Export as SVG, PNG, JPG, WebP
- ✅ **Responsive** - Adapts to container size
- ✅ **Error Correction** - Multiple error correction levels
- ✅ **Logo Support** - Add custom logos to QR codes

## Migration from v1 to v2

Many new features have been added to version 2.0.0, and some properties have been renamed.

Here is a list of the changes:

| Old property name      | New property name      | Note                                                                 |
| ---------------------- | ---------------------- | -------------------------------------------------------------------- |
| `content`              | `data`                 |                                                                      |
| `errorCorrection`      | `errorCorrectionLevel` |                                                                      |
| `base64Image`          | `logoInBase64`         |                                                                      |
| `logoWidth`            | `logoSize`             | `logoSize` is applied to `logoWidth` and `logoHeight` (new property) |
| `dispatchDownloadLink` | `dispatchDownloadUrl`  |                                                                      |

| Old event name          | New event name         |
| ----------------------- | ---------------------- |
| `downloadLinkGenerated` | `downloadUrlGenerated` |

## Properties

### Data

The data encoded in the QR code typically consists of a URL to a website or a code used by applications, such as handling secrets in time-based one-time password (TOTP) applications.

This is the only property required to generate the QR code.

| Property name | Type     | Required |
| ------------- | -------- | -------- |
| `data`        | `string` | **Yes**  |

```svelte
<QRCode data="https://duxreserve.com" />
```

### QR Code type number

The QR code type number, an integer ranging from 1 to 40, determines the QR code's data capacity. The default value is `0`, which allows for automatic detection.

[More details](https://github.com/kodav-dev/svelte5-qrcode/blob/main/readme/qr-code-type-number.png)

| Property name | Type                              | Default value |
| ------------- | --------------------------------- | ------------- |
| `typeNumber`  | Integer `number` between 0 and 40 | `0`           |

**Note:** In most cases, setting this property is unnecessary. However, if you need to generate a QR code with a specific type number, you can set it as follows:

```svelte
<QRCode data="https://duxreserve.com" typeNumber={4} />
```

### Error correction level

QR Code has error correction capability to restore data if the code is dirty or damaged. Four error correction levels are available to choose according to the operating environment. Raising this level improves error correction capability but also increases the amount of data QR Code size and reduces the QR code's data capacity.

To select error correction level, various factors such as the operating environment and QR Code size need to be considered. Level `Q` or `H` may be selected for factory environment where QR Code get dirty, whereas Level `L` may be selected for a clean environment with the large amount of data. Typically, level `M` (15%) is most frequently selected.

- Level `L` Approx 7%
- Level `M` Approx 15% (default value)
- Level `Q` Approx 25%
- Level `H` Approx 30%

| Property name          | Type                       | Default value |
| ---------------------- | -------------------------- | ------------- |
| `errorCorrectionLevel` | `'L'`, `'M'`, `'Q'`, `'H'` | `'M'`         |

```svelte
<QRCode data="https://duxreserve.com" errorCorrectionLevel="L" />

<QRCode data="https://duxreserve.com" errorCorrectionLevel="M" />

<QRCode data="https://duxreserve.com" errorCorrectionLevel="Q" />
```

### Size

The size of the QR code can be controlled using the `size` property. The default value is `256`.

| Property name | Type     | Default value |
| ------------- | -------- | ------------- |
| `size`        | `number` | `256`         |

```svelte
<QRCode data="https://duxreserve.com" size={100} />

<QRCode data="https://duxreserve.com" size={200} />

<QRCode data="https://duxreserve.com" size={300} />
```

### Width and Height

You can set different width and height values for the QR code. However, this may affect the readability of the QR code.

| Property name | Type     | Default value |
| ------------- | -------- | ------------- |
| `width`       | `number` | `256`         |
| `height`      | `number` | `256`         |

```svelte
<QRCode data="https://duxreserve.com" width={100} />

<QRCode data="https://duxreserve.com" width={100} height={150} />

<QRCode data="https://duxreserve.com" width={150} height={150} />
```

### Padding

The padding around the QR code can be controlled using the `padding` property. The default value is `10`.

| Property name | Type     | Default value |
| ------------- | -------- | ------------- |
| `padding`     | `number` | `10`          |

```svelte
<QRCode data="https://duxreserve.com" padding={0} />

<QRCode data="https://duxreserve.com" padding={5} />

<QRCode data="https://duxreserve.com" padding={20} />
```

### Colors

You can customize the colors of the QR code using various color properties.

| Property name         | Type     | Default value |
| --------------------- | -------- | ------------- |
| `color`               | `string` | `#000000`     |
| `backgroundColor`     | `string` | `#ffffff`     |
| `modulesColor`        | `string` | `#000000`     |
| `anchorsOuterColor`   | `string` | `#000000`     |
| `anchorsInnerColor`   | `string` | `#000000`     |

```svelte
<QRCode data="https://duxreserve.com" color="#990000" />

<QRCode data="https://duxreserve.com" backgroundColor="#009900" color="#ffffff" />

<QRCode data="https://duxreserve.com" anchorsOuterColor="#00ff00" anchorsInnerColor="blue" />
```

### Shape

You can customize the shape of the QR code modules using the `shape` property.

| Property name | Type                    | Default value |
| ------------- | ----------------------- | ------------- |
| `shape`       | `'square'`, `'circle'`  | `'square'`    |

```svelte
<QRCode data="https://duxreserve.com" shape="square" />

<QRCode data="https://duxreserve.com" shape="circle" />
```

### Responsive

You can make the QR code responsive by setting the `isResponsive` property to `true`.

| Property name   | Type      | Default value |
| --------------- | --------- | ------------- |
| `isResponsive`  | `boolean` | `false`       |

```svelte
<div style="width: 30%; height: 30%;">
  <QRCode data="https://duxreserve.com" isResponsive />
</div>
```

### Join

You can join the QR code modules by setting the `isJoin` property to `true`.

| Property name | Type      | Default value |
| ------------- | --------- | ------------- |
| `isJoin`      | `boolean` | `false`       |

```svelte
<QRCode data="https://duxreserve.com" isJoin />
```

### Gapped Modules

You can add gaps between QR code modules by setting the `haveGappedModules` property to `true`.

| Property name      | Type      | Default value |
| ------------------ | --------- | ------------- |
| `haveGappedModules` | `boolean` | `false`       |

```svelte
<QRCode data="https://duxreserve.com" haveGappedModules />
```

### Background Rounded Edges

You can add rounded edges to the background by setting the `haveBackgroundRoundedEdges` property to `true`.

| Property name                | Type      | Default value |
| ---------------------------- | --------- | ------------- |
| `haveBackgroundRoundedEdges` | `boolean` | `false`       |

```svelte
<QRCode data="https://duxreserve.com" haveBackgroundRoundedEdges />
```

### Logo

You can add a logo to the QR code using various logo-related properties.

| Property name         | Type     | Default value |
| --------------------- | -------- | ------------- |
| `logoPath`            | `string` | `undefined`   |
| `logoInBase64`        | `string` | `undefined`   |
| `logoSize`            | `number` | `20`          |
| `logoWidth`           | `number` | `20`          |
| `logoHeight`          | `number` | `20`          |
| `logoPadding`         | `number` | `1`           |
| `logoBackgroundColor` | `string` | `#ffffff`     |
| `waitForLogo`         | `boolean` | `false`      |

```svelte
<!-- Local logo -->
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" />

<!-- External logo -->
<QRCode data="https://duxreserve.com" logoPath="https://upload.wikimedia.org/wikipedia/commons/a/a8/Lightning_bolt_simple.png" />

<!-- WaitForLogo -->
<QRCode data="https://duxreserve.com" logoPath="https://upload.wikimedia.org/wikipedia/commons/a/a8/Lightning_bolt_simple.png" waitForLogo />

<!-- logoInBase64 -->
<QRCode data="https://duxreserve.com" logoInBase64="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJjdXJyZW50Q29sb3IiIGQ9Im0xOC40OTYgMTAuNzA5bC04LjYzNiA4Ljg4Yy0uMjQuMjQ2LS42MzgtLjAzOS0uNDgyLS4zNDVsMy4wNzQtNi4wNjZhLjMuMyAwIDAgMC0uMjY4LS40MzZINS43MThhLjMuMyAwIDAgMS0uMjE0LS41MWw4LjAxLTguMTE1Yy4yMzItLjIzNS42MTguMDIzLjQ4OS4zMjhMMTEuNzA2IDkuODZhLjMuMyAwIDAgMCAuMjguNDE3bDYuMjkxLS4wNzhhLjMuMyAwIDAgMSAuMjIuNTA5Ii8+PC9zdmc+" />

<!-- logo background color -->
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoBackgroundColor="#ff0000" />

<!-- logo padding -->
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoPadding={2} />

<!-- logo size -->
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoSize={20} />

<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoWidth={20} logoHeigh={15} />
```

![Alt text](https://github.com/kodav-dev/svelte5-qrcode/blob/main/readme/sample-logo.svg?sanitize=true)

### Downloading the QR Code

You can download the QR code as a file (`'svg'` | `'png'` | `'jpg'` | `'jpeg'` | `'webp'`) by using an anchor tag that initiates the download. To enable this functionality, set the `dispatchDownloadUrl` property to `true` and listen for the `downloadUrlGenerated` event to retrieve the download URL. You can choose the file format by setting the `downloadUrlFileFormat` property to `'svg'` (default), `'png'`, `'jpg'`, `'jpeg'`, or `'webp'`.

Add the `download` attribute to the anchor tag to specify the filename for the downloaded file. The extension is optional in the file name; the file format will be determined by the `downloadUrlFileFormat` property.

Additionally, include the `target="_blank"` attribute in the anchor tag to open the download in a new tab.

**Note:** You cannot use the `downloadUrlFileFormat` other than `'svg'` in a non-browser environment.

| Property name           | Type                                          | Default value |
| ----------------------- | --------------------------------------------- | ------------- |
| `dispatchDownloadUrl`   | `boolean`                                     | `false`       |
| `downloadUrlFileFormat` | `'svg'`, `'png'`, `'jpg'`, `'jpeg'`, `'webp'` | `'svg'`       |

```svelte
<script>
  import { QRCode } from '@kodav.dev/svelte5-qrcode';

  let downloadUrl = '';

  const handleDownloadUrlGenerated = (url = '') => {
    downloadUrl = url;
  };
</script>

<div>
  <QRCode
    data="https://duxreserve.com"
    logoPath="/logo/lightning.svg"
    downloadUrlFileFormat="png"
    dispatchDownloadUrl
    on:downloadUrlGenerated={(event) => handleDownloadUrlGenerated(event.detail.url)}
  />
</div>


{#if downloadUrl}
  <a href={downloadUrl} download="QR-code-filename.png" target="_blank">Download QR Code</a>
{/if}
```

### Other events

You can listen for the following events:

- `qrCodeGenerated`: The QR Code is successfully generated
- `qrCodeRegeneratedWithLogo`: The QR Code is successfully regenerated with the logo
- `qrCodeGenerationFailed`: The QR Code generation failed. The error message can be retrieved via `event.detail`. Check the console for more information

```svelte
<QRCode
  data="https://duxreserve.com"
  on:qrCodeGenerated={handleQrCodeGenerated}
  on:qrCodeRegeneratedWithLogo={handleQrCodeRegeneratedWithLogo}
  on:qrCodeGenerationFailed={handleQrCodeGenerationFailed}
/>
```

### Time-based one-time passwords (TOTP)

Sample URL for a John Doe user on the Acme app:

```svelte
<QRCode data="otpauth://totp/ACME%20Co:john.doe@email.com?secret=HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30" />
```

![Alt text](https://github.com/kodav-dev/svelte5-qrcode/blob/main/readme/sample-totp.svg?sanitize=true)

## Development

This project is a fork of the original `@castlenine/svelte-qrcode` library, updated to support Svelte 5 and runes.

### Building

```bash
npm run build
```

### Development server

```bash
npm run dev
```

### Type checking

```bash
npm run check
```

## License

MIT License - see the [LICENSE](LICENSE) file for details.

[npm]: https://www.npmjs.com/package/@kodav.dev/svelte5-qrcode
[npm.badge]: https://img.shields.io/npm/v/@kodav.dev/svelte5-qrcode
[download]: https://www.npmjs.com/package/@kodav.dev/svelte5-qrcode
[download.badge]: https://img.shields.io/npm/d18m/@kodav.dev/svelte5-qrcode
[repl]: https://svelte.dev/repl/3e0c8ebeb0c74d7098a1e939800456c2?version=4.2.15
[repl.badge]: https://img.shields.io/static/v1?label=&message=Svelte+REPL&logo=svelte&logoColor=fff&color=ff3e00
[contribution]: https://github.com/kodav-dev/svelte5-qrcode
[contribution.badge]: https://img.shields.io/badge/contributions-welcome-green