API

There are only a few callable methods and custom types that you need to know in order to take advantage of Freighter carousels. Below, you will find method signatures, descriptions, and return types for each method that can be called on a carousel, as well as the custom types referenced.

Callable Methods

Once a Freighter object is constructed, there are a few methods that can be called on that method. Note that each of these methods require an instance of the Freighter class to be called on, so, for example, the call Freighter.getCarouselState() would simply raise an exception.

Freighter(containerID, resizingMethod, wrappingMethod, properties)

Constructor for the Freighter class. Initializes the Carousel by passing the properties parameter to the Carousel constructor. Assigns the returned carousel to the carousel member attribute.

Parameters (4 required):

Parameter Type Description
containerID string The ID of the container <div> to be used as the carousel parent element.
resizingMethod "none" | "stretch" | "stretch-gap" | "stretch-scale" | "stretch-populate" The method to be used when resizing the carousel due to browser window resizing.
wrappingMethod "none" | "wrap-simple" | "wrap-smart" The wrapping method to be used when the carousel is scrolled while at either extreme.
properties CarouselProperties The properties to be used to initialize the carousel.

Returns the Freighter object that was constructed.

setCarouselProperties(properties)

Changes the carousel properties to those provided as arguments. Note that not all carousel properties can be changed, such as the wrap and resize methods.

Parameters (1 required):

Parameter Type Description
properties CarouselProperties The new properties to be used to update the carousel.

Returns void.

getCarouselState()

Retrieves the current state of the carousel and returns it. This includes internal data not specified in the original or updated properties, such as the carousel items themselves and the current carousel pointer.

Parameters (0)

Returns the CarouselState object representing the carousel's current state.

addCarouselItems(items, index?)

Adds a new item to the carousel. The item is added to the end of the carousel by default, but an optional index can be provided.

Parameters (1 required, 1 optional):

Parameter Type Description
items HTMLElement | HTMLElement[] The HTML element or elements to be added to the carousel.
index? number Optional index at which to add the item. Adds to the end of the carousel by default.
* A ? denotes an optional parameter. See above for what default is used if omitted.

removeCarouselItems(index, count = 1)

Removes a number of carousel items starting from the given index. By default, this method just returns the item at this index, but the number of items to remove starting from this index can be specified.

Parameters (1 required, 1 default):

Parameter Type Description
index number The index of the item to be removed, or the starting index if multiple items are to be removed.
count = 1 number Optional number of items to remove. Defaults to 1.
* A ? denotes an optional parameter. See above for what default is used if omitted.

Types

Freighter was written in TypeScript, allowing it to take advantage of the great typing system offered. The methods listed above mention a few custom types whose structure must be understood in order to effectively be called. Below are the custom types used by Freighter and their structures:

CarouselProperties

An object containing several (key, value) pairs that define the properties of a Freighter carousel. Note that because each of these properties is optional, the object can be empty. If a property is left blank, it will fall back to its default value specified below.

Object Keys:

Property Type Description
itemWidth number The width of each carousel item in pixels.
itemHeight number The height of each carousel item in pixels.
itemSpacing number The space between each item in pixels.
buttonStyles ButtonStyle The common styles that both buttons will use.
buttonHoverStyles ButtonStyle The common styles that both buttons will use when being hovered.
leftButtonStyles ButtonStyle The left button style overrides that will take precedence over the shared button styles.
leftButtonHoverStyles ButtonStyle The left button hover style overrides that will take precedence over the shared button hover styles.
rightButtonStyles ButtonStyle The right button style overrides that will take precedence over the shared button styles.
rightButtonHoverStyles ButtonStyle The right button hover style overrides that will take precedence over the shared button hover styles.
scrollable boolean Whether or not the carousel can be manually scrolled. If set to false, the buttons will not appear either.
scrollBy number The number of items to scroll by. This value is used for both manual and auto scroll.
numItemsVisible number The number of items that are visible at any given time.
syncScrollWithVisibility boolean Whether or not the scrollBy should be overriden with the numItemsVisible. Useful for when you want to sync these values knowing that the number of items will change.
autoScroll boolean Whether or not the carousel will scroll on its own. If scrollable is set to true, the user can still manually scroll.
autoScrollInterval number The number of milliseconds to wait before scrolling to the next set of carousel items.
autoScrollDirection "left" | "right" The direction that the carousel will auto scroll.
autoScrollPauseOnHover boolean Whether or not the carousel's auto scroll should pause if the user is hovered over the carousel.
transitionDuration number The number of milliseconds that it should take in order to complete a carousel scroll.
transitionDelay number The number of milliseconds that should pass before the scroll begins.
transitionTimingFunction string A valid CSS transition timing function used to scroll the carousel.

Default Values:

itemWidth: 225,
itemHeight: 150,
itemSpacing: 0,
buttonStyles: {
  width: "25px",
  height: "80%",
  position: "center",
  borderTop: "none",
  borderRight: "none",
  borderBottom: "none",
  borderLeft: "none",
  backgroundColor: "rgba(100, 100, 100, 0.5)",
  color: "rgba(50, 50, 50, 0.75)",
  cursor: "pointer",
  transition: "all 200ms ease",
},
buttonHoverStyles: {
  backgroundColor: "rgba(100, 100, 100, 0.8)",
  transition: "all 200ms ease",
},
leftButtonStyles: {
  borderTopRightRadius: "5px",
  borderBottomRightRadius: "5px",
},
leftButtonHoverStyles: {},
rightButtonStyles: {
  borderTopLeftRadius: "5px",
  borderBottomLeftRadius: "5px",
},
rightButtonHoverStyles: {},
scrollable: true,
scrollBy: 1,
numItemsVisible: 1,
syncScrollWithVisibility: false,
autoScroll: false,
autoScrollInterval: 1000,
autoScrollDirection: "right",
autoScrollPauseOnHover: false,
transitionDuration: 500,
transitionDelay: 0,
transitionTimingFunction: "ease-in-out"

CarouselState

An object containing several (key, value) pairs that represent the current state of a Freighter carousel. The state is defined as the intersection between a CarouselProperties object and a few other internal pieces of state that may be useful to know.

Object Keys:

All of the properties available in a CarouselProperties object, and...

Property Type Description
carouselID number The unique internal number assigned to a carousel. Will be different from all other carousels in order to uniquely identify each.
carouselItems HTMLElement[] An array of all of the carousel items. Allows for the modification or access of these items.
leftCarouselPointer number The index of the leftmost visible carousel item. Useful for determining which items are visible.
carouselContainer HTMLElement The outermost HTML element that houses the entire carousel.

ButtonStyle

An object containing several (key, value) pairs that define the styles of a Freighter carousel button. Note that because each of these properties is optional, the object can be empty. If a property is left blank, only the default CSS styles will be used.

Object Keys:

Property Type Description
width string A valid CSS width value that will be applied to the button.
height string A valid CSS height value that will be applied to the button.
position "top" | "center" | "bottom" The vertical aligmnemt of the buttons as compared to the carousel container.
borderTop string A valid CSS border value that will be applied to the button.
borderRight string A valid CSS border value that will be applied to the button.
borderBottom string A valid CSS border value that will be applied to the button.
borderLeft string A valid CSS border value that will be applied to the button.
borderTopLeftRadius string A valid CSS border radius that will be applied to the button.
borderTopRightRadius string A valid CSS border radius that will be applied to the button.
borderBottomLeftRadius string A valid CSS border radius that will be applied to the button.
borderBottomRightRadius string A valid CSS border radius that will be applied to the button.
backgroundColor string A valid CSS background color to be applied to the button.
color string A valid CSS color to be applied to the chevron within the button.
cursor string A valid CSS cursor option to be applied to the button.
transition string A valid CSS transition to be applied to the button; used to transition to the button's hover styles.
API