Container Properties

Carousel Container Basics

While many of the CarouselProperties that primarily affect the carousel container fall into one of 3 major categories (manual scrolling, automatic scrolling, and transitions ), there are a few properties that don't fit into any.

carouselID

The carouselID property is a static carousel property that is required for the creation of any Freighter carousel. It is the first parameter of the Freighter() constructor, and cannot be changed later.

itemSpacing

This is the carousel property that affects the amount of space between items of a carousel and uses the px unit. The space is placed between items, and thus there will always be numItemsVisible - 1 spaces that take up itemSpacing pixels each. When using the resizing method of none, the size of the carousel is the sum of all carousel items and the total amount of itemSpacing between all of the carousel items.

Besides being manually changed, this property may be changed by certain resizing methods. For example, stretch-gap and stretch-populate are partially defined by how they change the itemSpacing property, so expect this value to change when using either one of these resizing methods.

numItemsVisible

This property determines the number of carousel items to be displayed at a time. Once a scroll commences in either direction, numItemsVisible carousel items will be visible once again.

Besides being manually changed, this property may be changed by certain resizing methods, much like the itemSpacing property. For example, the stretch-populate wrapping method is partially defined by how it changes the numItemsVisible property, so expect this value to change when using either one of these resizing methods.

Manual Scrolling

Scrolling manually is the default behavior of a carousel, though exactly how the manual scrolling behaves can be fine-tuned via the following carousel properties.

scrollable

This carousel property is used to determine whether or not the user has the ability to manually scroll the carousel. The default value is true, which leaves the buttons untouched and available for the user to scroll.

If set to false, the carousel buttons will be removed, and the user will not be permitted to manually scroll the carousel. Not that the value of this property does not affect the autoScroll property; both of these properties are managed independently and thus any combination of the two is permitted.

scrollBy

This property determines how many carousel items should be scrolled by either a manual or automatic scroll in either direction. This number is not limited by the number of carousel items currently in a carousel. If scrollBy is greater than the total number of carousel items, the carousel will scroll to the end. If wrapping has been enabled, the appropriate behavior will be applied according to the selected wrapping method.

syncScrollWithVisibility

This property is closely associated with the scrollBy and numItemsVisible properties, and ensures that they are in sync. More specifically, if this property is set to true, the value of numItemsVisible will be used as the amount to scroll, overriding the scrollBy property. This means that if the numItemsVisible ever changes, scrolling will always scroll by the number of items, presenting the user with a completely new set of items on any scroll (disregarding the inevitable wrapping that occurs if there are fewer carousel items).

This functionality is already possible: the carousel could just be initialized with a scrollBy value that matches the numItemsVisible value. The major use case for this property, however, is if the numItemsVisible changes. This is possible through manual property changes, may also occur when using a resizing method that changes item visibility, such as stretch-populate.

This first carousel uses stretch-populate, but has a fixed scrollBy value of 2. This means that no matter how many carousel items are currently visible, the carousel will always scroll by 2. This means that the carousel may progress too far or not far enough on each scroll:

This next carousel has all of the same properties, including the same scrollBy value of 2. In addition, its syncScrollWithVisibility is set to true, which overrides the scrollBy value. No matter the size, no items will be skipped, nor will they remain visible when scrolling:

Automatic Scrolling

By default, a carousel will only scroll when the user manually clicks on one of the scroll buttons. In addition to this (or as a replacement), a carousel can be configured to automatically scroll in a given direction at a given interval.

autoScroll

This is the property that enables and disables automatic scrolling on a carousel. By default, it is set to false. The following 3 properties will have an affect on the carousel if and only if autoScroll is set to true.

Note that enabling autoScroll does not disable manual scrolling. If scrollable and autoScroll are both true, the carousel will automatically scroll, but can still be scrolled by the user. If you want the carousel to only scroll on its own, you must also set scrollable to false.

autoScrollInterval

This property determines how often the carousel should be automatically scrolled and uses the ms unit.

Every autoScrollInterval milliseconds, the carousel will be scrolled. The interval restarts once the transition has commenced. This means that a carousel with autoScrollInterval of 1000ms and transitionDuration of 3000ms will wait 1000ms, take 3000ms to transition to the next set of carousel items, and wait another 1000ms before scrolling again.

autoScrollDirection

This property can take either "left" or "right" as its value, and determines the direction in which a carousel will be automatically scrolled every autoScrollInterval milliseconds.

autoScrollPauseOnHover

This property determines if hovering over the carousel will prevent it from automatically scrolling to the next set of carousel items. This is useful for allowing the user to take a closer look at a carousel item without completely removing the autoScroll behavior. Note that by default, this property is set to false, so a user will by default have no way of pausing the autoscroll functionality.

When the user stops hovering over the carousel, the timer before scrolling again resets to 0. This means that when the user moves their mouse off of the carousel, it will take autoScrollInterval milliseconds to scroll again. This technically means that the scroll is being 'restarted' rather than 'resumed'.

Transitions

Every time the carousel is scrolled (either manually or automatically), the entire carousel goes through what is known as a transition. This transition defaults to a certain duration and uses a simple timing function, but all of these properties can be changed.

transitionDuration

This property, measured in ms, determines how long a scroll in either direction will take to complete. No matter how many items are being scrolled by, the speed at which the transition completes is defined by this property.

transitionDelay

This property is used to delay the transition of a carousel any number of ms, defaulting to 0. Once either a button is clicked to scroll or the next automatic scroll is to take place, transitionDelay milliseconds are waited before beginning the transition.

transitionTimingFunction

This property can take the value of any valid CSS transition timing function string and defaults to "ease-in-out" The timing function determines how the transition will be executed when scrolling, including the acelleration and decelleration of the transition.

Any CSS transition timing function can be used, including the more complex cubic-bezier() function. If you plan on using this transition timing function, check out this section of the cautions page for information about how making the transition too extreme can potentially result in empty carousel spaces during transitions.