{"id":13937907,"url":"https://github.com/johndatserakis/file-upload-with-preview","last_synced_at":"2025-05-15T18:03:13.618Z","repository":{"id":41893544,"uuid":"105165415","full_name":"johndatserakis/file-upload-with-preview","owner":"johndatserakis","description":"🖼 Simple file-upload utility that shows a preview of the uploaded image. Written in TypeScript. No dependencies. Works well with or without a framework.","archived":false,"fork":false,"pushed_at":"2024-09-02T20:38:34.000Z","size":5153,"stargazers_count":488,"open_issues_count":3,"forks_count":100,"subscribers_count":12,"default_branch":"develop","last_synced_at":"2025-04-04T10:27:09.246Z","etag":null,"topics":["file","image","input","javascript","preview","typescript","upload"],"latest_commit_sha":null,"homepage":"https://johndatserakis.github.io/file-upload-with-preview","language":"TypeScript","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/johndatserakis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-28T15:26:05.000Z","updated_at":"2025-04-01T12:26:55.000Z","dependencies_parsed_at":"2024-06-18T21:17:18.796Z","dependency_job_id":"fbb3fb1b-89bc-4884-b3eb-5d2b93c50e9c","html_url":"https://github.com/johndatserakis/file-upload-with-preview","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johndatserakis%2Ffile-upload-with-preview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johndatserakis%2Ffile-upload-with-preview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johndatserakis%2Ffile-upload-with-preview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johndatserakis%2Ffile-upload-with-preview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johndatserakis","download_url":"https://codeload.github.com/johndatserakis/file-upload-with-preview/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248489191,"owners_count":21112524,"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":["file","image","input","javascript","preview","typescript","upload"],"created_at":"2024-08-07T23:04:03.947Z","updated_at":"2025-04-11T22:28:58.578Z","avatar_url":"https://github.com/johndatserakis.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003ca href=\"\" target=\"_blank\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/johndatserakis/file-upload-with-preview/master/public/file-upload-with-preview.jpg\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n# file-upload-with-preview\n\n🖼 Simple file-upload utility that shows a preview of the uploaded image. Written in TypeScript. No dependencies. Works well with or without a framework.\n\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/file-upload-with-preview\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/file-upload-with-preview.svg\" alt=\"NPM Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/file-upload-with-preview\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/file-upload-with-preview.svg\" alt=\"NPM Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"http://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://twitter.com/intent/tweet?url=https%3A%2F%2Fgithub.com%johndatserakis%2Ffile-upload-with-preview\u0026text=Check%20out%20file-upload-with-preview%20on%20GitHub\u0026via=johndatserakis\"\u003e\n  \u003cimg src=\"https://img.shields.io/twitter/url/https/github.com/johndatserakis/file-upload-with-preview.svg?style=social\" alt=\"Tweet\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Links\n\n- [Demo](https://johndatserakis.github.io/file-upload-with-preview)\n- [npm](https://www.npmjs.com/package/file-upload-with-preview)\n- [GitHub](https://github.com/johndatserakis/file-upload-with-preview#readme)\n- [CodeSandbox - TypeScript](https://codesandbox.io/s/file-upload-with-preview-4ypil8?file=/src/index.ts)\n- [CodeSandbox - Browser](https://codesandbox.io/s/file-upload-with-preview-browser-446nc8?file=/src/index.js)\n- [Docs](https://johndatserakis.github.io/file-upload-with-preview/typedoc/)\n\n## Install\n\n```bash\nyarn add file-upload-with-preview\n```\n\nOr, you can include it through the browser.\n\n```html\n\u003clink\n  rel=\"stylesheet\"\n  type=\"text/css\"\n  href=\"https://unpkg.com/file-upload-with-preview/dist/style.css\"\n/\u003e\n\n\u003cscript src=\"https://unpkg.com/file-upload-with-preview/dist/index.js\"\u003e\u003c/script\u003e\n```\n\n## About\n\nThis is a simple frontend utility meant to help the file-upload process on your website.\n\nIt is written in pure JavaScript using TypeScript and has no dependencies. You can check out the live demo [here](https://johndatserakis.github.io/file-upload-with-preview).\n\nFor the most part, browsers do a good job of handling image-uploads. That being said - I find the ability to show our users a preview of their upload can go a long way in increasing the confidence in their upload.\n\n`file-upload-with-preview` aims to address the issue of showing a preview of a user's uploaded image in a simple to use package.\n\n## Features\n\n- Shows the actual image preview in the case of a single uploaded .jpg, .jpeg, .gif, or .png image. Shows a _success-image_ in the case of an uploaded .pdf file, uploaded video, or other un-renderable file - so the user knows their image was collected successfully. In the case of multiple selected files, the user's selected images will be shown in a grid.\n- Shows the image name in the input bar. Shows the count of selected images in the case of multiple selections within the same input.\n- Allows the user to clear their upload and clear individual images in the `multiple` grid\n- Looks great\n- Framework agnostic - to access the uploaded file/files just use the `cachedFileArray` (always will be an array) property of your `FileUploadWithPreview` object.\n- For every file-group you want just initialize another `FileUploadWithPreview` object with its own `uniqueId` - this way you can have multiple file-uploads on the same page. You also can just use a single input designated with a `multiple` property to allow multiple files on the same input.\n\n## Usage\n\nThis library looks for a specific HTML element to display the file-upload. Simply add the below `div` to your HTML. Make sure to populate your unique id in the `data-upload-id` attribute.\n\n```html\n\u003cdiv class=\"custom-file-container\" data-upload-id=\"my-unique-id\"\u003e\u003c/div\u003e\n```\n\nThen, initialize your file-upload in the JavaScript like below:\n\n```javascript\nimport { FileUploadWithPreview } from 'file-upload-with-preview';\nimport 'file-upload-with-preview/dist/style.css';\n\nconst upload = new FileUploadWithPreview('my-unique-id');\n```\n\nUsage with Next.js / Tailwind :\n\n```typescript\n'use client';\nimport { useEffect } from 'react';\nimport { FileUploadWithPreview } from 'file-upload-with-preview';\nimport 'file-upload-with-preview/dist/style.css';\n\nexport default function Uploader() {\n  useEffect(() =\u003e {\n    const upload = new FileUploadWithPreview('my-unique-id');\n  }, []);\n\n  return \u003cdiv className=\"custom-file-container\" data-upload-id=\"my-unique-id\"\u003e\u003c/div\u003e;\n}\n```\n\nIf you're importing directly in the browser, use the following instead:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\" /\u003e\n    \u003clink\n      rel=\"stylesheet\"\n      type=\"text/css\"\n      href=\"https://unpkg.com/file-upload-with-preview/dist/style.css\"\n    /\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv class=\"custom-file-container\" data-upload-id=\"my-unique-id\"\u003e\u003c/div\u003e\n    \u003cscript src=\"https://unpkg.com/file-upload-with-preview/dist/index.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nThen initialize like this:\n\n```javascript\nconst upload = new FileUploadWithPreview.FileUploadWithPreview('my-unique-id');\n```\n\nThen when you're ready to use the user's file for an API call or whatever, just access the user's uploaded file/files in the `cachedFileArray` property of your initialized object like this:\n\n```javascript\nupload.cachedFileArray;\n```\n\nYou can optionally trigger the image browser and clear selected images programmatically. There are additional methods on the class if you'd like to take a look at the source code.\n\n```javascript\nupload.emulateInputSelection(); // to open image browser\nupload.resetPreviewPanel(); // clear all selected images\n```\n\nYou may also want to capture the event when an image is selected.\n\n```javascript\nimport { Events, ImageAddedEvent } from 'file-upload-with-preview';\n\nwindow.addEventListener(Events.IMAGE_ADDED, (e: Event) =\u003e {\n  const { detail } = e as unknown as ImageAddedEvent;\n\n  console.log('detail', detail);\n});\n```\n\n### Note\n\nThe `cachedFileArray` property is always an array. So if you are only allowing the user to upload a single file, you can access that file at `cachedFileArray[0]` - otherwise just send the entire array to your backend to handle it normally.\n\nMake sure to pass in `multiple: true` in your options if you want to allow the user to select multiple images.\n\n## Docs\n\nView the full docs [here](https://johndatserakis.github.io/file-upload-with-preview/typedoc/).\n\n## Full Example\n\nSee the full example in the `./example/index.ts` folder. See the top of this README for some links to a few live CodeSandbox's.\n\n## Browser Support\n\nIf you are supporting a browser like IE11, one way to add a polyfill for `fetch` and `promise` is by adding the following in the bottom of your `index.html`:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/fetch/2.0.3/fetch.js\"\u003e\u003c/script\u003e\n```\n\n## Development\n\n```bash\n# Install dependencies\nyarn\n\n# Watch changes during local development\nyarn dev\n\n# Run tests\nyarn test\n\n# Build library\nyarn build\n```\n\n## Other\n\nGo ahead and fork the project! Submit an issue if needed. Have fun!\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohndatserakis%2Ffile-upload-with-preview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohndatserakis%2Ffile-upload-with-preview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohndatserakis%2Ffile-upload-with-preview/lists"}