{"id":13423014,"url":"https://github.com/wire-elements/modal","last_synced_at":"2026-01-23T13:49:47.793Z","repository":{"id":37928830,"uuid":"353093114","full_name":"wire-elements/modal","owner":"wire-elements","description":"Livewire component that provides you with a modal that supports multiple child modals while maintaining state.","archived":false,"fork":false,"pushed_at":"2025-04-24T07:58:59.000Z","size":656,"stargazers_count":1191,"open_issues_count":7,"forks_count":141,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-05-11T12:38:48.427Z","etag":null,"topics":["laravel","livewire","livewire-components"],"latest_commit_sha":null,"homepage":"https://wire-elements.dev","language":"PHP","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/wire-elements.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":["PhiloNL"]}},"created_at":"2021-03-30T17:54:40.000Z","updated_at":"2025-05-11T11:32:18.000Z","dependencies_parsed_at":"2024-01-06T23:23:57.497Z","dependency_job_id":"f5586f25-8f01-4dc2-a058-18a00747a9f6","html_url":"https://github.com/wire-elements/modal","commit_stats":{"total_commits":84,"total_committers":28,"mean_commits":3.0,"dds":0.6666666666666667,"last_synced_commit":"17b61596d15827394d7c2cd3e3efac28e2e93c30"},"previous_names":["livewire-ui/modal"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fmodal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fmodal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fmodal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fmodal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wire-elements","download_url":"https://codeload.github.com/wire-elements/modal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754115,"owners_count":21958842,"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":["laravel","livewire","livewire-components"],"created_at":"2024-07-30T23:01:05.302Z","updated_at":"2026-01-16T16:51:00.592Z","avatar_url":"https://github.com/wire-elements.png","language":"PHP","funding_links":["https://github.com/sponsors/PhiloNL"],"categories":["UI","Packages / Plugins","PHP"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/wire-elements/modal/actions\"\u003e\u003cimg src=\"https://github.com/wire-elements/modal/workflows/PHPUnit/badge.svg\" alt=\"Build Status\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/wire-elements/modal\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/wire-elements/modal\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/livewire-ui/modal\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/livewire-ui/modal\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/wire-elements/modal\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/wire-elements/modal\" alt=\"Latest Stable Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/wire-elements/modal\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/wire-elements/modal\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Livewire v3\nThis is the readme for Livewire v3. **If you are looking for the readme for Livewire v2 [click here](https://github.com/wire-elements/modal/tree/1.0.0).**\n\n### Upgrading from v2\n\nYou can use the following command to automate the upgrade process:\n\n```shell\nphp artisan livewire:upgrade --run-only wire-elements-modal-upgrade\n```\n\nPlease review the changes and ensure they follow the new convention set by Livewire v3:\n\n```blade\n\u003c-- Before --\u003e\n\u003cbutton wire:click=\"$emit('openModal', 'users')\"\u003eShow Users\u003c/button\u003e\n\u003c!-- After --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', {component: 'users'})\"\u003eShow Users\u003c/button\u003e\n\n\u003c-- Before --\u003e\n\u003cbutton wire:click=\"$emit('openModal', 'edit-user', {user: 5})\"\u003eEdit User\u003c/button\u003e\n\u003c!-- After --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', {component: 'edit-user', arguments: {user: 5}})\"\u003eEdit User\u003c/button\u003e\n```\n\nThe old component name is being deprecated. Replace `@livewire('livewire-ui-modal')` with `@livewire('wire-elements-modal')`.\n\nThe config file has been renamed as well. If you've published the config in the past, you will have to do so again and make the necessary changes:\n\n```shell\nphp artisan vendor:publish --tag=wire-elements-modal-config\n```\n\nAfter upgrading, make sure to clear your view cache:\n\n```shell\nphp artisan view:clear\n```\n\n## About Wire Elements Modal\nWire Elements Modal is a Livewire component that provides you with a modal that supports multiple child modals while maintaining state.\n\n## Installation\n\n\u003ca href=\"https://philo.dev/laravel-modals-with-livewire/\"\u003e\u003cimg src=\"https://d.pr/i/GR66B3+\" alt=\"\"\u003e\u003c/a\u003e\n\nClick the image above to read a full article on using the Wire Elements modal package or follow the instructions below.\n\nTo get started, require the package via Composer:\n\n```\ncomposer require wire-elements/modal:^2.0\n```\n\n## Livewire directive\nAdd the Livewire directive `@livewire('wire-elements-modal')` directive to your template.\n```html\n\u003chtml\u003e\n\u003cbody\u003e\n    \u003c!-- content --\u003e\n\n    @livewire('wire-elements-modal')\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## TailwindCSS\nThe base modal is made with TailwindCSS. If you use a different CSS framework I recommend that you publish the modal template and change the markup to include the required classes for your CSS framework.\n```shell\nphp artisan vendor:publish --tag=wire-elements-modal-views\n```\n\n\n## Creating a modal\nYou can run `php artisan make:livewire EditUser` to make the initial Livewire component. Open your component class and make sure it extends the `ModalComponent` class:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Livewire;\n\nuse LivewireUI\\Modal\\ModalComponent;\n\nclass EditUser extends ModalComponent\n{\n    public function render()\n    {\n        return view('livewire.edit-user');\n    }\n}\n```\n\n## Opening a modal\nTo open a modal you will need to dispatch an event. To open the `EditUser` modal for example:\n\n```html\n\u003c!-- Outside of any Livewire component --\u003e\n\u003cbutton onclick=\"Livewire.dispatch('openModal', { component: 'edit-user' })\"\u003eEdit User\u003c/button\u003e\n\n\u003c!-- Inside existing Livewire component --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', { component: 'edit-user' })\"\u003eEdit User\u003c/button\u003e\n\n\u003c!-- Taking namespace into account for component Admin/Actions/EditUser --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', { component: 'admin.actions.edit-user' })\"\u003eEdit User\u003c/button\u003e\n```\n\n## Passing parameters\nTo open the `EditUser` modal for a specific user we can pass the user id:\n\n```html\n\u003c!-- Outside of any Livewire component --\u003e\n\u003cbutton onclick=\"Livewire.dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user-\u003eid }} }})\"\u003eEdit User\u003c/button\u003e\n\n\u003c!-- Inside existing Livewire component --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user-\u003eid }} }})\"\u003eEdit User\u003c/button\u003e\n\n\u003c!-- If you use a different primaryKey (e.g. email), adjust accordingly --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user-\u003eemail }} }})\"\u003eEdit User\u003c/button\u003e\n\n\u003c!-- Example of passing multiple arguments --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user-\u003eid }}, advancedMode: true }})\"\u003eEdit User\u003c/button\u003e\n```\n\nThe parameters are injected into the modal component and the model will be automatically fetched from the database if the type is defined:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Livewire;\n\nuse App\\Models\\User;\nuse LivewireUI\\Modal\\ModalComponent;\n\nclass EditUser extends ModalComponent\n{\n    // This will inject just the ID\n    // public int $user;\n\n    public User $user;\n\n    public function mount()\n    {\n        Gate::authorize('update', $this-\u003euser);\n    }\n\n    public function render()\n    {\n        return view('livewire.edit-user');\n    }\n}\n```\n\nThe parameters are also passed to the `mount` method on the modal component.\n\n## Opening a child modal\nFrom an existing modal you can use the exact same event and a child modal will be created:\n\n```html\n\u003c!-- Edit User Modal --\u003e\n\n\u003c!-- Edit Form --\u003e\n\u003cbutton wire:click=\"$dispatch('openModal', { component: 'delete-user', arguments: { user: {{ $user-\u003eid }} }})\"\u003eDelete User\u003c/button\u003e\n```\n\n## Closing a (child) modal\nIf for example a user clicks the 'Delete' button which will open a confirm dialog, you can cancel the deletion and return to the edit user modal by dispatching the `closeModal` event. This will open the previous modal. If there is no previous modal the entire modal component is closed and the state will be reset.\n```html\n\u003cbutton wire:click=\"$dispatch('closeModal')\"\u003eNo, do not delete\u003c/button\u003e\n```\n\nYou can also close a modal from within your modal component class:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Livewire;\n\nuse App\\Models\\User;\nuse LivewireUI\\Modal\\ModalComponent;\n\nclass EditUser extends ModalComponent\n{\n    public User $user;\n\n    public function mount()\n    {\n        Gate::authorize('update', $this-\u003euser);\n    }\n\n    public function update()\n    {\n        Gate::authorize('update', $this-\u003euser);\n\n        $this-\u003euser-\u003eupdate($data);\n\n        $this-\u003ecloseModal();\n    }\n\n    public function render()\n    {\n        return view('livewire.edit-user');\n    }\n}\n```\n\nIf you don't want to go to the previous modal but close the entire modal component you can use the `forceClose` method:\n\n```php\npublic function update()\n{\n    Gate::authorize('update', $this-\u003euser);\n\n    $this-\u003euser-\u003eupdate($data);\n\n    $this-\u003eforceClose()-\u003ecloseModal();\n}\n```\n\nOften you will want to update other Livewire components when changes have been made. For example, the user overview when a user is updated. You can use the `closeModalWithEvents` method to achieve this.\n\n```php\npublic function update()\n{\n    Gate::authorize('update', $this-\u003euser);\n\n    $this-\u003euser-\u003eupdate($data);\n\n    $this-\u003ecloseModalWithEvents([\n        UserOverview::class =\u003e 'userModified',\n    ]);\n}\n```\n\nIt's also possible to add parameters to your events:\n\n```php\npublic function update()\n{\n    $this-\u003euser-\u003eupdate($data);\n\n    $this-\u003ecloseModalWithEvents([\n        UserOverview::class =\u003e ['userModified', [$this-\u003euser-\u003eid]],\n    ]);\n}\n```\n\n## Changing modal properties\n\nYou can change the width (default value '2xl') of the modal by overriding the static `modalMaxWidth` method in your modal component class:\n\n```php\n/**\n * Supported: 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl'\n */\npublic static function modalMaxWidth(): string\n{\n    return 'xl';\n}\n```\n\nBy default, the modal will close when you hit the `escape` key. If you want to disable this behavior to, for example, prevent accidentally closing the modal you can overwrite the static `closeModalOnEscape` method and have it return `false`.\n```php\npublic static function closeModalOnEscape(): bool\n{\n    return false;\n}\n```\n\nBy default, the modal will close when you click outside the modal. If you want to disable this behavior to, for example, prevent accidentally closing the modal you can overwrite the static `closeModalOnClickAway` method and have it return `false`.\n ```php\n public static function closeModalOnClickAway(): bool\n {\n     return false;\n }\n ```\n\n By default, closing a modal by pressing the escape key will force close all modals. If you want to disable this behavior to, for example, allow pressing escape to show a previous modal, you can overwrite the static `closeModalOnEscapeIsForceful` method and have it return `false`.\n ```php\n public static function closeModalOnEscapeIsForceful(): bool\n {\n     return false;\n }\n ```\n\n When a modal is closed, you can optionally enable a `modalClosed` event to be fired. This event will be fired on a call to `closeModal`, when the escape button is pressed, or when you click outside the modal. The name of the closed component will be provided as a parameter;\n ```php\n public static function dispatchCloseEvent(): bool\n {\n     return true;\n }\n ```\n\n By default, when a child modal is closed, the closed components state is still available if the same modal component is opened again. If you would like to destroy the component when its closed you can override the static `destroyOnClose` method and have it return `true`. When a destroyed modal is opened again its state will be reset.\n ```php\n public static function destroyOnClose(): bool\n {\n     return true;\n }\n ```\n\n## Preventing closing the modal on Escape or on click away based on the modal state\n\nWhen a modal is closed on Escape or click away, `closingModalOnEscape` and `closingModalOnClickAway` are issued. Handle these events to prevent closing a modal based on its state, for example, if there are uncommitted changes.\n\nFor example, if a modal has a `isDirty` property, it could have the following handler:\n\n```\n@script\n\u003cscript\u003e\n    $wire.on('closingModalOnEscape', data =\u003e {\n        if ($wire.isDirty \u0026\u0026 !confirm('{{ __('You have unsaved changes. Are you sure you want to close this dialog?') }}')) {\n            data.closing = false;\n        }\n    });\n    $wire.on('closingModalOnClickAway', data =\u003e {\n        if ($wire.isDirty \u0026\u0026 !confirm('{{ __('You have unsaved changes. Are you sure you want to close this dialog?') }}')) {\n            data.closing = false;\n        }\n    });\n\u003c/script\u003e\n@endscript\n```\n\n## Skipping previous modals\nIn some cases you might want to skip previous modals. For example:\n1. Team overview modal\n2. -\u003e Edit Team\n3. -\u003e Delete Team\n\nIn this case, when a team is deleted, you don't want to go back to step 2 but go back to the overview.\nYou can use the `skipPreviousModal` method to achieve this. By default it will skip the previous modal. If you want to skip more you can pass the number of modals to skip `skipPreviousModals(2)`.\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Livewire;\n\nuse App\\Models\\Team;\nuse LivewireUI\\Modal\\ModalComponent;\n\nclass DeleteTeam extends ModalComponent\n{\n    public Team $team;\n\n    public function mount(Team $team)\n    {\n        $this-\u003eteam = $team;\n    }\n\n    public function delete()\n    {\n        Gate::authorize('delete', $this-\u003eteam);\n\n        $this-\u003eteam-\u003edelete();\n\n        $this-\u003eskipPreviousModal()-\u003ecloseModalWithEvents([\n            TeamOverview::class =\u003e 'teamDeleted'\n        ]);\n    }\n\n    public function render()\n    {\n        return view('livewire.delete-team');\n    }\n}\n```\n\nYou can also optionally call the `destroySkippedModals()` method to destroy the skipped modals so if any are opened again their state will be reset\n\n\n\n\n\n## Building Tailwind CSS for production\nTo purge the classes used by the package, add the following lines to your purge array in `tailwind.config.js`:\n```js\n'./vendor/wire-elements/modal/resources/views/*.blade.php',\n'./storage/framework/views/*.php',\n```\n\nBecause some classes are dynamically build you should add some classes to the purge safelist so your `tailwind.config.js` should look something like this:\n```js\nmodule.exports = {\n  purge: {\n    content: [\n      './vendor/wire-elements/modal/resources/views/*.blade.php',\n      './storage/framework/views/*.php',\n      './resources/views/**/*.blade.php',\n    ],\n    options: {\n      safelist: {\n            pattern: /max-w-(sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl)/,\n            variants: ['sm', 'md', 'lg', 'xl', '2xl']\n        } \n    }\n  },\n  darkMode: false, // or 'media' or 'class'\n  theme: {\n    extend: {},\n  },\n  variants: {\n    extend: {},\n  },\n  plugins: [],\n}\n```\n\nFor TailwindCSS `3x`\n```js\nexport default {\n  content: [\n    './vendor/wire-elements/modal/resources/views/*.blade.php',\n    './storage/framework/views/*.php',\n    './resources/views/**/*.blade.php',\n  ],\n  safelist: [\n    {\n      pattern: /max-w-(sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl)/,\n      variants: ['sm', 'md', 'lg', 'xl', '2xl']\n    }\n  ],\n  // other options\n}\n```\n\n## Configuration\nYou can customize the Modal via the `wire-elements-modal.php` config file. This includes some additional options like including CSS if you don't use TailwindCSS for your application, as well as the default modal properties.\n\n To publish the config run the vendor:publish command:\n```shell\nphp artisan vendor:publish --tag=wire-elements-modal-config\n```\n\n```php\n\u003c?php\n\nreturn [\n\n    /*\n    |--------------------------------------------------------------------------\n    | Include CSS\n    |--------------------------------------------------------------------------\n    |\n    | The modal uses TailwindCSS, if you don't use TailwindCSS you will need\n    | to set this parameter to true. This includes the modern-normalize css.\n    |\n    */\n    'include_css' =\u003e false,\n\n\n    /*\n    |--------------------------------------------------------------------------\n    | Include JS\n    |--------------------------------------------------------------------------\n    |\n    | Livewire UI will inject the required Javascript in your blade template.\n    | If you want to bundle the required Javascript you can set this to false\n    | and add `require('vendor/wire-elements/modal/resources/js/modal');`\n    | to your script bundler like webpack.\n    |\n    */\n    'include_js' =\u003e true,\n\n\n    /*\n    |--------------------------------------------------------------------------\n    | Modal Component Defaults\n    |--------------------------------------------------------------------------\n    |\n    | Configure the default properties for a modal component.\n    |\n    | Supported modal_max_width\n    | 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl'\n    */\n    'component_defaults' =\u003e [\n        'modal_max_width' =\u003e '2xl',\n\n        'close_modal_on_click_away' =\u003e true,\n\n        'close_modal_on_escape' =\u003e true,\n\n        'close_modal_on_escape_is_forceful' =\u003e true,\n\n        'dispatch_close_event' =\u003e false,\n\n        'destroy_on_close' =\u003e false,\n    ],\n];\n```\n\n## Security\nIf you are new to Livewire I recommend to take a look at the [security details](https://laravel-livewire.com/docs/2.x/security). In short, it's **very important** to validate all information given Livewire stores this information on the client-side, or in other words, this data can be manipulated. Like shown in the examples above, use the `Gate` facade to authorize actions.\n\n## Credits\n- [Philo Hermans](https://github.com/philoNL)\n- [All Contributors](../../contributors)\n\n## License\nWireElements is open-sourced software licensed under the [MIT license](LICENSE.md).\n\n## Beautiful components crafted with Livewire\n\n\u003ca href=\"https://wire-elements.dev/\"\u003e\u003cimg src=\"https://philo.dev/content/images/size/w1600/2022/07/wire-elements-pro-v2.png\" width=\"600\" alt=\"\" /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwire-elements%2Fmodal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwire-elements%2Fmodal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwire-elements%2Fmodal/lists"}