You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: Add support for async initialization, loader, and slot content visibility
- Added `asyncInitialization` option to delay component initialization
- Implemented `loaderAttribute` for supporting loader spinner elements
- Added `hideSlotContentUntilMounted` option to control slot content visibility
- Updated documentation, types, and configuration to support new features
Copy file name to clipboardExpand all lines: README.md
+86-1
Original file line number
Diff line number
Diff line change
@@ -46,7 +46,9 @@ See the [Documentation](https://erangrin.github.io/vue-web-component-wrapper) fo
46
46
-**Disable Removal of Styles on Unmount**: Control the removal of styles upon component unmount to solve issues with CSS transitions.
47
47
-**Disable Shadow DOM**: Option to disable Shadow DOM for web components.
48
48
-**Replace `:root` with `:host`**: Optionally replace `:root` selectors with `:host` in your CSS to ensure styles are correctly scoped within the Shadow DOM.
49
-
49
+
-**Async Initialization**: Option to delay the initialization until its Promise resolves.
50
+
-**Loader Support**: Support for loader spinner elements until the application is fully initialized.
51
+
-**Hide slot content until the component is fully mounted**: Option to hide the content of named slots until the web-component is fully mounted.
replaceRootWithHostInCssFramework:false, // default is false
149
+
loaderAttribute:'data-web-component-loader', // default is 'data-web-component-loader'
150
+
hideSlotContentUntilMounted:true, // default is false
147
151
});
148
152
```
149
153
@@ -160,11 +164,92 @@ createWebComponent({
160
164
-**disableStyleRemoval**: Disable removal of styles on unmount (useful for CSS transitions).
161
165
-**disableShadowDOM**: Disable Shadow DOM for web components.
162
166
-**replaceRootWithHostInCssFramework**: Replace `:root` selectors with `:host` in your CSS styles.
167
+
-**asyncInitialization**: Accepts a function that returns a Promise.
168
+
-**loaderAttribute**: Defines the attribute used to mark loader spinner (default is `data-web-component-loader`).
169
+
-**hideSlotContentUntilMounted**: Hide the content of named slots until the component is fully mounted.
170
+
171
+
### asyncInitialization
172
+
173
+
The `asyncInitialization` option accepts a function that returns a Promise. The custom element waits for this Promise to resolve before completing its initialization. This is useful for performing asynchronous tasks (e.g., API calls, dynamic imports) before the app mounts.
174
+
175
+
#### Example Usage
176
+
177
+
```javascript
178
+
constasyncPromise= () => {
179
+
returnnewPromise((resolve) => {
180
+
setTimeout(() => {
181
+
resolve()
182
+
}, 1000)
183
+
})
184
+
}
185
+
186
+
createWebComponent({
187
+
rootComponent: App,
188
+
elementName:'my-web-component',
189
+
plugins: pluginsWrapper,
190
+
cssFrameworkStyles: tailwindStyles,
191
+
VueDefineCustomElement,
192
+
h,
193
+
createApp,
194
+
getCurrentInstance,
195
+
asyncInitialization: asyncPromise, // default is Promise.resolve()
196
+
loaderAttribute:'data-web-component-loader',
197
+
hideSlotContentUntilMounted:true, // default is false
198
+
});
199
+
```
200
+
201
+
### loaderAttribute
202
+
203
+
The `loaderAttribute` option defines the attribute used to mark loader spinner elements in your custom element's DOM. Elements with this attribute will be removed automatically once the component is fully mounted.
border-left-color: #4a90e2; /* Customize spinner color if needed */
219
+
border-radius: 50%;
220
+
width: 30px;
221
+
height: 30px;
222
+
animation: spin 1slinearinfinite;
223
+
margin: auto;
224
+
}
225
+
226
+
@keyframesspin {
227
+
to {
228
+
transform: rotate(360deg);
229
+
}
230
+
}
231
+
</style>
232
+
```
233
+
234
+
### hideSlotContentUntilMounted
235
+
236
+
The `hideSlotContentUntilMounted` option hides the content of named slots until the component is fully mounted.
237
+
- By using the `hidden` attribute on the slot element, the content will be hidden until the component is fully mounted, and the web component wrapper will remove the `hidden` attribute once the component is fully mounted.
238
+
- This could be break the layout of your application, if you use the `hidden` attribute internally in your application.
239
+
- If you want to use the `hidden` attribute internally in your application, you can set the `hideSlotContentUntilMounted` option to `false`.
240
+
241
+
```html
242
+
<my-web-component>
243
+
<!-- named slot -->
244
+
<divclass="customName"hiddenslot="customName">I am a custom named slot </div>
245
+
</my-web-component>
246
+
```
163
247
164
248
### replaceRootWithHostInCssFramework
165
249
166
250
The `replaceRootWithHostInCssFramework` option replaces all occurrences of `:root` with `:host` in your `cssFrameworkStyles`. This is useful when working with CSS variables defined on `:root`, ensuring they are properly scoped within the Shadow DOM.
The `vue-web-component-wrapper` supports asynchronous initialization, allowing you to perform tasks (e.g., fetching configuration data or dynamically importing modules) before your web component is fully mounted.
4
+
5
+
## How It Works
6
+
7
+
By providing an `asyncInitialization` function that returns a Promise in the `createWebComponent` method, the web component waits for the Promise to resolve before mounting the Vue component. This is useful when you need to perform asynchronous operations (such as API calls or dynamic imports) prior to the component's initialization.
8
+
9
+
## Example
10
+
11
+
```javascript
12
+
constasyncPromise= () => {
13
+
returnnewPromise((resolve) => {
14
+
// Simulate an asynchronous task (e.g., API call, dynamic import)
15
+
setTimeout(() => {
16
+
resolve();
17
+
}, 1000);
18
+
});
19
+
};
20
+
21
+
createWebComponent({
22
+
rootComponent: App,
23
+
elementName:'my-web-component',
24
+
plugins: pluginsWrapper,
25
+
cssFrameworkStyles: tailwindStyles,
26
+
VueDefineCustomElement,
27
+
h,
28
+
createApp,
29
+
getCurrentInstance,
30
+
asyncInitialization: asyncPromise, // Wait for this promise to resolve before mounting
31
+
loaderAttribute:'data-web-component-loader',
32
+
hideSlotContentUntilMounted:true,
33
+
});
34
+
```
35
+
36
+
In this example, the Vue app inside the web component will not mount until the asynchronous task completes.
# Replace `:root` with `:host` in CSS Framework Styles
2
+
3
+
When working with global CSS styles or CSS frameworks, rules defined on the `:root` selector might not work as expected inside a web component that uses Shadow DOM. The `replaceRootWithHostInCssFramework` option automatically converts `:root` to `:host` in your imported CSS styles.
4
+
5
+
## How It Works
6
+
7
+
By enabling the `replaceRootWithHostInCssFramework` option, any occurrence of `:root` in your `cssFrameworkStyles` will be replaced with `:host` during component creation. This ensures that CSS variables and other styles remain correctly scoped within the web component's Shadow DOM.
8
+
9
+
## Usage
10
+
11
+
Set the option to `true` when creating your web component:
12
+
13
+
```javascript
14
+
createWebComponent({
15
+
rootComponent: App,
16
+
elementName:'my-web-component',
17
+
plugins: pluginsWrapper,
18
+
cssFrameworkStyles: tailwindStyles,
19
+
VueDefineCustomElement,
20
+
h,
21
+
createApp,
22
+
getCurrentInstance,
23
+
replaceRootWithHostInCssFramework:true, // Enable replacement of :root with :host
24
+
});
25
+
```
26
+
27
+
This feature is particularly useful when your global CSS or framework styles rely on selectors defined on `:root`, ensuring they are correctly applied within the Shadow DOM.
0 commit comments