Properties Overview

Freighter features a number of configurable properties for your carousels, most of which can be changed at any time.

What are Properties?

Properties are what defines each Freighter carousel. They range from the number of items visible at a time to the wrapping and resizing behavior of the carousel.

With the exception of static properties, all properties are optional and dynamic , meaning they can be changed at any point. Properties are initially set when instantiating a new carousel using the constructor, but these dynamic properties can be set or changed later using the setCarouselProperties() method.

The code below demonstrates initializing properties through the constructor: 

const myCarousel = new Freighter(
  'myCarousel',
  'stretch-gap',
  'wrap-simple',
  {
    numItemsVisible: 2,
    scrollBy: 2,
    itemWidth: 200,
    itemHeight: 200,
    itemSpacing: 20,
    ...
  }
);

The 3 static properties are the first 3 required parameters of the constructor, whereas the dynamic properties are all included in a single CarouselProperties object as the 4th required parameter. If you didn't want to explicitly set any dynamic properties, an empty object would instead be passed.

Another logical way of splitting up properties is by the components of a carousel that they affect. Properties may affect the carousel container, the carousel items, or even the carousel buttons. The documentation pages of this site are set up in a way that reflects this organization.

Types of Properties

As mentioned, there are 2 types of properties for any Freighter carousel: static and dynamic.

Static properties are required, as they define some of the core functionality of the carousel. For this reason, they also cannot be changed later (with one exception).

Dynamic properties are optional, as they have logical defaults that can be used in absence of user-set values. They also aren't deeply integrated into the core functionality of the carousel, so they can be changed later.

Static Properties

There are only 3 static properties, as indicated by the table below. Feel free to click on any property to be taken to its designated section in the documentation:

Element(s) Potentially Affected
Property Name Carousel Container Carousel Item Carousel Buttons
carouselID ❌
resizingMethod ❌ ❌ ❌
wrappingMethod ❌
*❌ indicates that the component(s) are affected in some way by the property.

Though there may not be many, the resizingMethod and wrappingMethod properties are so involved that each one warrants its own section.

The resizing behavior of a carousel defines how it reacts to changes in its parent container's size. The wrapping behavior of a carousel defines how it reacts when the user attempts to scroll beyond either end of it. Freighter offers a number of built-in methods for both of these behaviors, each of which can be read about on their respective pages.

Dynamic Properties

There are 20 dynamic properties, some of which expecting a value of an entirely different object type! The table below lists all of the dynamic properties. Feel free to click on any property to be take to its designated section in the documentation:

Element(s) Potentially Affected
Property Name Carousel Container Carousel Item Carousel Buttons
itemWidth ❌ ❌
itemHeight ❌ ❌
itemSpacing ❌
numItemsVisible ❌ ❌
scrollBy ❌
syncScrollWithVisibility ❌
scrollable ❌
autoScroll ❌
autoScrollInterval ❌
autoScrollDirection ❌
autoScrollPauseOnHover ❌
transitionDuration ❌
transitionDelay ❌
transitionTimingFunction ❌ ❌
buttonStyles ❌
buttonHoverStyles ❌
leftButtonStyles ❌
leftButtonHoverStyles ❌
rightButtonStyles ❌
rightButtonHoverStyles ❌
*❌ indicates that the component(s) are affected in some way by the property.

itemWidth, itemHeight, and itemSpacing are all used to control the dimensions and spacing of carousel items. They each use the px unit, and for some carousel resizing methods, may change the actual dimensions of the carousel container itself.

numItemsVisible and scrollBy determine how many items are visible in the carousel at a time, as well as how far to scroll in either direction (left or right). syncScrollWithVisibility, if set to true, ensures that the carousel will always scroll by the same amount of items that are visible, meaning each scroll will load in a completely new set of items.

Most of the autoScroll properties are self-explanatory. Note that if autoScroll itself is set to false, the values of the other related properties are ignored.

Much like autoScroll, there are a number of different transition-related properties. These really only affect the carousel container, but depending on the transitionTimingFunction selected, certain carousel items may not load as you might expect.

Finally, all of the buttonStyles and related properties are used to safely apply common styles to the carousel buttons. The same base styles can be applied to both using buttonStyles, and then individual styles can be applied to each button using the leftButtonStyles and rightButtonStyles properties accordingly. The style of the buttons can also be configured by using the HoverStyles variation of each property.

For a fully-detailed description of each property, be sure to check out the property's designated documentation section by using the links in the table above.

Getting Properties

At any point, the current value for any carousel property can be retrieved. In order to simply the interface for retrieving these values, all property values are stored in a single object - this object can be retrieved using the getCarouselState() method. Take, for example, the carousel below. There is no code included for this carousel, but rather a button that calls the getCarouselState() method and logs the resulting object to the console.

Why is the method called getCarouselState() and not getCarouselProperties()?

This is because this method returns more than just the properties of a carousel. There are a few other pieces of internal state returned that can prove useful to the programmer, and they are technically not a part of the properties of the carousel. For the full list of properties and state, see the API documentation.

Try it yourself: press the button and open the console. Apart from now understanding what properties were used to create the carousel below, being able to see all of the keys in this object can introduce the programmer to properties of which they were previously unaware:

Setting Properties

Freighter carousels allow most properties to be changed dynamically, or on-the-fly. This can be done through the setCarouselProperties() method. This method takes a single parameter: a CarouselProperties object, representing a collection of key-value pairs for the properties to be changed. The object structure can be viewed in the full API documentation, but most of the properties are self-explanatory. Additionally, many of the changeable properties can be revealed by using the getCarouselState() method described above.

Use the buttons below to change a variety of carousel properties:

As you can see, Freighter offers a great amount of customization to carousels, including the ability to change properties and carousel items at any time.

These are just some of the basics; be sure to continue reading the documentation for complete and in-depth breakdowns of all the features that Freighter carousels have to offer, including how wrapping or resizing properties affect carousels, an overview of the various carousel properties that can be customized and dynamically changed, or a full breakdown of the API offered by Freighter.

Properties Overview