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:
As you can see, it's not much different than your standard HTML elements 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 its purpose.
For example, the goal could be to create a card component that displays the 'name' attribute once executed:
Components behave like standard HTML elements, so you can target them by using CSS:
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.
The above code would output a masonry layout of images that spans four columns, with a gap of 2% between 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. The variable names correlate with their attribute counterpart like this:
That 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:
While it is technically possible to style the components directly and without CSS variables, it is not recommended. Since all CSS is generated dynamically, random classes are being applied by the CSS-in-JS engine (spx is using Emotion). These classes change depending on the applied attributes. CSS variables are also future-proof in case components will be switched over to use the new Shadow DOM API.
On top of that, some component attributes apply the same value to many different properties for the element to function correctly, making styling without CSS variables not a viable option.
Tokens
Besides variables for all individual components, some general design tokens that affect all components.
Please note that all builder elements use a different system for the font-family and font-size and are thus not altered by the above values.
Responsive design
Creating responsive designs using spx components is straight forward and possible in two different ways. Let's change the font-size of our navigation element for desktop screen sizes.
Using CSS variables is preferred, however, it is also possible to style elements responsively using attributes.
This will have the same result as styling the component with the CSS code from above but instead relies on the ResizeObserver interface to apply the appropriate values. Of course, it is possible to create various breakpoints and add multiple attributes.
Helpers
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. The navigation component only works using the helper function.
This will automatically create a masonry layout from the ACF gallery!
Available helpers:
Helpers are also available as non class-based functions:
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.
Events
Javascript events are being emitted by a couple of components. You can attach an event listener to those just like you normally would.
Methods
Components might expose public methods in Javascript:
The above code would start the animation of the typewriter component. Methods come in handy when trying to interact with other libraries and functions.
Oxygen
Before version 2.0, components were integrated inside of Oxygen as separate elements.
2.0 is changing that behaviour. Instead of individual elements, there now is a master element, which can become any of the core components. This has various advantages for the development team behind spx, since it isn't necessary to implement every component and property again.
Instead, the wrapper now correlates with the core JavaScript components, meaning that every new element and property is immediately available to be used inside Oxygen. Settings can be applied using the "Attributes" text box just like outside of Oxygen. The single components are still available in 2.0, but will be removed with version 3.0. It is advised to use the wrapper element from now on.
Of course, it is still possible to use spx elements inside code blocks.
Accordion
Accordions are the classic method to show and hide elements on your website.
Properties
content-color
Content color.
content-text
Content text.
content-text-tag
Content text tag.
content-transition-duration
Content transition-duration.
content-transition-timing-function
Content transition-timing-function.
font-size
Component font-size property.
gap
Space between header and content.
header-color
Header color.
header-gap
Gap between header text and icon.
header-text
Header text.
header-text-tag
Header text tag.
indicator-icon
Indicator icon.
indicator-icon-transform
Indicator icon transform.
indicator-icon-type
Indicator icon type.
Slots
content
Content.
header
Header.
icon
Icon.
Methods
reload
Reload component.
Animate
Wrapper around GSAP that allows for staggered and scroll-based animation.
Properties
delay
Delay before animation starts.
display
Component display property.
duration
Animation duration.
ease
Ease being used. Accepts all common GSAP options.
once
Determines if animation should only play once. (if viewport is true)
opacity
Opacity level the animation starts from.
repeat
Repeats the animation. -1 to repeat indefinitely.
repeat-delay
Time to wait between repetitions.
reverse
Reverses the animation.
stagger
Amount of time elements should be staggered by.
target
The target element that should be animated inside the component.
viewport
Starts animation when target is in the viewport.
viewport-margin-bottom
Adjust the root margin of the animation start.
viewport-margin-left
Adjust the root margin of the animation start.
viewport-margin-right
Adjust the root margin of the animation start.
viewport-margin-top
Adjust the root margin of the animation start.
x
X position the animation starts from.
y
Y position the animation starts from.
yoyo
Causes the animation to go back and forth, alternating backward and forward on each repeat.
Methods
play
Plays animation.
reload
Reload component.
restart
Restarts animation.
Class Toggle
Toggle CSS classes on any element in the document.
Properties
display
Component display property.
local
Specify a local storage item, so the toggle state will be remembered when the user visits the site again.
target
Target element. Can take any querySelector value. (id, class, tag etc.) If none is set it will default to the first element inside.
toggle
List of classes that should be toggled.
Methods
reload
Reload component.
Code
Highlight a block of code similar to a code editor.
Properties
background
Component background property.
border-radius
Component border-radius property.
display
Component display property.
font-size
Component font-size property.
height
hide-scrollbar
Hide scrollbar.
overflow
padding
Component padding property.
theme
Colour theme.
type
Determines the programming language.
Methods
reload
Reload component.
Edit Button
Let your clients edit text on their site using this handy component.
There is a guide available for this component.
Properties
background
Component background property.
background-discard
Discard button background.
border
Component border property.
border-radius
Component border-radius property.
color
Component color property.
color-discard
Discard button color.
distance-x
Distance to the edge of the viewport on the x-axis.
distance-y
Distance to the edge of the viewport on the y-axis.
edit-id
Corresponding ID for editable fields. This property is needed when multiple edit-button components are used on the page. Simply apply a "data-spx-edit-id" attribute with the same value to editable elements.
font-family
Component font-family property.
font-size
Component font-size property.
gap
Gap between the buttons.
padding
Component padding property.
position
Component position in page.
position-css
CSS property position of button.
test
text-discard
Discard button text.
text-edit
Edit button text.
text-save
Save button text.
text-success
Success message.
z-index
Component z-index property.
Events
spxEditButtonDiscard
Fires after pressing the discard button.
spxEditButtonSave
Fires after pressing the save button.
Methods
reload
Reload component.
Group
Pass attributes to all inner (spx) child elements. 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'
Properties
display
Component display property.
target
Specifies a target element.
Methods
reload
Reload component.
Icon
Wrapper component for different kinds of icon sets. Currently comes included with Ionicons.
Properties
color
Component color property.
icon
Icon code.
size
Icon size.
type
Icon type.
Iframe
A wrapper around a standard iframe element, which scales proportionally to its parent. Great for showing desktop versions of a website on smaller screens or viewports.
Properties
size
Screen size of the site shown inside the iframe.
src
Source for the iframe.
Methods
reload
Reload component.
Image Comparison
Compare two images visually using a slider. Handy for showing subtle (or not so subtle) before/after differences.
Properties
color
Component color property.
icon-color
Icon color.
src-after
Image URL of the before image.
src-before
Image URL of the after image.
start
Opening state in pixels.
Methods
reload
Reload component.
Lightbox
Overlay a gallery of images on top of the current page.
Properties
display
Component display property.
height
overlay-color
Overlay color.
width
Methods
reload
Reload component.
Masonry
Arrange images in a masonry layout.
Properties
bp-columns
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.
columns
Number of columns.
gap
Gap between images.
image-size
WordPress media size when using the helper function..
images
Gets images from an ACF or Metabox field.
images-src
Gets images from an ACF or Metabox field.
Events
spxMasonryDidLoad
Methods
recalc
Recalculate grid.
reload
Reload component.
Mockup
Display device mockups around your content.
Properties
color-galaxy-s8
Samsung S8 color.
color-google-pixel
Google Pixel color.
color-ipad-pro
iPad Pro color.
color-iphone8
iPhone 8 color.
color-macbook
MacBook color.
color-macbook-pro
MacBook Pro color.
display
Component display property.
image-position
Component image-position property.
src
Image src if no inner slot is used.
type
Device type.
Methods
reload
Reload component.
Navigation
Render a complete WordPress menu with nested submenus and automatic positioning.
Properties
child-border
Child border.
child-border-radius
Child menu border-radius.
child-box-shadow
Child menu box-shadow.
child-child-gap
Gap between nested child menus.
child-gap
Gap between top level menu items and child menus.
child-icon
Indicator icon..
child-icon-type
Indicator icon type.
child-indicator-gap
Gap between child menu indicator and text.
child-item-background
Child item background.
child-item-background-hover
Child item hover background.
child-item-color
Child item color.
child-item-color-hover
Child item hover color.
child-item-padding
Child item padding.
child-placement
Child menu placement.
font-size
Component font-size property.
item-transition-duration
Item transition-duration.
item-transition-timing-function
Item transition-timing-function.
item-underline
Underlines all links.
item-underline-hover
Underlines all links on hover.
menu
Renders a WordPress menu.
mobile
Mobile breakpoint.
mobile-icon
Mobile button icon.
mobile-icon-type
Mobile button icon type.
mobile-item-background
Mobile item background.
mobile-item-background-hover
Mobile item hover background.
mobile-item-color
Mobile item color.
mobile-item-color-hover
Mobile item hover color.
mobile-item-nested-margin-left
Mobile item nested margin-left.
mobile-item-padding
Mobile item padding.
mobile-placement
Mobile placement.
parent-item-background
Parent item background.
parent-item-background-hover
Parent item hover background.
parent-item-color
Parent item color.
parent-item-color-hover
Parent item hover color.
parent-item-gap
Gap between parent menu items.
parent-item-padding
Parent item padding.
vertical
Renders menu vertically.
Events
spxNavigationDidLoad
Fires when component has loaded.
Methods
reload
Reload component.
Notation
Annotate letters, words or whole sentences.
Properties
animation
Turn animation on or off when animation.
animation-duration
Animation duration.
color
Component color property.
display
Component display property.
iterations
Number of iterations.
multiline
Annotate multiline text.
stroke-width
Stroke width.
type
Type of notation.
Methods
clear
Remove the annotation.
hide
Hides the annotation. (non animated)
reload
Reload component.
show
Draws the annotation.
Offset
The component offsets itself to the height of a specified element. It 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.
Properties
display
Component display property.
target
Target element.
Methods
reload
Reload component.
Scrollspy
Automatically add CSS classes to navigation items and content elements depending on the scroll position.
Properties
content-class
Applied class to active content element.
display
Component display property.
nav-class
Applied class to active navigation element.
offset
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.
scrolling
Automatically scroll to the active element
scrolling-offset
Scrolling offset from the top.
target
Target element. Can take any querySelector value. (id, class, tag etc.)
url-change
Appends the currently active link to the end of the URL.
Events
spxScrollspyDidLoad
Methods
reload
Reload component.
Share
Social share buttons. Currently includes Facebook, Twitter, Whatsapp and E-Mail.
Properties
font-size
Component font-size property.
item-background
Item background.
item-border-radius
Item radius border.
item-color
Gap between buttons.
item-filter-hover
Filter hover.
item-gap
Gap between buttons.
item-padding
Item padding.
item-size
item-transition-duration
Item transition-duration.
item-transition-timing-function
Item transition-timing-function.
target
Button href target.
theme
Button theme.
vertical
Render buttons vertically.
Methods
reload
Reload component.
Slider
A slider is a revolving carousel that displays photos or other types of content.
Properties
autoheight
Automatically adjusts height of slider.
autoplay
Starts navigating to the next slide when page is loaded.
autoplay-delay
Autoplay delay.
autoplay-disable-on-interaction
Disable autoplay after interaction with slides.
bp-tabs
Starts navigating to the next slide when page is loaded.
centered-slides
Centers slides in viewport.
direction
Slider direction.
effect
Slider effect.
image-object-fit
Image object-fit.
image-size
WordPress media size when using the helper function..
images
Gets images from an ACF or Metabox field.
images-src
Gets images from an ACF or Metabox field.
loop
Loops all slides infinitely.
max-height
Max height.
max-width
Max width.
navigation
navigation-background
Navigation background.
navigation-border-radius
Navigation radius border.
navigation-color
Navigation color.
navigation-distance-x
Navigation distance.
navigation-icon-next
Navigation icon type.
navigation-icon-prev
Navigation icon type.
navigation-icon-type
Navigation icon type.
navigation-padding
Navigation padding.
navigation-size
Navigation size.
pagination
Pagination type.
pagination-bullets-background
Pagination bullets background.
pagination-bullets-background-active
Pagination bullets active background.
pagination-bullets-clickable
Make bullets clickable.
pagination-bullets-dynamic
Will only keep a selected amount of bullets visible.
pagination-bullets-dynamic-amount
Amount of dynamic bullets.
pagination-bullets-size
Size of the bullets.
pagination-bullets-space-between
Space between the bullets.
pagination-tabs-max-width
Pagination tabs max-width.
pagination-transition-duration
Pagination transition-duration.
pagination-transition-timing-function
Pagination transition-timing-function.
prev-next-filter
Filter property for the previous and next elements.
slide-message-first
Screen reader message for first slide.
slide-message-last
Screen reader message for last slide.
slide-message-next
Screen reader message for next slide.
slide-message-previous
Screen reader message for previous slide.
slides-per-view
Amount of slides shown at once.
space-between
Space between slides.
speed
Sliding speed.
Methods
reload
Reload component.
Slideshow
Continuously playing slideshow.
Properties
duration
Duration of slideshow to complete one cycle.
gap
Gap between inner elements.
image-size
WordPress media size when using the helper function..
images
Gets images from an ACF or Metabox field.
images-src
Gets images from an ACF or Metabox field.
max-width
Max width of inner elements.
Snackbar
Notification bars with a variety of options. Great for success or failure messages. In default mode, the snackbar will fade out and remove itself from the DOM.
Properties
animation-delay
Component animation-delay property.
animation-duration
Component animation-duration property.
background
Component background property.
border
Component border property.
border-radius
Component border-radius property.
closeable
Adds option to close snackbar after its creation.
color
Component color property.
distance-x
Distance to the edge of the viewport on the x-axis.
distance-y
Distance to the edge of the viewport on the y-axis.
fixed
Makes snackbar not removable.
font-size
Component font-size property.
identifier
Unique identifier for snackbar instance.
padding
Component padding property.
position
Component position in page.
position-css
CSS property position of button.
reverse
Reverses the close button if "closable" prop is true.
space-between
Space between snackbars.
target
Element where snackbars should be created in.
text
Text inside snackbar.
z-index
Component z-index property.
Methods
reload
Reload component.
Text
This component styles text coming from a markdown file or a rich-text editor appropriately. It will eventually be 100% compatible with the Gutenberg editor as well.
Properties
content-font-size-multiplier
Only works if text-type is set to 'multiply'.
heading-color
Heading color.
heading-font-family
Heading font-family.
heading-font-weight
Heading font-weight.
heading-letter-spacing
Heading letter-spacing.
heading-line-height
Heading line-height.
heading-text-transform
Heading text-transform.
link-decoration-color
Link decoration color.
markdown
Parse markdown.
max-width
Component max-width property.
text-color
Text color.
text-font-family
Text font-family.
text-font-weight
Text font-weight.
text-letter-spacing
Text letter-spacing.
text-line-height
Text line-height.
text-max-w
Maximum viewport width when text-type is set to linear.
text-min-w
Minimum viewport width when text-type is set to linear.
text-text-transform
Text text-transform.
text-type
Typewriter
Animates text like it is being written on a typewriter.
Properties
auto-start
Automatically starts writing.
delay
Writing delay in ms. Also accepts 'natural' value.
delete-speed
Delete delay in ms. Also accepts 'natural' value.
display
Component display property.
loop
Loops the animation.
text
Text that should be written.
Methods
play
Start animation.
stop
Stop animation.
Introduction
A new feature of version 2.0 is the page builder. It is a collection of components to create responsive, full-page layouts. All of the following elements are part of an evolving system that is supposed to ease the way modern sites are being built.
They are meant to be used together and in many cases are dependant on each other. This is not the case with the core component suite, as they are built (and will continue to be built) as standalone, boxed-off elements. However, this doesn't mean that the core components can't be used with the new building system.
Keep in mind that sections, pages, and the container component and related documentation are in beta, so changes to properties and elements will happen without warning. If you want to see how they work under the hood, check out the source code of the homepage.
Container
The container element is a special component, as it isn't outputting any visible markup. Rather, it's purpose is to provide global styles for section and page components. It does not affect single components and won't ever will.
Properties
bp-mobile
Mobile breakpoint width.
button-border-radius
Button radius border.
button-font-size-multiplier
Button multiplier font-size.
button-font-weight
Button font-weight.
button-margin-top
Button margin-top.
button-margin-x
button-reverse-color
Reverse color of buttons.
button-text-transform
Button text-transform.
color-primary
Primary color which will be used for sections and pages.
color-secondary
Secondary color which will be used for sections and pages.
disable-colors
Disable color generation.
focus-color
Focus color.
font-family-primary
Primary font-family.
font-family-secondary
Secondary font-family.
image-max-width
Image max-width.
max-width
Section max-width on mobile.
offset-header
Offsets first section to the height of the header.
pre-title-background
Pre title background.
pre-title-border-radius
Pre title radius border.
pre-title-color
Pre title color.
pre-title-font-size-multiplier
Pre title multiplier font-size.
pre-title-font-weight
Pre title font-weight.
pre-title-letter-spacing
Pre title letter-spacing.
pre-title-line-height
Pre title line-height.
pre-title-margin-bottom
Pre title margin-bottom.
pre-title-padding
Pre title padding.
pre-title-text-transform
Pre title text-transform.
space-x
Space between content and outer edge of the viewport.
space-xsm
Space between content and outer edge of the viewport.
space-y
Space between the sections.
spacing
Space base for space-scale.
tabs-margin-between
Margin between tab items.
tabs-margin-first
Top margin for first tab item.
tabs-opacity
Tabs opacity.
text-color
Text color.
text-font-size-multiplier
Text multiplier font-size.
text-font-weight
Text font-weight.
text-letter-spacing
Text letter-spacing.
text-line-height
Text line-height.
text-margin-top
Text margin-top.
text-max-width
Text max-width.
text-transform
Component text-transform property.
title-color
Title color.
title-font-size-multiplier
Title multiplier font-size.
title-font-weight
Title font-weight.
title-letter-spacing
Title letter-spacing.
title-line-height
Title line-height.
title-max-width
Title max-width.
title-text-transform
Title text-transform.
Button
Properties
href
Link href.
reverse-color
Reverse text color.
target
Target.
transition-duration
Component transition-duration property.
transition-timing-function
Component transition-timing-function property.
type
Button type.
Card
Card component for sections.
Properties
box-shadow
Component box-shadow property.
padding
Component padding property.
text-color
Text color.
text-font-size-multiplier
Text multiplier font-size.
text-font-weight
Text font-weight.
text-letter-spacing
Text letter-spacing.
text-line-height
Text line-height.
text-margin-top
Text margin-top.
text-max-width
Text max-width.
text-transform
Component text-transform property.
title-color
Title color.
title-font-size-multiplier
Title multiplier font-size.
title-font-weight
Title font-weight.
title-letter-spacing
Title letter-spacing.
title-line-height
Title line-height.
title-max-width
Title max-width.
title-text-transform
Title text-transform.
Footer
Footer component for sections.
Properties
background
Component background property.
gap
Gap between columns.
image-max-height
justify-content
max-width
Component max-width property.
space-before
Space before the footer.
space-y
Distance to the edge of the viewport on the y-axis.
text-color
Text color.
text-max-width
Text max-width.
Header
The introductory element of every website.
Properties
backdrop-filter
Component backdrop-filter property.
background
Component background property.
background-scroll
Turns on background after scroll.
border-bottom
Component border-bottom property.
logo-link
URL the logo links to.
logo-max-height
logo-src
Logo src.
logo-src-mobile
Logo mobile src.
navigation-align
Where the navigation should be aligned to.
position
Component positioning.
space-x
Distance to the edge of the viewport on the y-axis.
wrapper
z-index
Component z-index property.
Text Media
Two-column text-media block component that can be used for a variety of layout options. The current homepage consists of this block only.
Properties
background
Component background property.
column-size
Column size.
first
If set, component will transform the header offset to the top-padding value.
gap
Gap between columns.
hide-media
Hides the media column.
images-gap
Gap between images.
layout
Layout of the section.
media-background
Background color for the media column.
media-background-overlap
Overlaps the background with the media column.
media-full
Removes the outer spacing for the media column.
media-full-mobile-fix
Adds padding to the media column on mobile.
reverse
Reverses the column order.
text-align-inner
Alignment for the inner text wrapper.
text-align-outer
Alignment for the outer text wrapper.
text-background
Background color for the text column.
text-background-overlap
Overlaps the background with the text column.
Docs
Renders a documentation page similar to the one you are currently seeing here. Every heading tag becomes a navigation entry, while navigation headings get created by applying the "data-spx-docs-heading" attribute to the first h1 of a new section.
Properties
bp-mobile
content-heading-font-family
Content heading font-family.
navigation-background
Navigation background.
navigation-font-family
Navigation font-family.
navigation-font-size-multiplier
Navigation multiplier font-size.
navigation-gap
navigation-heading-tag
navigation-height-adjust
navigation-link-color
Navigation link color.
navigation-link-color-active
Navigation link active color.
navigation-link-font-size-multiplier
Navigation link multiplier font-size.
navigation-link-font-weight
Navigation link font-weight.
navigation-link-letter-spacing
Navigation link letter-spacing.
navigation-link-line-height
Navigation link line-height.
navigation-link-text-transform
Navigation link text-transform.
navigation-padding
Navigation padding.
navigation-title-color
Navigation title color.
navigation-title-font-weight
Navigation title font-weight.
navigation-title-letter-spacing
Navigation title letter-spacing.
navigation-title-line-height
Navigation title line-height.
navigation-title-text-transform
Navigation title text-transform.
navigation-top
offset-margin-top
Offset margin-top.
space-bottom
Space from the last content element to the end of the component.
space-x
Distance to the edge of the viewport on the x-axis.
space-y
Distance to the edge of the viewport on the y-axis.
unique-id
Events
spxPageDocsDidLoad
Single
Render a single post layout.
Properties
author-color
Author color.
author-font-family
Author font-family.
author-font-size-multiplier
Author multiplier font-size.
author-font-weight
Author font-weight.
author-letter-spacing
Author letter-spacing.
author-line-height
Author line-height.
author-margin-top
Author margin-top.
author-text-transform
Author text-transform.
content-margin-top
Content margin-top.
content-max-width
Content max-width.
content-space-x
date
Display date.
date-color
Date color.
date-font-family
Date font-family.
date-font-size-multiplier
Date multiplier font-size.
date-font-weight
Date font-weight.
date-letter-spacing
Date letter-spacing.
date-line-height
Date line-height.
date-margin-top
Date margin-top.
date-text-transform
Date text-transform.
header-border-bottom
Header bottom border.
header-padding-bottom
Header bottom padding.
image
Display image.
image-border-radius
Image radius border.
image-height
image-object-position
image-space-x
image-space-y
mobile
Mobile breakpoint.
post
Gets a WordPress post to render.
title-color
Space to edge of the viewport.
title-font-family
Title font-family.
title-font-size-multiplier
Title multiplier font-size.
title-font-weight
Title font-weight.
title-letter-spacing
Title letter-spacing.
title-line-height
Title line-height.
title-margin-top
Title margin-top.
title-text-transform
Title text-transform.
Projects
A collection of web components
for WordPress developers.
A modern component-like
ACF blocks framework.
A minimal and feature-packed
WordPress theme.
© 2020 Fabrikat. All rights reserved.
hi@fabrikatdigital.com