Button Properties

The 6 CarouselProperties Button Keys

There are 6 button-related keys in the CarouselProperties object. Each represents the styles to be used for a certain grouping of buttons under certain circumstances, and this section defines the heirarchy that they follow:

By default, if any of these keys are omitted from the CarouselProperties object, Freighter falls back on its own defaults. This is the same behavior that occurs when any of the CarouselProperties keys are omitted.

If these keys are included in the CarouselProperties object, the following defines the heirarchy that will be used for styling carousel buttons:

1. Any properties included in buttonStyles will initially be applied to both the left and the right buttons.
2. Then, any properties included in either leftButtonStyles or rightButtonStyles will be used as overrides for their associated buttons. This means that defining the same style in buttonStyles and leftButtonStyles will ignore the one in buttonStyles for the left button.
3. When a carousel button is hovered, the same process used in 1. and 2. above will be used to determine the new style of each button. All of the associated button's hover styles will also override the normal styles if they are defined in both places.

This heirarchy essentially allows you to define general styles for both buttons using buttonStyles and buttonHoverStyles, and then fine tune each button individually using their associated properties. In fact, the default Freighter styles used as fallbacks do this very thing, and can be seen of the API documentation.

The ButtonStyle object

As seen in the container properties and item properties, each key in the CarouselProperties object previously accepted a simple type, whether that be a number, boolean, string, etc. Because the carousel buttons themselves are more complex in their styling and properties, it makes more sense to abstract out their properties into up to 6 ButtonStyle objects that can be assigned to 6 keys in the main CarouselProperties object. For a better breakdown of the CarouselProperties object, see this section of the Freighter API documentation.

Below, each property of the ButtonStyle object is described in full.

width

This property, which accepts any valid CSS width string, determines the width of a carousel button. Note that because the width is not restricted to the px unit, percentages and viewport units can be used. When percentages are used, they refer to the width of the carousel's container element.

height

This property, which accepts any valid CSS height string, determines the height of a carousel button. Note that because the height is not restricted to the px unit, percentages and viewport units can be used. When percentages are used, they refer to the height of the carousel's container element.

Be sure to use caution when setting the height property to a value larger than the height of the carousel container. Note that using percentages or viewport units can cause the buttons to change height as the carousel container or viewport size changes.

position

This property accepts a value of "top" | "center"| "bottom" and is used to determine the position of each carousel button. These values are all relative to the carousel container itself, and the property defaults to "center". Check out the example below which positions the left and right buttons at the top and bottom of the carousel container, respectively.

const myCarousel = new Freighter(
  'myCarousel', 'stretch-scale', 'none', {
  numItemsVisible: 2,
  scrollBy: 2,
  itemSpacing: 30,
  leftButtonStyles: {
    position: 'top',
    borderTopLeftRadius: '10px',
  },
  rightButtonStyles: {
    position: 'bottom',
    borderBottomRightRadius: '10px',
  },
});

Notice that because the height of each button has a value that is a percentage of the carousel container, changing the height of the container prevents the buttons from overflowing.

border and borderRadius Properties

There are 8 border-like and borderRadius-like ButtonStyle properties that can be used to fully customize your carousel control buttons:

The idea behind seperating these out comes from the fact that left and right buttons will often need seperate styling for borders and border radii in order to better fit the carousel container. For example, the default carousel buttons each utilize different borderRadius-like properties to get rounded corners on one side only. Each property accepts any valid CSS string that could be used for a border or border radius property value.

backgroundColor

This property determines the color for the carousel buttons. Note that the chevron (arrow) inside of each button is not affected by this property; only the button element itself changes color when changing this property.

Any valid CSS color string can be used here, including rgba() colors that introduce opacity. The default color is a slightly-transparent light darkish gray.

color

The color property is responsible only for giving the chevron (arrow) inside of the carousel buttons a color. Any valid CSS color string can be used, and the default value is a slightly-transparent dark gray.

cursor

This property, which takes the value of any valid CSS 'cursor' value, is used to determine the appearance of the user's cursor when hovering over a carousel button. By default, this property is set to cursor to indicate that the user is able to scroll manually with a click.

transition

This property determines the transition that should be used when the user hovers over a carousel button. More specifically, this property determines the transition used when changing between buttonStyles styles and buttonHoverStyles styles, assignable for any of the 3 variations (left, right, and both).

Unlike the CarouselProperties transition properties, the transition property for a ButtonStyle object includes duration, delay, and transition timing function all within the same string. By default, the value is set to all 200ms ease in order to provide a smooth transition.