Welcome to our new Help Center. We’re still adding articles, and if you can’t find an answer yet, we’re happy to help.Contact Us

Events and Event Callbacks

Code in the Project Editor or your own script can run when a project loads, changes slides, plays a video, or opens as a popup. It receives the project’s state and can stop or redirect a slide change.

On this page

    LayerSlider’s events are jQuery events of the project’s element, the container that holds the project on the page. You can handle them in 2 places: as Event Callbacks, written in the Project Editor, or with jQuery’s .on() in a script of your own.

    Events

    The table lists the events in the order of the Event Callbacks window.

    Event When it fires
    sliderWillLoad When the project’s script starts, before any other event and before LayerSlider reads the project’s settings and builds the project
    sliderDidLoad When the project has been built, before its first slide starts playing
    sliderWillResize Before LayerSlider sizes the project: while the project loads, each time the browser window is resized, and when the project’s container changes its width
    sliderDidResize After LayerSlider has sized the project, at the same moments
    slideshowStateDidChange At every change of the slideshow’s state, also at each slide change, not only when the slideshow pauses or resumes
    slideshowDidPause When the slideshow goes from playing to paused, also when a project waits to be scrolled into view
    slideshowDidResume When the slideshow goes from paused to playing, also when the project starts its slideshow
    slideChangeWillStart When a slide change is about to begin, before anything moves
    slideChangeDidStart When the slide transition has begun
    slideChangeWillComplete Shortly before the change completes, while slides.current is still the slide that is leaving
    slideChangeDidComplete After the change has completed: slides.current is the new slide, and slides.prev the one before
    slideTimelineDidCreate When the layer timeline of the slide about to play has been built, for the first slide too
    slideTimelineDidUpdate On every frame while the slide’s layer timeline plays, also while it plays backward
    slideTimelineDidStart When the slide’s layer timeline starts playing: for the first slide, and again after every slide change
    slideTimelineDidComplete When the slide’s layer timeline reaches the end of the slide, right before the slideshow moves on
    slideTimelineDidReverseComplete When the slide’s layer timeline, played backward by the reverse command, reaches the start of the slide
    mediaDidStart When a video layer starts playing for the first time. Resuming the video after a pause doesn’t fire this event again
    mediaDidStop When a video layer that has started ends, or when a slide change stops it. A pause doesn’t fire this event
    mediaPlayStateDidChange When a video layer starts, pauses, resumes, or ends, and when a slide change stops it
    mediaMuteStateDidChange When the project’s sound is muted or unmuted
    popupWillOpen When a popup starts to open
    popupDidOpen When the popup’s opening transition has ended
    popupWillClose When the popup starts to close
    popupDidClose When the popup’s closing transition has ended and the popup is hidden
    sliderDidDestroy When the destroy command has finished
    sliderDidRemove After destroy with true, right after sliderDidDestroy, as the project leaves the page

    These events don’t pass the event data to a handler:

    • sliderWillLoad, sliderDidDestroy, and sliderDidRemove pass only the jQuery event.
    • slideTimelineDidCreate passes an object with 3 keys. slideTimeline is the slide’s layer timeline, layersOnSlideTimeline a jQuery set of the slide’s layers and its background, and slideTimelineDuration the slide’s duration as a number of seconds.
    • slideTimelineDidUpdate passes the slide’s layer timeline itself.

    Stopping or redirecting a slide change

    Two events use what a handler returns. From slideChangeWillStart, return false to cancel the slide change. To change to another slide instead, return its number, and the slideshow goes on from that slide.

    From slideTimelineDidComplete, return false to keep the slideshow on the slide.

    After a false, the slideshow doesn’t try again by itself. To move on, send the project the next command, and the slideshow goes on from the next slide.

    The event data

    A handler receives the jQuery event, whose target is the project’s element, and, for most events, the event data, an object that describes the project at that moment. this is the project’s element too.

    These are the keys of the event data that a handler uses most:

    Key What it is
    slides.current The slide shown, with index, deeplink, layersIn, layersOut, and timeline
    slides.prev The slide shown before, with index and deeplink
    slides.next The slideshow’s next slide, with index, deeplink, layersIn, and layersOut. During slideChangeWillStart of a change sent from code, such as layerSlider( 3 ), it’s still the slide that would have come next
    slides.count The number of slides
    index A slide’s number, counted from 1, as in slides.current.index
    deeplink The value of a slide’s Deep Link field, or null when it’s empty
    layersIn, layersOut jQuery sets of a slide’s layers that come in and that go out
    timeline In slides.current, the slide’s layer timeline: a TimelineMax of LayerSlider’s own copy of GSAP 2, not of a gsap that your page loads
    slideshow.state The slideshow’s state: the flags running and paused, and changed, a counter that goes up at each slide change
    isBusy true while the project preloads images or changes slides. A slide change asked for during that time is ignored
    event.target In mediaDidStart, mediaDidStop, and mediaPlayStateDidChange, the video layer’s video element, and in the other events the project’s element. In a handler written as function( event, slider ), this key is slider.event.target, and event.target is the project’s element
    userData The settings the project runs with: its own, merged with LayerSlider’s defaults
    api() A function that sends a command to this project only, such as api( 'next' )

    Event Callbacks in the Project Editor

    In the Project Editor, go to Project Settings › Event Callbacks. In the Event Callbacks window, write your code in the event’s box.

    In a box’s first line, such as function( event, slider ) {, event is the jQuery event and slider the event data, or what the event passes instead.

    The callbacks are saved with the project and reach your site when you click Publish. Save keeps them in the draft, which only the editor shows. The callbacks also run in the editor’s previews.

    Warning

    If a callback isn’t valid JavaScript, the Event Callbacks window marks its event with a warning, but Publish puts it on the page all the same. On the page, the browser then reports a SyntaxError, and the project doesn’t start.

    Listening from your own script

    Find the project by its ID, as [id^="layerslider_12_"], and bind your handlers with jQuery’s .on(), as the examples do. The article on the JavaScript API shows where to find the ID, and how to select a project by its slug instead.

    If the page shows the project more than once, the handler runs for each copy, and this is the copy that the event is about.

    To receive sliderWillLoad and sliderDidLoad too, bind before the project starts, for example in a jQuery ready handler. Print your script after jQuery: from wp_footer at priority 99, it comes after jQuery wherever WordPress puts jQuery. A listener for the window’s load event comes too late for a project that starts with the page.

    If a handler doesn’t run

    A handler runs when it’s bound on the project’s element itself, with the event’s name as the table gives it. These handlers don’t run:

    • A handler whose event name has only a namespace of your own, such as 'sliderDidLoad.mytheme'
    • A handler delegated from document with a selector for the project
    • A handler bound on a parent element of the project

    Bind on the project itself instead, as the examples do. To give a handler a namespace of your own, add layerSlider to it, as in 'sliderDidLoad.layerSlider.mytheme': the handler runs, and .off( '.mytheme' ) removes it.

    If a handler throws an error, the project goes on, and the browser’s console shows the error after a line with the event’s name, such as LayerSlider: Error while calling event "slideChangeDidComplete":.

    If your code was written for LayerSlider 8, see which changes in LayerSlider 9 affect it.

    Examples

    Each example goes in a script printed from wp_footer at priority 99. Change 12 to your project’s ID, and 15 to your popup’s.

    The first example adds the class summer-sale-ready to the page’s body when the project has loaded.

    JavaScript
    jQuery( function() {
    	const $project = jQuery( '[id^="layerslider_12_"]' );
    
    	$project.on( 'sliderDidLoad', function() {
    		jQuery( 'body' ).addClass( 'summer-sale-ready' );
    	} );
    } );

    The second example writes the number of the slide shown into the data-summer-slide attribute of body each time a slide starts, the first slide included.

    JavaScript
    jQuery( function() {
    	const $project = jQuery( '[id^="layerslider_12_"]' );
    
    	$project.on( 'slideTimelineDidStart', function( event, slider ) {
    		jQuery( 'body' ).attr( 'data-summer-slide', slider.slides.current.index );
    	} );
    } );

    The third example keeps the slideshow on the project’s last slide.

    JavaScript
    jQuery( function() {
    	const $project = jQuery( '[id^="layerslider_12_"]' );
    
    	$project.on( 'slideTimelineDidComplete', function( event, slider ) {
    		if ( slider.slides.current.index === slider.slides.count ) {
    			return false;
    		}
    	} );
    } );

    The fourth example stops the project’s slideshow while a popup is open, and starts it again when the popup has closed.

    JavaScript
    jQuery( function() {
    	const $project = jQuery( '[id^="layerslider_12_"]' );
    	const $popup = jQuery( '[id^="layerslider_15_"]' );
    
    	$popup.on( 'popupWillOpen', function() {
    		$project.layerSlider( 'stop' );
    	} );
    
    	$popup.on( 'popupDidClose', function() {
    		$project.layerSlider( 'start' );
    	} );
    } );

    Events on the first slide

    For the first slide of a project that’s in view when the page loads, no slide change event fires. Those events start with the project’s first change of slides. To run code on every slide, the first included, use slideTimelineDidStart, as the second example does.

    A project outside the view when the page loads waits until it’s scrolled into view, because the Start Only in Viewport switch in Project Settings › Slideshow is on by default. When the project comes into view, it gets a slideChangeDidComplete for its first slide, without a slideChangeWillStart or slideChangeDidStart before it.

    A project far down the page

    A project far below the first screen doesn’t load with the page. Its sliderWillLoad fires as the page loads, but its sliderDidLoad can come well after the page’s load event, even if nobody scrolls. LayerSlider starts the projects closest to the viewport first, and a project far down the page waits, even when it’s the only project on the page.

    To have such a project load with the page, go to Project Settings › Performance, choose Highest in the Load Priority list, and publish the project. The project’s slideshow still waits until the project is scrolled into view.