Spinner Web Component (Using Custom Elements v1 and Shadow DOM)
The <spinner-component></spinner-component>
represents spinner that can be used on the page during loading of the external resources or data. Component can hold text which can be set either via attribute text
or via property on the component itself.
Component doesn't receive any children.
Download spinner-web-component.js
file and link it in your HTML document. Declare <spinner-component></spinner-component>
in your HTML document.
<!DOCTYPE html>
<html lang="en">
<head>...</head>
<body>
<spinner-component></spinner-component>
<script src="spinner-web-component.js"></script>
</body>
</html>
NOTE: When component is insterted into the DOM, it automatically gets
hidden
attribute set on it, that is, it will be hidden by default.
Chrome 54, Edge 79, Firefox 63, Opera 41, Safari 10.1, iOS Safari 10.3, Samsung Internet 6.0
- Standalone polyfill for Custom Elements v1.
- A suite of polyfills supporting the Web Components specs: webcomponents.js loader
Common attributes like id
, hidden
are supported and can be used as with the regular HTML Elements.
Component also supports the following attributes:
Represent text that will be displayed when component is visible.
NOTE: If this attribute is set on the component via HTML and then setup
method is called without setting text.value
,
then text
attribute will be used, otherwise value set via setup
method is used.
If text
attribute not set via attribute or as a property, and component doesn't have aria-label
set on it, aria-label="loading"
will be set by default.
Otherwise if text
attribute is set, aria-labelledby="spinnerText"
will be set.
Each time text
attribute is changed, either via attribute or as a property, aria-label
/aria-labelledby
will be changed accordingly.
// set via property
const spinner = document.getElementById("spinner");
spinner.text = "some text for spinner";
// get via property
const spinner = document.getElementById("spinner");
const spinnerCurrentText = spinner.text;
// set on HTML Element
<spinner-component text="some text for spinner"></spinner-component>
Component supports the following properties:
Boolean value determines whether component is visible.
// get via property
const spinner = document.getElementById("spinner");
const isSpinnerVisible = spinner.isShown;
Event is fired when component is shown by calling show
method, in addition its isShown
property will be changed accordingly.
You can determine current state of the component by reading event.detail.isShown
property. This event bubbles up through the DOM.
document.addEventListener("show", function (e) {
const isSpinnerShown = e.detail.isShown;
console.log("from spinner-component SHOW EVENT");
});
Event is fired when component is hidden by calling hide
method, its isShown
property will be changed accordingly.
You can determine current state of the component by reading event.detail.isShown
property. This event bubbles up through the DOM.
document.addEventListener("hide", function (e) {
const isSpinnerShown = e.detail.isShown;
console.log("from spinner-component HIDE EVENT");
});
Setup component with initial values.
Method receives options
object parameter with the following properties:
{HTMLElement}
parentContainer
- Containing Element for the component (coponent's container)
NOTE: container should have CSS position
property other than static (e.g. relative
or absolute
)
-
{Object}
direction
- Custom directions to adjust component manually (e.g.top: 10px
/left: 50%
etc...)Example: spinner.setup({..., "direction": {top: "41%"} });
-
{String}
color
- CSS Valid value for the color/background properties in string representation, e.g.grey
/rgb(255, 30, 30)
/#f1f1f1
-
{Number}
size
- Size of the component, 1 is 100%, 0.5 is 50% of the spinner's original size (NOTE: component's size, internally, set viafont-size
property) -
{Object}
text
- Options for the component's text element:-
{String}
color
- CSS Valid value for the color/background properties in string representation, e.g.grey
/rgb(255, 30, 30)
/#f1f1f1
-
{Number}
size
- Size of the component's text, 1 is 100%, 0.5 is 50% of the component's original size -
{Object}
direction
- Custom directions to adjust component's text manually (e.g. top:10px
/left: 50%
etc...)Example: spinner.setup({..., text: { "direction": {top: "41%"} } });
-
{String}
value
- Component's text element's value (internally set viaHTMLElement.textContent
)
-
NOTE: If during setup
text.value
is set, it is used as component's text, otherwise text set via attribute on the component will be used
Examples:
<spinner-component id="top-spinner"></spinner-component>
// Examples:
// get element
var topSpinner = document.getElementById("top-spinner");
// setup - without setting `text.value`
topSpinner.setup({size: 0.35, color: "cornflowerblue", text: {color: "firebrick"}});
//setup - setting `text.value` explicitly
topSpinner.setup({
size: 2.5,
color: "yellow",
direction: {
top: "2rem"
},
text: {
color: "firebrick",
value: "50% percents"
}
});
// setup - setting parent container
const parentElement = document.getElementById("container");
topSpinner.setup({
parentContainer: parentElement
color: "yellow",
text: {
color: "green",
value: "loading data"
}
});
Reveals component.
Also the following actions will be made:
show
event will be fired
aria-busy
will be set to true
on the component's parent container (see aria-busy
for more info)
isShown
property of the component will be changed
Example:
const spinner = document.getElementById("spinner");
spinner.show();
Hides component.
Also the following actions will be made:
hide
event will be fired
aria-busy
will be removed from the component's parent container (see aria-busy
for more info)
isShown
property of the component will be changed
Example:
const spinner = document.getElementById("spinner");
spinner.hide();
You can customize component, by setting your css on the component itself and by using CSS custom properties (a.k.a CSS variables).
NOTE: component's dimension properties mainly defined in em
unit (this unit is relative to the font-size
property that defined on the element itself or on the parent element), thus, you can change its dimensions by setting font-size
on the component itself or on the parent element.
// default values
spinner-component {
--hue: 0;
--lightness: 100%;
--saturation: 46%;
--alpha: 0;
--box-shadow-hue: var(--hue);
--box-shadow-lightness: var(--lightness);
--box-shadow-saturation: 18%;
--box-shadow-alpha: var(--alpha);
--box-shadow-x: 0px;
--box-shadow-y: 0px;
--box-shadow-blur: 3px;
--box-shadow-spread: 0px;
--spinner--color: hsla(var(--hue), var(--lightness), var(--saturation), var(--alpha));
--spinner--size: 1rem;
--spinner--backdrop: rgba(0, 0, 0, 0);
--spinner--box-shadow: var(--box-shadow-x) var(--box-shadow-y) var(--box-shadow-blur) var(--box-shadow-spread) hsla(var(--box-shadow-hue), var(--box-shadow-lightness), var(--box-shadow-saturation), var(--box-shadow-alpha));
--spinner--text-color: var(--spinner--color);
--spinner--text-size: var(--spinner--size);
--spinner--direction-left: 50%;
--spinner--direction-top: 50%;
--spinner-text-direction-left: 0;
--spinner-text-direction-top: 0;
}
The following properties can be used to customize the component:
Sets hue for component's color
/box-shadow
properties. [default value: 0]
Sets lightness for component's color
/box-shadow
properties. [default value: 100%]
Sets saturation for component's color
/box-shadow
properties. [default value: 46%]
Sets alpha for component's color
/box-shadow
properties. [default value: 0]
Sets hue for component's box-shadow
property's color which is set via hsla
. [default value: var(--hue)
]
Sets lightness for component's box-shadow
property's color which is set via hsla
. [default value: var(--lightness)
]
Sets saturation for component's box-shadow
property's color which is set via hsla
. [default value: 18%]
Sets alpha for component's box-shadow
property's color which is set via hsla
. [default value: var(--alpha)
]
Sets x-offset for component's box-shadow
property. [default value: 0]
Sets y-offset for component's box-shadow
property. [default value: 0]
Sets blur for component's box-shadow
property. [default value: 3px]
Sets spread for component's box-shadow
property. [default value: 0]
Sets component's box-shadow
. [default value: var(--box-shadow-x) var(--box-shadow-y) var(--box-shadow-blur) var(--box-shadow-spread) hsla(var(--box-shadow-hue), var(--box-shadow-lightness), var(--box-shadow-saturation), var(--box-shadow-alpha))
]
Sets component's color
property. [default value: hsla(var(--hue), var(--lightness), var(--saturation), var(--alpha))
if none of the custom properties are set, contaning block's color
proerty value will be used]
Sets component's size. [default value: 1rem]
Sets component's text color
. [default value: var(--spinner--color)
]
Sets component's backdrop which is displayed beneath the component when visible. [default value: rgba(0, 0, 0, 0)
]
Sets component's text size. [default value: var(--spinner--size)
]
Sets component's direction left
. [default value: 50%]
Sets component's direction top
. [default value: 50%]
Sets component's text direction left
. [default value: 0]
Sets component's text direction top
. [default value: 0]