Handling uploads with Vue | laravel-medialibrary | Spatie SPATIE Laravel Media Library ======================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-medialibrary](https://spatie.be/docs/laravel-medialibrary/v10) Handling-uploads-with-media-library-pro Handling uploads with Vue Version v11 v10 v9 v8 v7 v6 v5 v4 v3 Other versions for crawler [v11](https://spatie.be/docs/laravel-medialibrary/v11) [v10](https://spatie.be/docs/laravel-medialibrary/v10) [v9](https://spatie.be/docs/laravel-medialibrary/v9) [v8](https://spatie.be/docs/laravel-medialibrary/v8) [v7](https://spatie.be/docs/laravel-medialibrary/v7) [v6](https://spatie.be/docs/laravel-medialibrary/v6) [v5](https://spatie.be/docs/laravel-medialibrary/v5) [v4](https://spatie.be/docs/laravel-medialibrary/v4) [v3](https://spatie.be/docs/laravel-medialibrary/v3) - [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v10/introduction) - [ Support us ](https://spatie.be/docs/laravel-medialibrary/v10/support-us) - [ Base installation ](https://spatie.be/docs/laravel-medialibrary/v10/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v10/questions-issues) - [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v10/requirements) - [ Upgrading ](https://spatie.be/docs/laravel-medialibrary/v10/upgrading) - [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v10/changelog) - [ Troubleshooting ](https://spatie.be/docs/laravel-medialibrary/v10/troubleshooting) - [ About us ](https://spatie.be/docs/laravel-medialibrary/v10/about-us) Basic usage ----------- - [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v10/basic-usage/preparing-your-model) - [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v10/basic-usage/associating-files) - [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v10/basic-usage/retrieving-media) Working with media collections ------------------------------ - [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v10/working-with-media-collections/simple-media-collections) - [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v10/working-with-media-collections/defining-media-collections) Converting images ----------------- - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v10/converting-images/defining-conversions) - [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v10/converting-images/retrieving-converted-images) - [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v10/converting-images/optimizing-converted-images) - [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v10/converting-images/regenerating-images) Handling uploads with Media Library Pro --------------------------------------- - [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/introduction) - [ Installation ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/installation) - [ Processing uploads on the server ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/processing-uploads-on-the-server) - [ Handling uploads with Livewire 2 ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-livewire-2) - [ Handling uploads with Livewire 3 ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-livewire-3) - [ Handling uploads with Vue ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-vue) - [ Creating custom Vue components ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/creating-custom-vue-components) - [ Handling uploads with React ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-react) - [ Creating custom React components ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/creating-custom-react-components) - [ Customizing CSS ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/customizing-css) - [ Upgrading ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/upgrading) Responsive images ----------------- - [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/getting-started-with-responsive-images) - [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/using-your-own-width-calculator) - [ Customizing the rendered HTML ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/customizing-the-rendered-html) - [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/generating-your-own-tiny-placeholder) - [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/demo) Converting other file types --------------------------- - [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v10/converting-other-file-types/using-image-generators) - [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v10/converting-other-file-types/creating-a-custom-image-generator) Downloading media ----------------- - [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v10/downloading-media/downloading-a-single-file) - [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v10/downloading-media/downloading-multiple-files) Advanced usage -------------- - [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/working-with-multiple-filesystems) - [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-custom-properties) - [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/storing-media-specific-manipulations) - [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-your-own-model) - [ Outputting media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/outputting-media) - [ Rendering media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/rendering-media) - [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-a-custom-directory-structure) - [ Using a custom file removal strategy ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-a-custom-file-removal-strategy) - [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/ordering-media) - [ Using a custom media downloader ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-a-custom-media-downloader) - [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/moving-media) - [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/consuming-events) - [ Attaching media in mails ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/attaching-media-in-mails) - [ Generating custom URLs ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/generating-custom-urls) - [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/overriding-the-default-filesystem-behaviour) - [ Naming generated files ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/naming-files) - [ Disable CDN ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/disable-cdn) - [ Customising Database Connections ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/customising-database-connections) API --- - [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v10/api/adding-files) - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v10/api/defining-conversions) You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command: ` composer show spatie/laravel-medialibrary ` Handling uploads with Vue ========================= ### On this page 1. [ Demo application ](#content-demo-application) 2. [ Basic setup ](#content-basic-setup) 3. [ Vite ](#content-vite) 4. [ Your first components ](#content-your-first-components) 5. [ Validation rules ](#content-validation-rules) 6. [ Translations ](#content-translations) 7. [ Props ](#content-props) Media Library Pro provides beautiful UI components for Vue 2 and Vue 3. They pack a lot of features: temporary uploads, custom property inputs, frontend validation, and robust error handling. The `MediaLibraryAttachment` component can upload one or more files with little or no extra information. The attachment component is a lightweight solution for small bits of UI like avatar fields. ![Screenshot of the MediaLibraryAttachment Vue component](/docs/laravel-medialibrary/v10/images/pro/attachment.png) The `MediaLibraryCollection` component can upload multiple files with custom properties. The collection component shines when you need to manage media, like in backoffices. ![Screenshot of the MediaLibraryCollection Vue component](/docs/laravel-medialibrary/v10/images/pro/collection.png) If neither of these fit the bill, we've exposed a set of APIs for you to be bold and [roll your own components](./creating-custom-vue-components). Demo application -------------------------------------------------------------------------------------------------------- In [this repo on GitHub](https://github.com/spatie/laravel-medialibrary-pro-app), you'll find a demo Laravel application in which you'll find examples of how to use Media Library Pro with Vue. If you are having troubles using the components, take a look in that app to see how we've done it. Basic setup ----------------------------------------------------------------------------------------- First, the server needs to be able to catch your incoming uploads. Use the `mediaLibrary` macro in your routes file. ``` // Probably routes/web.php Route::mediaLibrary(); ``` The macro will register a route on `/media-library-pro/uploads`, which is used by the Vue components by default. You can change the prefix by passing it to the macro: ``` // Probably routes/web.php Route::mediaLibrary('my-custom-url'); ``` This will register a route at `/my-custom-url/uploads` instead. ### Customizing the upload endpoint The Vue components post data to `/media-library-pro/uploads` by default. If you changed the prefix in the route macro, pass it to the `route-prefix` prop of your Vue components. ``` ``` ### Importing the components The components aren't available through npm, but are located in `vendor/spatie/laravel-medialibrary-pro/resources/js` when you install the package through Composer. This makes for very long import statements, which you can clean up by adding some configuration to your Webpack/Laravel Mix configuration. *If you're developing a project where you don't have access to composer, you can download the package through GitHub Packages: [installation steps](./installation#usage-in-a-frontend-repository)* **laravel-mix >6** ``` // webpack.mix.js mix.override((webpackConfig) => { webpackConfig.resolve.modules = [ "node_modules", __dirname + "/vendor/spatie/laravel-medialibrary-pro/resources/js", ]; }); ``` **laravel-mix <6** ``` // webpack.mix.js mix.webpackConfig({ resolve: { modules: [ "node_modules", __dirname + "/vendor/spatie/laravel-medialibrary-pro/resources/js", ], }, }); ``` This will force Webpack to look in `vendor/spatie/laravel-medialibrary-pro/resources/js` when resolving imports, and allows you to shorten your import. Notice that the Vue 2 and Vue 3 components are separate components. ``` import { MediaLibraryAttachment } from "media-library-pro-vue2-attachment"; // or import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment"; ``` If you're using TypeScript, you will also have to add this to your tsconfig: ``` // tsconfig.json { "compilerOptions": { "paths": { "*": ["*", "vendor/spatie/laravel-medialibrary-pro/resources/js/*"] } } } ``` To use a component in your Blade templates, import the components you plan to use in your `app.js` file, and add them to your main Vue app's `components` object. **Vue 2** ``` import Vue from "vue"; import { MediaLibraryAttachment } from "media-library-pro-vue2-attachment"; import { MediaLibraryCollection } from "media-library-pro-vue2-collection"; new Vue({ el: "#app", components: { MediaLibraryAttachment, MediaLibraryCollection, }, }); ``` **Vue 3** ``` import { createApp } from "vue"; import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment"; import { MediaLibraryCollection } from "media-library-pro-vue3-collection"; createApp({ components: { MediaLibraryAttachment, MediaLibraryCollection, }, }).mount("#app"); ``` You can now use them in any `.blade.php` file in your application. ``` Submit ``` You may also choose to import the components on the fly in a `.vue` file. ``` Submit import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment"; import { MediaLibraryCollection } from "media-library-pro-vue3-collection"; export default { components: { MediaLibraryAttachment, MediaLibraryCollection, }, }; ``` Vite -------------------------------------------------------------------- If you are using vite, you need to import an alias to the `vite.config.js` and some little changes to your Vue component. ``` // vite.config.js import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; import vue from '@vitejs/plugin-vue'; export default defineConfig({ ... resolve: { alias: { '@': '/resources/js', + 'spatie-media-lib-pro': '/vendor/spatie/laravel-medialibrary-pro/resources/js', }, }, }); ``` **Component changes Vue2** ``` ... - import { MediaLibraryAttachment } from "media-library-pro-vue2-attachment"; + import { MediaLibraryAttachment } from "spatie-media-lib-pro/media-library-pro-vue2-attachment"; - import { MediaLibraryCollection } from "media-library-pro-vue2-collection"; + import { MediaLibraryCollection } from "spatie-media-lib-pro/media-library-pro-vue2-collection"; ... ``` **Component changes Vue3** ``` ... - import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment"; + import { MediaLibraryAttachment } from "spatie-media-lib-pro/media-library-pro-vue3-attachment"; - import { MediaLibraryCollection } from "media-library-pro-vue3-collection"; + import { MediaLibraryCollection } from "spatie-media-lib-pro/media-library-pro-vue3-collection"; ... ``` **CSS Import for SPA use** If you are using a SPA you can import the CSS into `app.js` like this: ``` // resources/js/app.js import './bootstrap'; import '../css/app.css'; + import 'spatie-media-lib-pro/media-library-pro-styles/src/styles.css'; ... ``` If you want to import the CSS into `app.css` you can still use the import mentioned in [Customizing CSS](./customizing-css). Your first components ----------------------------------------------------------------------------------------------------------------------- The most basic components have a `name` prop. This name will be used to identify the media when it's uploaded to the server. ``` Submit import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment"; import { MediaLibraryCollection } from "media-library-pro-vue3-collection"; export default { components: { MediaLibraryAttachment, MediaLibraryCollection, }, }; ``` ### Passing an initial value If your form modifies an existing set of media, you may pass it through in the `initial-value` prop. You can retrieve your initial values in Laravel using `$yourModel->getMedia($collectionName)`. This will also take care of any `old` values after an invalid form submit. You can also use this straight in your blade file: ``` Submit ``` Under the hood, these components create hidden `` fields to keep track of the form values on submit. If you would like to submit your values asynchronously, refer to [the `Asynchronously submit data` section](#asynchronously-submit-data). ### Setting validation rules You'll probably want to validate what gets uploaded. Use the `validation-rules` prop, and don't forget to pass Laravel's validation errors too. The validation errors returned from the server will find errors under the key used in your `name` prop. ``` Submit ``` You can also set the maximum amount of images that users can be uploaded using the `max-items` prop. Don't forget to set the `multiple` prop for the attachment component. ``` Submit ``` See the [Validation rules section](#validation-rules) for a complete list of all possible validation rules. ### Checking the upload state The components keep track of whether they're ready to be submitted, you can use this to disable a submit button while a file is still uploading or when there are frontend validation errors. This value can be tracked by listening to a `is-ready-to-submit-change` event on the components. If you submit a form while a file is uploading, Laravel will return a HTTP 500 error with an `invalid uuid` message. ``` Submit import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment"; export default { components: { MediaLibraryAttachment }, data() { return { isReadyToSubmit: true, }; }, }; ``` ### Using custom properties The Media Library supports [custom properties](/docs/laravel-medialibrary/v10/advanced-usage/using-custom-properties) to be saved on a media item. The values for these can be chosen by your users. By default, the `MediaLibraryAttachment` component doesn't show any input fields, and the `MediaLibraryCollection` component only shows a `name` field, with the option to add more fields. Use the `fields` scoped slot to add some fields: **Vue 2** ``` Name @{{ error }} Extra field @{{ error }} ``` **Vue 3** ``` … (see Vue 2 example above) ``` When you add an image to your collection, it will look like this. ![Screenshot of custom property](/docs/laravel-medialibrary/v10/images/pro/extra.png) ### Customizing the file properties When uploading a file, some properties appear by default: its extension, filesize and a remove or download button (respectively for the attachment or collection component). You can customize what is displayed here by using the `properties` scoped slot: **Vue 2** ``` {{ object.attributes.name }} ``` **Vue 3** ``` {{ object.attributes.name }} ``` ### Asynchronously submit data If you don't want to use traditional form submits to send your data to the backend, you will have to keep track of the current value of the component using the `onChange` handler. The syntax is the same for all UI components: ``` Submit import Axios from "axios"; export default { props: { values }, data() { return { validationErrors: {}, media: this.values.media, }; }, methods: { onChange(media) { this.media = media; }, submitForm() { Axios.post("endpoint", { media: this.media }).catch( (error) => (this.validationErrors = error.data.errors) ); }, }, }; ``` ### Usage with Laravel Vapor If you are planning on deploying your application to AWS using [Laravel Vapor](https://vapor.laravel.com/), you will need to do some extra configuration to make sure files are uploaded properly to an S3 bucket. First off, make sure you have [enabled Vapor support in Laravel](./processing-uploads-on-the-server#enabling-vapor-support). You will also need to set the `vapor` prop in your components. ``` ``` If you edited Vapor's signed storage URL in Laravel, you will need to pass the new endpoint to your components in `vapor-signed-storage-url`. It will use `/vapor/signed-storage-url` by default. ``` ``` ### Usage with Inertia When using the components in repository that uses Inertia, the setup is very similar to the asynchronous setup. ``` Submit import { Inertia } from "@inertiajs/inertia"; export default { data() { return { validationErrors: this.$page.props.errors, avatar: this.$page.props.values.avatar, }; }, methods: { onChange(avatar) { this.avatar = avatar; }, submitForm() { Inertia.post("", { avatar: this.avatar }); }, }, }; ``` Validation rules -------------------------------------------------------------------------------------------------------- There are a couple of different ways to validate files on the frontend. These props are available to you: `validationRules`, `maxItems` and `beforeUpload`. **validationRules** In the `validationRules` object, we've got the `accept` property, which expects an array of MIME types as strings. Leave it empty to accept all types of files, set its value to `['image/*']` to accept any type of image, or choose your own set of rules using [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types). Remember, the only valid MIME type of a JPEG/JPG is `image/jpeg`! The `minSizeInKB` and `maxSizeInKB` properties set the minimum and maximum size of any individual file. ``` ``` **maxItems** Set the maximum amount of items in the collection/attachment component at any time. ``` ``` **beforeUpload** Pass a method to `before-upload` that accepts a [file](https://developer.mozilla.org/en-US/docs/Web/API/File) parameter. Return any value (or resolve a Promise with any value) from this function to upload the file. Throw an Error in this function to cause the file not to be uploaded, and display your error message. ``` export default { … methods: { checkFileValidity(file) { return new Promise((resolve) => { if (file.size < 1000) { return resolve(); } throw new Error("The uploaded file is too big"); }); } }, } ``` Translations -------------------------------------------------------------------------------------------- If you would like to use the components in your own language, you can pass a `translations` prop to the component. ``` ``` The values mentioned here are the defaults. Feel free to only pass in a couple of keys, as your object will be merged onto the default. If you use the component in different parts of your app, you might want to set the translations globally. ``` window.mediaLibraryTranslations = { somethingWentWrong: "whoops", remove: "delete", }; ``` If you use the [vue-i18n](https://vue-i18n.intlify.dev/) package from intlify, you can also pass the keys from a translation file like `lang/media-library.php` by using the [`$tm`-function](https://vue-i18n.intlify.dev/api/composition.html#tm-key). ``` ``` Props ----------------------------------------------------------------------- These props are available on both the `attachment` and the `collection` component. prop nameDefault valueDescriptionnameinitial-value`[]`route-prefix`"media-library-pro"`upload-domainUse this if you're uploading your files to a separate (sub)domain, e.g. `files.mydomain.com` (leave out the trailing slash)validation-rulesRefer to the ["validation rules"](#validation-rules) sectionvalidation-errorsThe standard Laravel validation error objectmultiple`false` (always `true` in the `collection` component)Only exists on the `attachment` componentsmax-items`1` when `multiple` = `false`, otherwise `undefinedvaporSet to true if you will deploy your application to Vapor. This enables uploading of the files to S3.vapor-signed-storage-url`"vapor/signed-storage-url"`max-size-for-preview-in-bytes`5242880` (5 MB)When an image is added, the component will try to generate a local preview for it. This is done on the main thread, and can freeze the component and/or page for very large filessortable`true`Only exists on the `collection` components. Allows the user to drag images to change their order, this will be reflected by a zero-based `order` attribute in the valuetranslationsRefer to the ["Translations"](#translations) sectionfile-type-help-textOverride the automatically generated helptext from `validation-rules.accept`refUsed to set a reference to the MediaLibrary instance, so you can change the internal state of the component.before-uploadA method that is run right before a temporary upload is started. You can throw an `Error` from this function with a custom validation messageafter-uploadA method that is run right after a temporary upload has completed, `{ success: true, uuid }`@changed@is-ready-to-submit-changeRefer to [Checking the upload state](#checking-the-upload-state) section