Usage

Last modified:

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 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:



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

        

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:



      <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;
      }

        

While it is technically possible to style the components directly and without CSS variables, it is not recommended. 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, there are some general design tokens that affect all components. Of course, these can be freely reassigned to match your current project.



        body {
          --spx-fluid-base: 16;
          --spx-fluid-min-w: 320;
          --spx-fluid-max-w: 1440;
          --spx-backdrop-filter: blur(4px);
          --spx-border-radius: 0.375rem;
          --spx-font-family: helvetica, segoe, arial, sans-serif;
          --spx-font-size: 16px;
          --spx-transition-duration: 100ms;
          --spx-transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
        }

        

Responsive design

Creating responsive designs using spx components is straight forward using the following two options:

CSS Variables

Drop these into your CSS file or add them as inline style tags.



        @media (min-width: 1024px) {
            body {
                --spx-navigation-font-size: 18px;
            }
        }

        @media (min-width: 1280px) {
            body {
                --spx-navigation-font-size: 24px;
            }
        }

        

Element attributes

Every data attribute that starts with bp- will automatically be added to the responsive options. The number after the dash indicates the screen size (in pixels) when the new settings should be applied. (mobile-first)

The following code is the equivalent of the example from above:



        <spx-navigation
            bp-1024='{"font-size": "18px"}'
            bp-1280='{"font-size": "24px"}'>
        </spx-navigation>

Keep in mind that the content inside the attributes has to be a valid JSON object and thus needs to be enclosed by single quotes.

Responsive attributes have the big advantage that every component property can be changed depending on the current screen size, even ones that don't have a CSS variable counterpart! This means that you can create fully responsive versions of components without ever leaving the markup of the page.

Styling

Some components can be styled using varying methods. If the styling attribute is present on a component, up to three different techniques are available:

Default

Styles are applied using CSS attributes.



      <spx-accordion styling="default" gap="0.4em">

      <style>
        :root {
          // alternatively using CSS variables.
          --spx-accordion-gap: 0.5em;
        {
      </style>

Fluid

In this mode, a value will responsively scale up or down in a linear fashion depending on a set min and max value.



      <spx-accordion styling="fluid" gap-min="0.5" gap-max="1">

      <style>
        :root {
          // alternatively using CSS variables.
          --spx-accordion-gap-min: 0.5;
          --spx-accordion-gap-max: 1;
        {
      </style>

Headless

Great for a utility-first workflow using a library like Tailwind. Please refer to the component docs for all possible class slots.



    <spx-accordion styling="headless" class-header="grid gap-4">

Since version 4.0, it is now possible to define your own Tailwind config and overwrite the standard configuration by naming your object spxTailwindConfig.



    var spxTailwindConfig = {
      theme: {
        colors: {
          gray: colors.coolGray,
          blue: colors.lightBlue,
          red: colors.rose,
          pink: colors.fuchsia,
        },
        fontFamily: {
          sans: ['Graphik', 'sans-serif'],
          serif: ['Merriweather', 'serif'],
        },
        extend: {
          spacing: {
            '128': '32rem',
            '144': '36rem',
          },
          borderRadius: {
            '4xl': '2rem',
          }
        }
      }
    }

        

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, slider, slideshow (spxGetImages) and navigation (spxGetNavigation) component. The navigation component only works using the helper function.



      <?php $images = spxGetImages( "myGallery", "acf" ) ?>

      <spx-masonry images="<?php echo $images ?>"/>

This will automatically create a masonry layout from the ACF gallery!

Available helpers



      // Gets images for masonry, slider, slideshow.
      spxGetImages( $fieldName, $fieldSrc = 'acf' | 'mb', $postId )

      // Gets a menu for navigation.
      spxGetNavigation( $name )

        

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 and functions.

Lazy Loading

By default, spx is only loading the needed .js files depending on which components are available on the page. This has the advantage that the library of components can grow to an unimaginable number without an effect on performance. Since no assets are loaded if there are no spx elements on the page, elements added via JavaScript won't be initialised.

To counteract this, it is possible to specify a list of body classes, which, when present, will load the necessary assets for components to function correctly.



    add_filter( 'spx/lazyload_whitelist', function ( $array ) {
      $array[] = 'my-custom-body-class';
      $array[] = 'page-invoice';

      return $array;
    } );