# [v-image](https://vinayakkulkarni.github.io/v-image/) 📷

<!-- Badges -->

[![Pipeline](https://img.shields.io/github/actions/workflow/status/vinayakkulkarni/v-image/pipeline.yml?branch=main&logo=github-actions&label=pipeline)](https://github.com/vinayakkulkarni/v-image/actions/workflows/pipeline.yml)
[![Doctor](https://img.shields.io/badge/doctor-audited-2ea043?logo=vuedotjs&label=doctor)](https://github.com/geoql/doctor)
[![GitHub release](https://img.shields.io/github/v/release/vinayakkulkarni/v-image?sort=semver&logo=github&label=release)](https://github.com/vinayakkulkarni/v-image/releases)
[![npm](https://img.shields.io/npm/v/v-image?logo=npm&label=npm)](https://www.npmjs.com/package/v-image)
[![JSR](https://img.shields.io/jsr/v/@vinayakkulkarni/v-image?logo=jsr&label=jsr)](https://jsr.io/@vinayakkulkarni/v-image)
[![npm downloads](https://img.shields.io/npm/dm/v-image?logo=npm&label=downloads)](http://npm-stat.com/charts.html?package=v-image)
[![bundle size](https://img.shields.io/bundlephobia/minzip/v-image?label=size)](https://bundlephobia.com/package/v-image@latest)
[![types](https://img.shields.io/npm/types/v-image?logo=typescript&label=types)](https://github.com/vinayakkulkarni/v-image/blob/main/package.json)
[![License](https://img.shields.io/github/license/vinayakkulkarni/v-image?logo=github&label=license)](./LICENSE)

[![vite-plus](https://img.shields.io/github/package-json/dependency-version/vinayakkulkarni/v-image/dev/vite-plus?logo=vite&label=vite-plus)](https://github.com/voidzero-dev/vite-plus)
[![typescript](https://img.shields.io/github/package-json/dependency-version/vinayakkulkarni/v-image/dev/typescript?logo=TypeScript&label=typescript)](https://www.typescriptlang.org/)
[![pnpm](https://img.shields.io/github/package-json/packageManager/vinayakkulkarni/v-image?label=pnpm&logo=pnpm)](https://pnpm.io/)
[![node](https://img.shields.io/node/v/v-image?logo=node.js&label=node)](https://nodejs.org/)

<!-- End Badges -->

⚠️ Docs are for Vue 3, for Vue 2 docs, check [this tree](https://github.com/vinayakkulkarni/v-image/tree/v2.6.1#readme)

## Demo

[![Edit v-image](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/v-image?file=src/App.vue)

## Features

- 💪 Built with [TypeScript](https://www.typescriptlang.org/)
- 🌠 Built with [Vue 3](https://vuejs.org/)
- ⚡ Zero dependencies.

## Table of Contents

- [v-image 📷](#v-image-)
  - [Demo](#demo)
  - [Features](#features)
  - [Table of Contents](#table-of-contents)
    - [Installation](#installation)
    - [Build Setup](#build-setup)
    - [Usage](#usage)
    - [Example](#example)
    - [API](#api)
      - [Props](#props)
      - [Events](#events)
  - [Contributing](#contributing)
  - [Author](#author)

### Installation

```bash
pnpm add v-image
```

### Build Setup

```bash
# install dependencies
$ pnpm install

# package lib
$ pnpm run build
```

### Usage

Global component:

```js
// main.ts
import { VImage } from 'v-image';
import { createApp } from 'vue';

const app = createApp({});
app.component('VImage', VImage);
```

Or use locally

```js
// component.vue
<script lang="ts">
import { VImage } from 'v-image';

export default defineComponent({
  components: {
    VImage,
  },
})
</script>
```

For Nuxt 3, create a file in `plugins/v-image.ts`

```js
import { VImage } from 'v-image';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component('VImage', VImage);
});
```

then import the file in `nuxt.config.{j|t}s`:

```js
export default {
  // ...
  plugins: [
    // ...
    { src: '~/plugins/v-image', mode: 'client' },
    // ...
  ],
  // ...
};
```

### Example

```html
<template>
  <v-image
    wrapper="flex justify-center items-center content-center w-full h-full"
    :placeholder="placeholder"
    :form="form"
    :uploaded="uploaded"
    @image-loaded="onImageLoad"
    @image-removed="onImageRemove"
  />
</template>
```

```js
<script lang="ts">
  import { defineComponent, ref } from 'vue';
  import type { Ref } from 'vue';
  import { VImage } from 'v-image';

  export default defineComponent({
    components: { VImage },
    setup() {
      const image: Ref<null | string> = ref(null);
      const placeholder = ref({
        image: 'https://picsum.photos/1000/1000',
        alt: 'Placeholder Image',
        imgClass: 'block rounded object-contain min-h-0 w-72',
        btnClass:
          'cursor-pointer inline-flex items-center justify-center mt-4 rounded-md border border-transparent bg-indigo-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 w-72',
        wrapper: 'p-4 max-w-xs w-full border border-gray-400 border-dotted',
      });
      const form = ref({
        name: 'myImage',
        label: 'Select Image',
        accept: 'image/jpg',
      });
      const uploaded = ref({
        wrapper: 'p-4 max-w-xs w-full border border-gray-400 border-dotted',
        alt: 'User uploaded dope image',
        imgClass: 'block rounded object-contain min-h-0 w-72',
        btnClass:
          'cursor-pointer inline-flex items-center justify-center mt-4 rounded-md border border-transparent bg-indigo-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 w-72',
        removeBtnText: 'Remove image',
      });

      const onImageLoad = (img: string) => {
        image.value = img;
      };
      const onImageRemove = (deleted: boolean) => {
        if (deleted) {
          image.value = null;
        }
      };

      return {
        placeholder,
        form,
        uploaded,
        onImageLoad,
        onImageRemove,
      };
    },
  });
</script>
```

### API

#### Props

| Name                     | Type   | Required? | Default                         | Description                                        |
| ------------------------ | ------ | --------- | ------------------------------- | -------------------------------------------------- |
| `wrapper`                | String | No        | ''                              | The wrapper classes for the top level `<div>`      |
| `placeholder`            | Object | No        | -                               | The placeholder image & input related code         |
| `placeholder.wrapper`    | String | No        | ''                              | Any wrapper classes for the placeholder `<div>`    |
| `placeholder.image`      | String | No        | 'https://picsum.photos/200x200' | The placeholder image                              |
| `placeholder.alt`        | String | No        | 'Placeholder Image'             | The placeholder image alt attribute                |
| `placeholder.imgClass`   | String | No        | ''                              | Any placeholder image classes                      |
| `placeholder.btnClass`   | String | No        | ''                              | `Select Image` button classes                      |
| `form`                   | Object | No        | -                               | The placeholder input form                         |
| `form.name`              | String | No        | 'v-image'                       | Enable the label to interact with the `<input />`  |
| `form.label`             | String | No        | 'Select Image'                  | The label/button text                              |
| `form.accept`            | String | No        | 'image/\*'                      | Abilty to accept file types                        |
| `uploaded`               | Object | No        | -                               | The user uploaded image related `Object`           |
| `uploaded.wrapper`       | String | No        | ''                              | Any wrapper classes for the uploaded image `<div>` |
| `uploaded.alt`           | String | No        | 'Very Interesting Image'        | The actual uploaded image alt attribute            |
| `uploaded.imgClass`      | String | No        | ''                              | Uploaded image classes                             |
| `uploaded.btnClass`      | String | No        | ''                              | `Remove Image` button classes                      |
| `uploaded.removeBtnText` | String | No        | 'Remove Image'                  | `Remove Image` button text                         |

#### Events

| Name             | Returns | Description                        |
| ---------------- | ------- | ---------------------------------- |
| `@image-loaded`  | String  | Sends the image in `base64` format |
| `@image-removed` | Boolean | Emits `true` if image is removed   |

## Contributing

1. Fork it ([https://github.com/vinayakkulkarni/v-image/fork](https://github.com/vinayakkulkarni/v-image/fork))
2. Create your feature branch (`git checkout -b feat/new-feature`)
3. Commit your changes (`git commit -Sam 'feat: add feature'`)
4. Push to the branch (`git push origin feat/new-feature`)
5. Create a new [Pull Request](https://github.com/vinayakkulkarni/v-image/compare)

_Note_:

1. Please contribute using [GitHub Flow](https://web.archive.org/web/20191104103724/https://guides.github.com/introduction/flow/)
2. Commits & PRs will be allowed only if the commit messages & PR titles follow the [conventional commit standard](https://www.conventionalcommits.org/), _read more about it [here](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional#type-enum)_
3. PS. Ensure your commits are signed. _[Read why](https://withblue.ink/2020/05/17/how-and-why-to-sign-git-commits.html)_

## Author

**v-image** © [Vinayak](https://github.com/vinayakkulkarni), Released under the [MIT](./LICENSE) License.<br>
Authored and maintained by Vinayak Kulkarni with help from contributors ([list](https://github.com/vinayakkulkarni/v-image/contributors)).

> [vinayakkulkarni.dev](https://vinayakkulkarni.dev) · GitHub [@vinayakkulkarni](https://github.com/vinayakkulkarni) · Twitter [@\_vinayak_k](https://twitter.com/_vinayak_k)