Basic Usage

Creating a Carousel

A carousel is created by specifying an existing container div, a resizing method, a wrapping method, and a list of properties. All properties within the list are optional with defaults used as fallbacks.

The following sections will demonstrate the creation of some of the simplest carousels. These will take advantage of the resizingMethod and wrappingMethod in order to quickly create responsive carousel elements.

Choosing a Container

Any div that you create can be used to house a Freighter carousel. The only requirement is that you assign the div a unique ID that can be used to locate and modify this DOM element:

<div id="myCarousel">
  <!-- Carousel items will eventually go in here! -->
</div>

You can add, reposition, and style this container. All Freighter carousel DOM elements will be appended to it (they will be made the children of the chosen div). The classes and ID of the chosen container will not be altered, so feel free to apply custom CSS classes to your container.

Content-First Philosophy

Let's create the simplest possible carousel by calling the Freighter constructor with a containerID, no resizing or wrapping methods, and an empty property object The code below presupposes that the above div with the ID of myCarousel has already been created:

const myCarousel = new Freighter(
  'myCarousel',
  'none',
  'none',
  {}
);

With no other properties passes into the constructor, the generated carousel looks a bit silly:

You can just about see the flat 'next' and 'previous' buttons, but nothing else renders to the screen. This is because Freighter carousels take a content-first approach, meaning that the content within a carousel dictates how it will look. This includes the dimensions of the carousel, which currently has a height of a few pixels.

Adding Items

Let's continue creating our carousel by adding some items to it. This will fix the height of the carousel demonstrated in the above sections. Remember that this is because the carousel itself typically inherits the dimensions of its carousel items.

There are two ways to add content to a carousel: before the carousel is created or after the carousel is created. This section discusses the basics of both approaches.

At Creation

The easiest way to add items to a carousel is to do so at creation time (before the constructor is called). This can be done directly in the markup, and involves you adding any number of div elements inside of your selected container.

For example, suppose that we want 3 carousel items to our carousel before calling the constructor. The markup would look something like this:

<div id="myCarousel">
  <div class="myItem">
    <p>A</p>
  </div>
  <div class="myItem">
    <p>B</p>
  </div>
  <div class="myItem">
    <p>C</p>
  </div>
</div>

There are a couple of key things to notice about this approach:

• Each carousel item is given an optional classname of myItem, which is an arbitrary classname that can be used to style the carousel items later.
• Each carousel item contains a <p> tag. Carousel items may contain any number of other items, but each carousel item at the highest level must be a div.

If the constructor code from above is run now, the following carousel will be generated. The myItem class and p elements were styled in order to make the carousel items more visually appealing, but buttons and carousel functionality was not altered:

After Creation

Freighter carousels give you the ability to modify most of the properties of a carousel after they have already been constructed. Naturally, one of the most important things that you can change about a carousel are its items.

Freighter provides the addCarouselItems() method that can be called on a Freighter instance, which explains why we stored the constructor's return value in a variable called myCarousel in the previous sections. This method takes either a single HTML element or an array of HTML elements as its first parameter, and an optional second parameter that specifies where the items should be added. By default, items are pushed to the end of the carousel:

// Carousel items to be added.
const newItem1 = document.createElement('div');
newItem.innerHTML = '<p>D</p>';
newItem.classList.add('myItem');

const newItem2 = document.createElement('div');
newItem.innerHTML = '<p>E</p>';
newItem.classList.add('myItem');

const newItem3 = document.createElement('div');
newItem.innerHTML = '<p>F</p>';
newItem.classList.add('myItem');

// Appends one item to the end of the carousel.
myCarousel.addCarouselItems(newItem1);

// Prepends two items to the beginning of the carousel.
myCarousel.addCarouselItems([newItem2, newItem3], 0);

Obviously, this code can be run at any time after the carousel has been created, such as in a button click handler. Try scrolling through the carousel below first, and notice that there is only one item in it. Then, click the button to append a new item to the end of the carousel:

Configuring Properties

Now that our carousel is capable of holding items, we want to change some of the default properties of the carousel. Similar to how items could be added during or after creation of the carousel, properties can be passed into the Freighter constructor or modified after the carousel has been created.

The properties that are available to customize are logically organized into 3 categories:

• Container
• Items
• Buttons

In order to simplify the process of changing carousel properties, this section will focus on adding properties to the carousel through the constructor. See the next section for how to change the properties on an existing carousel.

Container

Two of the most powerful container properties offered by Freigher include the resizingMethod and wrappingMethod properties. Due to the complexity of each value for these properties, they are covered in their own detailed documentation pages.

Note that neither resizingMethod nor wrappingMethod are present in the properties object; instead, they follow the containerID as normal constructor parameters. This is because the properties object only contains properties that can be dynamically changed later, and the resizingMethod and wrappingMethod are fixed.

The two values that will be used in the example below are resizingMethod: 'stretch-scale' and wrappingMethod: 'wrap-simple'. You may be able to figure out what these values do by comparing the carousel to the ones in the previous sections, but be sure to consult their respective documentation pages for more information.

Some of the more self-explanatory properties offerred for carousels include the numItemsVisible, scrollBy, and autoScroll properties. Below shows an example of constructing a carousel that overrides the default values for these properties, as well as the resulting carousel:

// Create a new carousel using the container with the ID "myCarousel".
const myCarousel = new Freighter(
  'myCarousel',
  'stretch-scale', 
  'wrap-simple',
  {
    numItemsVisible: 3,
    scrollBy: 2,
    autoScroll: true,
  }
);

There are many more properties that can be modified to impact the behavior of Freighter carousels, including ways to modify the specific behavior of an autoscrolling carousel. Check out all of the properties associated with Freighter carousels here.

Items

Some properties that can be set on Freighter carousels impact the way that carousel items themselves appear or behave on the screen. The most important ones are itemHeight, itemWidth, and itemSpacing, which do esentially what their names suggest. Each of these values implicitly uses the px unit, and only requires a number to be set as its value.

Below shows an example of constructing a carousel that overrides the default values for these properties, as well as the resulting carousel:

// Create a new carousel using the container with the ID "myCarousel".
const myCarousel = new Freighter(
  'myCarousel',
  'stretch-scale',
  'wrap-simple',
  {
    numItemsVisible: 3,
    scrollBy: 2,
    itemHeight: 3,
    itemWidth: 2,
    itemSpacing: 10,
  }
);

There's more to adjusting the size and spacing of each carousel item, but what you have seen are the absolute basics. Check out all of the properties associated with Freighter carousel items here.

Buttons

The final category of customizable carousel properties are those that change the style of the buttons that appear on the left and right sides of the carousel. Each button is highly customizable, including the ability to change each button individually.

Customizing buttons works a bit differently than customizing the carousel or its items. There 6 total button properties that can be assigned objects as their values, with each object containing a set of styles for that button (or buttons). Below is the code for a simple example of customizing the buttons of a carousel, with the resulting carousel and an explanation below:

// Create a new carousel using the container with the ID "myCarousel".
const myCarousel = new Freighter(
  'myCarousel',
  'stretch-scale',
  'wrap-simple',
  { 
    numItemsVisible: 3,
    scrollBy: 2,
    itemSpacing: 20,

    // Common styles for both buttons.
    buttonStyles: {
      backgroundColor: 'rgba(255, 255, 255, 0.75)',
      color: 'orange',
    },

    // Common hover styles for both buttons.
    buttonHoverStyles: {
      backgroundColor: 'rgba(255, 255, 255, 0.9)',
      height: '90%'
    },

    // Styles for the right button only.
    rightButtonStyles: {
      color: 'blue',
    }
  }
);

Below is an explanation for the property values applied and the resulting carousel:

• The order of properties has no effect on how button styles are applied; styles for both buttons are always applied before styles for an individual button override these styles.
  • The buttonStyles property is applied to both buttons, and the buttonHoverStyles property is applied to both buttons when the user hovers over either button.
  • The property values in the constructor above ensure that both buttons are white with orange chevrons normally, and increase their opacity and height on hover.
• The rightButtonStyles are applied after, applying new or overriding existing properties to only the right button. This is why the right button chevron is blue instead of orange.
• Because the chevron hover styles are never overridden on either button, hovering over the buttons resets the chevron color to its default color.

Visible and responsive buttons are key to any good carousel, which is why Freighter features ones that are highly and individually customizable. Check out all of the properties associated with freighter carousel buttons here.

Changing Properties

Much of the power of Freighter carousels comes from the ability to change most of the properties of a carousel after it has been created. At the click of a button, carousel item sizes, spacings, transitions, button styles, and more can all be changed.

Freighter also provides ways of retrieving the current property values applied to a carousel. These could be useful for writing your own code that behaves differently based on the current property values.

It should now start to make sense why a reference to each carousel above was stored during construction; a number of useful methods (including those described below) can be called on a carousel object.

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.

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.