webview: add CSS styling notes

Create a new section for CSS and add notes to avoid hiding the webview via hidden or display:none; and provide a recommended approach.

diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md
index 8df8d29..cee06df 100644 (file)
--- a/docs/api/web-view-tag.md
+++ b/docs/api/web-view-tag.md
@@ -20,11 +20,6 @@ control the appearance of the `webview` container:
 ```html
 <webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>
 ```
-Please note that the `webview` tag's style uses `display:flex;` internally to 
-ensure the child `object` element fills the full height and width of its `webview` 
-container when used with traditional and flexbox layouts (since v0.36.11). Please 
-do not overwrite the default `display:flex;` CSS property, unless specifying 
-`display:inline-flex;` for inline layout.
 
 If you want to control the guest content in any way, you can write JavaScript
 that listens for `webview` events and responds to those events using the
@@ -50,6 +45,36 @@ and displays a "loading..." message during the load time:
 </script>
 ```
 
+## CSS Styling Notes
+
+Please note that the `webview` tag's style uses `display:flex;` internally to 
+ensure the child `object` element fills the full height and width of its `webview` 
+container when used with traditional and flexbox layouts (since v0.36.11). Please 
+do not overwrite the default `display:flex;` CSS property, unless specifying 
+`display:inline-flex;` for inline layout.
+
+`webview` has issues being hidden using the `hidden` attribute or using `display: none;`. 
+It can cause unusual rendering behaviour within its child `browserplugin` object 
+and the web page is reloaded, when the `webview` is un-hidden, as opposed to just 
+becoming visible again. The recommended approach is to hide the `webview` using 
+CSS by zeroing the `width` & `height` and allowing the element to shrink to the 0px 
+dimensions via `flex`.
+
+```html
+<style>
+  webview {
+    display:inline-flex;
+    width:640px;
+    height:480px;
+  }
+  webview.hide {
+    flex: 0 1;
+    width: 0px;
+    height: 0px; 
+  }
+</style>
+```
+
 ## Tag Attributes
 
 The `webview` tag has the following attributes: