Skip to content

Commit 2b88d6f

Browse files
QuentinGabQuentinGab
committed
doc
1 parent 584e61c commit 2b88d6f

File tree

1 file changed

+70
-52
lines changed

1 file changed

+70
-52
lines changed

‎README.md‎

Lines changed: 70 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,12 @@
55
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/ElegantEngineeringTech/livewire-modal/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/ElegantEngineeringTech/livewire-modal/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
66
[![Total Downloads](https://img.shields.io/packagist/dt/elegantly/livewire-modal.svg?style=flat-square)](https://packagist.org/packages/elegantly/livewire-modal)
77

8-
With this package, you can effortlessly open Livewire components inside modals or slideovers, featuring:
8+
This package allows you to seamlessly open Livewire components inside modals or slideovers with powerful features:
99

1010
- Support for modals, slideovers, or any similar UI pattern.
11-
- Nested modals (one at a time).
12-
- Stacked modals.
11+
- Nested and stacked modals.
1312
- Custom styling and animations, with optional presets.
14-
- Preloading components for faster user interactions.
13+
- Preloading components for faster interactions.
1514

1615
## Requirements
1716

@@ -24,7 +23,7 @@ This package provides a single Livewire `Modal` component that you should place
2423

2524
You can open and close modals by dispatching `modal-open` and `modal-close` events.
2625

27-
Any Livewire component can be used as a modal, no need for special interfaces or base components. Simply use your existing components as they are.
26+
Any Livewire component can be used as a modal without requiring special interfaces or base components. Simply use your existing components as they are.
2827

2928
## Installation
3029

@@ -34,7 +33,7 @@ Install the package via Composer:
3433
composer require elegantly/livewire-modal
3534
```
3635

37-
To customize modal behavior, you can publish the views with:
36+
To customize modal behavior, publish the views with:
3837

3938
```bash
4039
php artisan vendor:publish --tag="livewire-modal-views"
@@ -44,21 +43,19 @@ php artisan vendor:publish --tag="livewire-modal-views"
4443

4544
### Configuring Tailwind CSS
4645

47-
Since the modal component is styled using Tailwind CSS, you need to include its views in your Tailwind configuration file:
46+
Since the modal component is styled using Tailwind CSS, you must include its views in your Tailwind configuration file:
4847

4948
```js
5049
export default {
51-
// ...
5250
content: [
5351
"./vendor/elegantly/livewire-modal/resources/views/**/*.blade.php",
5452
],
55-
// ...
5653
};
5754
```
5855

59-
### Preparing your App
56+
### Setting Up Your Application
6057

61-
Add the modal manager component `<livewire:modal />` at the end of your `body` tag. This is usually done in your layout views:
58+
Add the modal manager component `<livewire:modal />` at the end of your `body` tag. This is typically done in your layout views:
6259

6360
```html
6461
<body>
@@ -67,79 +64,100 @@ Add the modal manager component `<livewire:modal />` at the end of your `body` t
6764
</body>
6865
```
6966

70-
### Preparing your Modals
67+
### Preparing Your Modals
7168

72-
Any Livewire component can be displayed as a modal, however, some features like stacking, requires you to customize your components.
69+
Any Livewire component can be displayed as a modal. However, certain features like stacking require additional customization.
7370

74-
### Opening a Modal
75-
76-
To open a modal, dispatch a `modal-open` event with the following parameters:
71+
#### Creating a Simple Modal Component
7772

78-
- `component`: The name of the Livewire component (required)
79-
- `props`: An array of properties to pass to the component (optional)
80-
- `stack`: A string identifying a specific stack, like `left` or `center` (optional)
81-
- `params`: Additional parameters to store in the modal manager (optional)
73+
This package provides two Blade components to simplify stacking and positioning:
8274

83-
You can disptach the events using three methods:
75+
- `x-livewire-modal::stack`: Provides a basic layout with stacking capabilities.
76+
- `x-livewire-modal::modal`: Handles positioning and stacking.
8477

85-
Using Alpine `$distach` from inside an Alpine or Livewire component:
78+
Wrap your content within these components:
8679

8780
```html
88-
<button
89-
type="button"
90-
x-on:click="$dispatch('modal-open', { component: 'users.show', props: { userId: 1 } })"
91-
>
92-
See User
93-
</button>
81+
<x-livewire-modal::stack>
82+
<x-livewire-modal::modal
83+
position="center"
84+
class="w-full max-w-md overflow-auto rounded-lg bg-white p-5"
85+
>
86+
<div class="prose">
87+
<p>
88+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam
89+
rhoncus, augue eget vulputate vehicula, justo dui auctor est, at
90+
iaculis urna orci ut nunc.
91+
</p>
92+
</div>
93+
</x-livewire-modal::modal>
94+
</x-livewire-modal::stack>
9495
```
9596

96-
Using the custom Alpine directive from inside an Alpine or Livewire component:
97+
#### Controlling the Modal Position
98+
99+
By default, modals are centered, but you can adjust their position using the `position` prop:
97100

98101
```html
99-
<button
100-
type="button"
101-
x-modal:open="{ component: 'users.show', props: { userId: 1 } }"
102-
>
103-
See User
104-
</button>
102+
<x-livewire-modal::stack>
103+
<x-livewire-modal::modal position="left"> ... </x-livewire-modal::modal>
104+
</x-livewire-modal::stack>
105105
```
106106

107-
Using the Livewire global variable from outside a component:
108-
109-
```js
110-
Livewire.dispatch("modal-open", {
111-
component: "users.show",
112-
props: { userId: 1 },
113-
});
107+
```html
108+
<x-livewire-modal::stack>
109+
<x-livewire-modal::modal position="bottom"> ... </x-livewire-modal::modal>
110+
</x-livewire-modal::stack>
114111
```
115112

116-
### Closing the Current Modal
113+
#### Fullscreen Modal
117114

118-
To close the currently active modal, dispatch a `modal-close` event. If there is a modal history, it will return to the previous modal; otherwise, all modals will close.
115+
To make a modal fullscreen, use the `fullscreen` prop:
119116

120-
You can disptach the events using three methods:
117+
```html
118+
<x-livewire-modal::stack fullscreen> ... </x-livewire-modal::stack>
119+
```
121120

122-
Using Alpine `$distach` from inside an Alpine or Livewire component:
121+
#### Creating a Slideover Component
123122

124123
```html
125-
<button type="button" x-on:click="$dispatch('modal-close')">Close</button>
124+
<x-livewire-modal::stack>
125+
<x-livewire-modal::slideover
126+
class="w-full max-w-md overflow-auto rounded-lg bg-white p-5"
127+
>
128+
<div class="prose">
129+
<p>
130+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam
131+
rhoncus, augue eget vulputate vehicula, justo dui auctor est, at
132+
iaculis urna orci ut nunc.
133+
</p>
134+
</div>
135+
</x-livewire-modal::slideover>
136+
</x-livewire-modal::stack>
126137
```
127138

128-
Using the custom Alpine directive from inside an Alpine or Livewire component:
139+
### Opening a Modal
129140

130-
```html
131-
<button type="button" x-modal:close>Close</button>
141+
To open a modal, dispatch a `modal-open` event:
142+
143+
```js
144+
Livewire.dispatch("modal-open", {
145+
component: "users.show",
146+
props: { userId: 1 },
147+
});
132148
```
133149

134-
Using the Livewire global variable from outside a component:
150+
### Closing the Current Modal
151+
152+
To close the currently active modal, dispatch a `modal-close` event:
135153

136154
```js
137155
Livewire.dispatch("modal-close");
138156
```
139157

140158
### Closing All Modals
141159

142-
To close all modals at once, dispatch a `modal-close-all` event:
160+
To close all modals at once:
143161

144162
```html
145163
<button x-on:click="$dispatch('modal-close-all')">Close All</button>

0 commit comments

Comments
 (0)