Web Components

Introduced by Alex Rusell at the Fronteers Conference in 2011, Web Components have since gained traction among web developers to create encapsulated and reusable elements for the web.

They look like that:

<my-component name="Dennis"/>

As you can see, it's not much different than your normal HTML element like a div or li. Since web components are built with Javascript, they are executed on the client side, so when visited in a browser. A custom component could be programmed in any way, depending on it's purpose.

For example, the goal could be to create a card component that displays the 'name' attribute once executed:

							
							<my-card name="Dennis">
								<div class="card-wrap">
									<h1 class="card-title">Dennis</h1>
								</div>
							</my-card>
							
						

Components behave like normal HTML elements, so you can target them by using CSS:

							
							my-card {
								background: white;
								padding: 1em;
								border-radius: 0.125em;
							}
							
						

That's it for the most part, let's dive deeper into how spx is utilizing the power of web components. 🦾

Attributes

All settings for spx components are applied using attributes. These are no different to attributes for standard HTML elements.

							
							<spx-masonry
									columns="4"
									bp-columns="1000:2,600:1"
									gap="2%">
								<img src="img.jpg"/>
								<img src="img2.jpg"/>
								<img src="img3.jpg"/>
								...
							</spx-masonry>
							
						

The above code would output a masonry layout of images that spans 4 columns, with a gap of 2% between the images. The number of columns will reduce to 2 when the screen size is under 1000px and to 1 when under 600px.

Every component has different possible attributes that can be applied. Please head to the individual components to find out more.

CSS variables

Components which are not purely functional can also be styled using CSS variables. Here, the variable names correlate with their attribute counterpart like this:

							
							:root {
								--spx-masonry-gap: 10px;
							}
							
						

This would create a gap of 10px between all images of all existing masonry components on the site. If you want to target a specific instance, you could give an ID or class to the component:

							
							<spx-masonry
									id="my-masonry">
								<img src="img.jpg"/>
								<img src="img2.jpg"/>
								<img src="img3.jpg"/>
								...
							</spx-masonry>
							
						
							
							#my-masonry {
								--spx-masonry-gap: 1em;
							}
							
						

Helper functions

While many of the components will work without WordPress, the true, time-saving power of spx comes from using it in conjunction with the provided PHP helper functions. At the moment, helper functions exist for the masonry and navigation component. In fact, the navigation component only works using the helper function.

							
								<?php $images = spx\get::acfGallery("myGallery") ?>
							
						
							
							<spx-masonry images="<?php echo $images ?>"/>
							
						

This will automatically create a masonry layout from the ACF gallery! We are hard at work to add more helper function for other frameworks like Metabox.

Slots

Some components have certain slots that can be filled with custom markup. For example, the accordion can be filled with custom slots for the header and content.

							
							<spx-accordion>
								<div slot="header">Click me to unveil the content</div>
								<img slot="content" src="image.jpg"/>
							</spx-accordion>
							
						

Events

Javascript events are being emitted by a couple of components. You can attach an event listener to those just like you normally would.

							
                            document.addEventListener('spxEditButtonSave', function() {
                                // your functions
                            }
							
						

Methods

Components might expose public methods in Javascript:

							
                            (async () => {
                                await customElements.whenDefined('spx-typewriter');
                                const sT = document.querySelector('spx-typewriter');
                                await sT.play();
                            })();
							
						

The above code would start the animation of the typewriter component. Methods come in handy when trying to interact with other libraries or your own functions.

Accordion


			                <spx-accordion/>

The classic method to show and hide elements.

Attributes

gap

string
🎨CSS variable: --spx-accordion-gap
🌎Default: 0.4em
Gap between header and content. Accepts any valid value for this CSS property.

font-size

string
🎨CSS variable: --spx-accordion-font-size
🌎Default: 16px
Font size. Accepts any valid value for this CSS property.

header-color

string
🎨CSS variable: --spx-accordion-header-color
🌎Default: #212121
Header color. Accepts any valid value for this CSS property.

header-text

string
🌎Default: Default Header Text
Text for the header.

header-text-tag

string
🌎Default: span
HTML tag for the header text.

header-gap

string
🎨CSS variable: --spx-accordion-header-gap
🌎Default: 0.4em
Gap between icon and header text. Accepts any valid value for this CSS property.

indicator-icon

string
Indicator icon. Accepts any Font Awesome icon class.

content-color

string
🎨CSS variable: --spx-accordion-content-color
🌎Default: #212121
Content color. Accepts any valid value for this CSS property.

content-text

string
🌎Default: Default Content Text
Text for the content.

content-text-tag

string
🌎Default: span
HTML tag for the content text.

Slots

header

Replaces the header.

content

Replaces the content.

Animate


			                <spx-animate/>

A component that allows for staggered and scroll based animations.

Attributes

position

string
🎨CSS variable: --spx-animate-display
🌎Default: block
CSS display property for component.

target

string
🌎Default: *
The target element that should be animated inside the component.

duration

number
🌎Default: 1
Length of the animation.

opacity

number
🌎Default: 1
Opacity level the animation starts from.

x

string
🌎Default: 0
X position the animation starts from.

y

string
🌎Default: 0
Y position the animation starts from.

delay

number
🌎Default: 0
Amount of delay before the animation starts.

stagger

number
🌎Default: 0.15
Amount of time elements should be staggered by.

ease

string
🌎Default: power1.out
βš–οΈ Choices:  power1.in, power1.inOut, power1.out, power2.in, power2.inOut, power2.out, power3.in, power3.inOut, power3.out, power4.in, power4.inOut, power4.out, back.in, back.inOut, back.out, elastic.in, elastic.inOut, elastic.out, bouncein, bounce.inOut, bounce.out, steps.in, steps.inOut, steps.out, sine.in, sine.inOut, sine.out, none
Type of easing which should be applied.

viewport

boolean
🌎Default: false
Starts animation when target is in viewport.

once

boolean
🌎Default: false
Works in correlation with viewport and dictates if animation should only be run once.

Class Toggle


			                <spx-class-toggle/>

An easy way to toggle CSS classes on any element in the document.

Attributes

position

string
🎨CSS variable: --spx-class-toggle-display
🌎Default: block
CSS display property for component.

toggle

string
🌎Default: spx-class-toggle--active
List of classes that should be toggled.

target

string
Target element. Can take any querySelector value. (id, class, tag etc.) If none is set it will default to the first element inside.

local

string
Specify a local storage item, so toggle state will be remembered when the user visits the site again. Click the button above and refresh the page for an example.

Edit Button


			                <spx-edit-button/>

Let your clients edit text on their site using this handy component. Updates are being sent via AJAX, making this a solution that works completely on the front-end without reload.

At the moment, only text fields that are coming from Advanced Custom Fields and wp_options can be updated. We are working hard to support more frameworks and options in the future.

To enable front-end editing, just add the spx-edit-button component to a page. After that, you have to mark all elements that you want to be editable on the site. This is being done by adding the data-spx-edit attribute to existing text elements:

							
							<h1 data-spx-edit="myTextField" type="acf">
								Some text that you want to be editable.
							</h1>
							
		

The wp_options or ACF field name has to be the value of the attribute. After that, you're good to go! Of course, it makes sense to only show to logged in users, so you can wrap it in a condition of your choice.

Please note: to reduce server load, all data is being collected before being sent off. This way, only one AJAX request is needed, even when 100 fields are being updated at the same time. This has the disadvantage that it currently isn't possible to edit different types of fields with one button. For example, you can't mix wp_options and ACF fields since they need a different function to update the data in the request.

However, it is possible to have multiple spx-edit-button on the page, each having different targets:

			
<h1 data-spx-edit="myTextField" data-spx-edit-id="my-acf-fields">
    Some ACF field that you want to be editable.
</h1>
<spx-edit-button edit-id="my-acf-fields" type="acf"/>

<h1 data-spx-edit="blogdescription" data-spx-edit-id="my-option-fields">
    The blog tagline.
</h1>
<spx-edit-button edit-id="my-option-fields" type="option"/>
			
		

Attributes

type

string
🌎Default: option
βš–οΈ Choices:  option, acf
Which data type should be updated. Choice between ACF fields and wp_options.

text-edit

string
🌎Default: Edit site
Edit button text.

text-save

string
🌎Default: Save
Save button text.

text-discard

string
🌎Default: Discard
Discard button text.

text-success

string
🌎Default: Save was successful
Success message that gets displayed after saving.

position

string
🎨CSS variable: edit-button
🌎Default: bottom-right
βš–οΈ Choices:  bottom-left, bottom-center, bottom-right, top-left, top-center, top-right
Position of the component.

distance-x

string
🎨CSS variable: --spx-edit-button-position-x
🌎Default: 1em
Distance between component and end of the screen on the x-axis. Accepts any valid value for this CSS property.

distance-y

string
🎨CSS variable: --spx-edit-button-position-y
🌎Default: 1em
Distance between component and end of the screen on the y-axis. Accepts any valid value for this CSS property.

font-size

string
🎨CSS variable: --spx-edit-button-font-size
🌎Default: 16px
Font size. Accepts any valid value for this CSS property.

padding

string
🎨CSS variable: --spx-edit-button-padding
🌎Default: 0.8em 1.2em
Padding. Accepts any valid value for this CSS property.

color

string
🎨CSS variable: --spx-edit-button-color
🌎Default: #ffffff
Color. Accepts any valid value for this CSS property.

color-discard

string
🎨CSS variable: --spx-edit-button-color-discard
🌎Default: #ffffff
Color for discard button. Accepts any valid value for this CSS property.

background

string
🎨CSS variable: --spx-edit-button-background
🌎Default: #212121
Background. Accepts any valid value for this CSS property.

background-discard

string
🎨CSS variable: --spx-edit-button-background-discard
🌎Default: #757575
Background for discard button. Accepts any valid value for this CSS property.

border

string
🎨CSS variable: --spx-edit-button-border
Border. Accepts any valid value for this CSS property.

border-radius

string
🎨CSS variable: --spx-edit-button-border-radius
🌎Default: 0.25em
Border radius. Accepts any valid value for this CSS property.

gap

string
🎨CSS variable: --spx-edit-button-gap
🌎Default: 0.4em
Gap between the two buttons. Accepts any valid value for this CSS property.

Events

spxEditButtonSave

Emits when pressing the save button.

spxEditButtonSave

Emits when pressing the discard button.

Iframe


			                <spx-iframe/>

A wrapper around a normal iframe element, which scales proportionally to its parent. Great for showing desktop versions of a website in a small section.

Attributes

src

string
Src of the iframe.

width

string
Screen size of the site shown inside the iframe.

Image comparison


			                <spx-image-comparison/>

Compare two images visually using a slider. Handy for showing subtle (or not so subtle) before/after differences.

Attributes

src-before

string
Image URL of the before image.

src-after

string
Image URL of the after image.

start

number
Opening state in px.

color

string
🎨CSS variable: --spx-image-comparison-color
🌎Default: #ffffff
Color of the handle. Accepts any valid value for this CSS property.

icon-color

string
🎨CSS variable: --spx-image-comparison-icon-color
🌎Default: #9E9E9E
Color of the icon inside the handle. Accepts any valid value for this CSS property.

Group


			                <spx-group/>

This is a functional element that is used to pass attributes to all inner child components.

Attributes

g-*

all
All attributes that start with g-* will be passed on to child elements. For example, to change all icons for a group of accordions, the data attribute would look like that:
g-icon-indicator='far fa-arrow-down'

Masonry


			                <spx-masonry/>

Arranges images in a masonry layout.

It is possible to nest the masonry component inside a lightbox to create an overlay gallery for all images.

Attributes

images

helper function

                <?php spx\get::gallery($fieldName, $type) ?>
Gets images from an ACF or Metabox field. $type can be either 'acf' (Advanced Custom Fields) or 'mb' (Metabox).

image-size

string
WordPress media size when using the helper function.

columns

number
Number of columns.

bp-columns

string
Columns for different screen sizes.
Example value: 1000:3;600:2 - this will switch to a three column layout when the screen size is under 1000px and to a two column layout under 600px.

gap

string
🎨CSS variable: --spx-masonry-gap
🌎Default: 10px
Gap between images.

Mockup


			                <spx-mockup/>

Easy device mockups around your content.

Attributes

position

string
🎨CSS variable: --spx-mockup-display
🌎Default: block
CSS display property for component.

type

string
🌎Default: iphone-8
βš–οΈ Choices:  iphone-x, iphone-8, google-pixel-2-xl, google-pixel, galaxy-s8, ipad-pro, surface-pro, surface-book, macbook, macbook-pro, surface-studio, imac-pro, apple-watch
Device type.

src

string
Image src if no inner slot is used.

image-position

string
🌎Default: 50% 50%
Image position.

color-iphone-8

string
🌎Default: silver
βš–οΈ Choices:  silver, gold, spacegray
iPhone 8 color.

color-google-pixel

string
🌎Default: silver,
βš–οΈ Choices:  silver, black, blue
Google Pixel color.

color-galaxy-s8

string
🌎Default: black
βš–οΈ Choices:  black, blue
Samsung S8 color.

color-ipad-pro

string
🌎Default: silver
βš–οΈ Choices:  silver, gold, rosegold, spacegray
iPad Pro color.

color-macbook

string
🌎Default: silver
βš–οΈ Choices:  silver, gold, rosegold, spacegray
Macbook color.

color-macbook-pro

string
🌎Default: silver
βš–οΈ Choices:  silver, spacegray
Macbook Pro color.

Offset


			                <spx-offset/>

Offsets itself to the height of a specified element. The component comes in handy when dealing with a fixed header and is used on this site. Simply wrap your main content container with it and select a target element. The distance will adjust on screen resize. Besides applying a margin to the top, the distance will also be updated in a CSS variable. (see below)

Attributes

position

string
🎨CSS variable: --spx-offset-display
🌎Default: block
CSS display property for component.

target

string
🎨CSS variable: --spx-offset
🌎Default: header
Target element. Can take any querySelector value. (id, class, tag etc.)

Scrollspy


			                <spx-scrollspy/>

Automatically add CSS classes to navigation items and content elements depending on the scroll position. You can see it in action on the left of this page! (on desktop)

To make this component work correctly, the href attributes of the links hav to correlate with the IDs of the sections and links must be wrapped with a li tag:

							
                            <ul>
                                <li><a href="#section1">Section 1</a></li>
                                <li><a href="#section2">Section 2</a></li>
                            </ul>
                            <div id="section1"><div>
                            <div id="section2"><div>
							
						

Attributes

position

string
🎨CSS variable: --spx-scrollspy-display
🌎Default: block
CSS display property for component.

target

string
🌎Default: a
Target element. Can take any querySelector value. (id, class, tag etc.)

nav-class

string
🌎Default: spx-scrollspy__item--active
Class that will be applied to active navigation element.

content-class

string
🌎Default: spx-scrollspy__content--active
Class that will be applied to active content element.

offset

string or number
🌎Default: header
Selects the height of an element (any querySelector value) or number that is used for offsetting how far from the top the next section is activated.

url-change

boolean
Appends the current hash link to the end of the URL.

Share


			                <spx-share/>

Social share buttons. Currently includes Facebook, Twitter, Whatsapp and E-Mail.

Attributes

theme

string
Theme for the buttons. Choice of 'outline' and 'minimal'.

vertical

boolean
Renders the component vertically.

target

string
🌎Default: _blank
Link target.

font-size

string
🎨CSS variable: --spx-share-font-size
🌎Default: 16px
Font size. Accepts any valid value for this CSS property.

item-gap

string
🎨CSS variable: --spx-share-item-gap
🌎Default: 0.5em
Gap between buttons. Accepts any valid value for this CSS property.

item-size

string
🎨CSS variable: --spx-share-item-size
🌎Default: 1em
Item size. Accepts any valid value for this CSS property.

item-color

string
🎨CSS variable: --spx-share-item-color
🌎Default: #ffffff
Item color. Accepts any valid value for this CSS property.

item-background

string
🎨CSS variable: --spx-share-item-background
🌎Default: #202020
Item background. Accepts any valid value for this CSS property.

item-padding

string
🎨CSS variable: --spx-share-item-padding
🌎Default: 0.5em
Item padding. Accepts any valid value for this CSS property.

item-border-radius

string
🎨CSS variable: --spx-share-item-border-radius
🌎Default: 0.25em
Item border radius. Accepts any valid value for this CSS property.

Snackbar


			                <spx-snackbar/>

Notification bars with a variety of options. Great for success or failure messages. In default mode, the bar will fade out and remove itself from the DOM. Click the clipboard button to see it in action.

You have probably seen and used Snackbars all over the internet. As success, error or information bars. Creating a Snackbar with the Oxygen element is easy, simply wrap the element you wish to trigger the Snackbar with and it's good to go!

Attributes

text

string
🌎Default: Hello, I'm a snackbar.
Text inside of snackbar.

fixed

boolean
When true, Snackbar won't fade out after fading in.

closeable

boolean
Adds a closing button.

reverse

boolean
Reverses the closing button.

position

string
🎨CSS variable: snackbar
🌎Default: bottom-right
βš–οΈ Choices:  bottom-left, bottom-center, bottom-right, top-left, top-center, top-right
Position of the component.

distance-x

string
🎨CSS variable: --spx-snackbar-position-x
🌎Default: 1em
Distance between component and end of the screen on the x-axis. Accepts any valid value for this CSS property.

distance-y

string
🎨CSS variable: --spx-snackbar-position-y
🌎Default: 1em
Distance between component and end of the screen on the y-axis. Accepts any valid value for this CSS property.

font-size

string
🎨CSS variable: --spx-snackbar-font-size
🌎Default: 18px
Font size. Accepts any valid value for this CSS property.

size

string
βš–οΈ Choices:  sm, md, lg
Component size. If set, font-size and padding are ignored.

padding

string
🎨CSS variable: --spx-snackbar-padding
🌎Default: 1em
Padding. Accepts any valid value for this CSS property.

color

string
🎨CSS variable: --spx-snackbar-color
🌎Default: #ffffff
Color. Accepts any valid value for this CSS property.

background

string
🎨CSS variable: --spx-snackbar-background
🌎Default: #212121
Background. Accepts any valid value for this CSS property.

border

string
🎨CSS variable: --spx-snackbar-border
Border. Accepts any valid value for this CSS property.

border-radius

string
🎨CSS variable: --spx-snackbar-border-radius
🌎Default: 0.25em
Border radius. Accepts any valid value for this CSS property.

animation-delay

string
🎨CSS variable: --spx-snackbar-animation-delay
🌎Default: 200ms
Time before the fade-in animation starts. Accepts any valid value for this CSS property.

animation-duration

string
🎨CSS variable: --spx-snackbar-animation-duration
🌎Default: 2s
Duration of the complete animation. Accepts any valid value for this CSS property.

Typewriter


			                <spx-typewriter/>

Animates text like it is being written on a typewriter.

The classic reveal. This component needs an inner text element (heading or text) to work. Please note that the text is being taken from the field in the settings, as the inner content of the text element is being ignored here.

Attributes

text

string
🌎Default: I'm a typewriter.
Text to be typed.

delay

any
🌎Default: natural
The delay between each key when typing. Can be 'natural' or any number.

delete-speed

any
🌎Default: natural
The delay between deleting each character. Can be 'natural' or any number.

loop

boolean
Whether to keep looping or not.

auto-start

boolean
Whether to autostart typing strings or not.

inner

boolean
If true, component will look for a heading, span or p element to render text in.

Methods

play

Starts the animation.

stop

Stops the animation.
asd.kjaasdkjhalshdlagsdlaghsslgdliuas asd.kjaasdkjhalshdlagsdlaghsslgdliuas asd.kjaasdkjhalshdlagsdlaghsslgdliuas asd.kjaasdkjhalshdlagsdlaghsslgdliuas asd.kjaasdkjhalshdlagsdlaghsslgdliuas asd.kjaasdkjhalshdlagsdlaghsslgdliuas
Stay in
the loop!