Core

Core is the module providing main Tiny Carousel functionalities and API. It exports the TinyCarousel class.

Styling

Styling can be imported via:

Sass: @frsource/tiny-carousel-core/src/index.scss

CSS: @frsource/tiny-carousel-core/dist/index.css

When importing Sass source file you can configure the variables:

• Sass variables:

  • {string} $frs-tc-class-name = "frs-tc"
  • {string} $frs-tc-class-name-overflow = "frs-tc--o"
  • {string} $frs-tc-item-class-name = "frs-tc-item"

• Details:

  • $frs-tc-class-name is a class name added to the carousel element
  • $frs-tc-class-name-overflow is a class name added to the carousel element when overflow option is set to true
  • $frs-tc-item-class-name is a class name added to the carousel items (slides)

TIP

Every SCSS variable should be changed together with a corresponding Config option.

• Example:

$frs-tc-class-name: "some-custom-classname";
@import "~@frsource/tiny-carousel-core";

TIP

This packages uses @frsource/frs-hide-scrollbar to hide native scrollbars. So, when importing the core Sass styling you have a possibility to set @frsource/frs-hide-scrollbar configuration beforehand. For example, this might be useful to change the default frs-hide-scroll class name:

$frs-hide-scroll-classname: "your-new-hide-scroll-classname";
@import '~@frsource/tiny-carousel-core';

Global API

updateDefaultConfig( config )

• Arguments:

  • {Config} config

• Returns: undefined

• Usage:

  Method used for changing the default configuration of the whole TinyCarousel module. Every instance created afterwards will use updated default configuration. The argument config is merged with previous configuration which means that to remove property you’d need to pass it explicitly set to undefined.

• See also: Config data type description

defaultConfig

• Type: Config

• Read only

• Details:

  Property returning copy of the default configuration object.

• See also: Config data type description

new TinyCarousel( carouselElement, config )

• Arguments:

  • {HTMLElement} carouselElement
  • {Config} config <optional>

• Returns: New, uninitialized Tiny Carousel instance

• Usage:

  Carousel wrapper element should be passed ad carouselElement. Every of the config properties (and the config object itself) are optional.

• See also: Config data type description

Instance properties

carousel.config

• Type: Config

• Details:

  Configuration object of the Tiny Carousel instance.

• See also: Config data type description

carousel.carouselElement

• Type: HTMLElement

• Details:

  Main wrapper element of the carousel.

carousel.active

• Type: number

• Read only

• Details:

  Active slide index.

Instance methods

carousel.use

• Arguments:

  • {PluginDefinition} pluginDefinition
  • {unknown[]} ...args <optional>

• Returns: this - this TinyCarousel instance (for chaining purposes)

• Usage:

  Method used to setup any of the Tiny Carousel plugins. Number of arguments and their types are dependent on what plugin is being installed. For details, head to the documentation of the plugin you’d like to use.

carousel.init

• Arguments: None

• Returns: this - this TinyCarousel instance (for chaining purposes)

• Usage:

  Initializes a TinyCarousel instance. If no config.items were set yet the library will fallback to the value returned by carousel.findPossibleItems method. Also, this method adds class names to the carousel wrapper and carousel items HTML elements and sets the correct active slide based on config.active variable.

carousel.destroy

• Arguments: None

• Returns: this - this TinyCarousel instance (for chaining purposes)

• Usage:

  Deregisters every event handler bound by the carousel and its plugins. Use this method before you’d like to remove the carousel or to reinitialize it (together with carousel.init method).

carousel.goTo

• Arguments:

  • {number} index

• Returns: this - this TinyCarousel instance (for chaining purposes)

• Usage:

  Method which allows to change the current slide. index parameter should be any numeric value (even negated).

  • For index values less than 0, the new active slide is counted from the end of items array. For example: when there are 3 slides and carousel.goTo(-1) is called, the new active index will be 3 - because that’s the last index in the config.items array
  • For index values bigger than the number of items or smaller than the negated number of items, number of items will be subtracted/added to the index value. Whole operation will be repeated until index is within the range from negated items array length to items array length

carousel.next

• Arguments: None

• Returns: same as goTo method

• Usage:

  Syntax sugar for changing the active slide to the next one. Same as carousel.goTo(carousel.active + 1).

carousel.prev

• Arguments: None

• Returns: same as goTo method. Additionally, returns false when carousel.active equals 0

• Usage:

  Syntax sugar for changing the active slide to the previous one. Same as carousel.goTo(carousel.active - 1).

carousel.resetActive

• Arguments: None

• Returns: undefined

• Usage:

  Use with caution! This method is used for flushing of the cached carousel.active value. It should be used whenever you need to force active index recalculation during next carousel operation.

TIP

To recalculate carousel.active in place, call carousel.resetActive and then try to access carousel.active property. Getter will provide you with new value.

carousel.findPossibleItems

• Arguments: None

• Returns: HTMLElement[] - an array of the possible slides. The return value is:

  • The carouselElement children which have config.itemClassName class name set,
  • (if the step above doesn’t find any item) all carouselElement children

• Usage:

  Method which finds possible carousel items. Called as a item-gathering fallback by the constructor.

Options

Config

• Properties:

  • {number} active = 0
  • {string} className = "frs-tc"
  • {string} classNameOverflow = "frs-tc--o"
  • {string} itemClassName = "frs-tc-item"
  • {string} hideScrollClassName = "frs-hide-scroll"
  • {boolean} overflow = true
  • HTMLElement[] items = []

• Details:

  Data type which holds most of the Tiny Carousel configuration. To be changed together with SCSS variables - more in the styling section.

  • active index of the item which should be activated during carousel initialization
  • overflow allows toggling the overflow behavior on/off

TIP

When changing hideScrollClassName always remember to change the $frs-hide-scroll Sass variable as well. More information available in the styling section or @frsource/frs-hide-scrollbar documentation.

PluginDefinition

• Methods:

  • install( instance, args ) - method called by carousel.use during plugin installation

• Details:

  Data type describing general interface which needs to be implemented by every plugin in the Tiny Carousel ecosystem.