API

Options

General
filter selectedIndex distance numberOfElementsToDisplayRight numberOfElementsToDisplayLeft enabled designedForWidth designedForHeight fallback distanceInFallbackMode
Scene
scaleX scaleY scaleZ path.settings.shiftX path.settings.shiftY path.settings.shiftZ path.settings.rotationAngleXY path.settings.rotationAngleZY path.settings.rotationAngleZX path.settings.rotateElements perspective mode3D
Motion
rotationAnimationEasing rotationAnimationDuration sensitivity minKeyDownFrequency verticalRotation mousewheelEnabledv1.5 keyboardEnabledv1.5 gesturesEnabledv1.6 inertiaFriction inertiaHighFriction autorotation autorotationDirection autorotationPause
Path
path.type path.settings.endless path.settings for parabola path.settings.wideness path.settings for cubic path.settings.wideness path.settings for archimedes_spiral path.settings.fi path.settings.flatness path.settings for ellipse path.settings.a path.settings.b path.settings for cubic_bezier path.settings.pathLength path.settings.zeroPosition path.settings.width path.settings.height path.settings.xyPathBezierPoints path.settings.xzPathBezierPoints path.settings.depth path.settings.xyArcLengthBezierPoints
Effects
allignElementsWithPath allignElementsWithPathCoefficient shadow shadowBlurRadius shadowSpreadRadius fadeAway fadeAwayNumberOfConfigurableElements fadeAwayBezierPoints rotation rotationNumberOfConfigurableElements rotationBezierPoints rotationVectorX rotationVectorY rotationVectorZ rotationInvertForNegative sizeAdjustment sizeAdjustmentNumberOfConfigurableElements sizeAdjustmentBezierPoints popoutSelected popoutSelectedShiftX popoutSelectedShiftY popoutSelectedShiftZ reflection reflectionBelow reflectionHeight

Options

filter

Description: Selector of the carousel items.

Type: String

Default: "div"

selectedIndex

Description: Index of the selected item.

Type: Number

Default: 0

distance

Description: Distance between items.

Type: Number

Default: 70

numberOfElementsToDisplayRight

Description: The number of visible items to the right.

Type: Number

Default: null

numberOfElementsToDisplayLeft

Description: The number of visible items to the left.

Type: Number

Default: null

enabled

Description: Indicates whether the carousel can respond to user interaction.

Type: bool

Default: true

designedForWidth

Description: The carousel width defined during configuration. This value is used while scaling.

Type: Number

Default: null

designedForHeight

Description: The carousel height defined during configuration. This value is used while scaling.

Type: Number

Default: null

fallback

Description: Fallback mode. In fallback mode carousel does not use any 3D transformations and displays all items as a plain horizontal list.

Type: String

Default: "auto"

Property Values:

"auto" Carousel automatically detects if browser support 3D transformations, and uses fallback mode if it doesn't.

"always" Always use fallback mode.

"never" Never use fallback mode.

distanceInFallbackMode

Description: Distance between carousel element's centers in fallback mode.

Type: Number

Default: 200

mode3D

Description: 3D mode.

Type: String

Default: "z"

Property Values:

"z" Real 3D.

"scale" Simulated 3D mode that is based on object scaling. 'Scale' differs from 'Real 3D' in that with distance along the Z axis items do not shift to the center of the scene.

scaleX

Description: Scaling the scene along the X-axis.

Type: Number

Default: 1

scaleY

Description: Scaling the scene along the Y-axis.

Type: Number

Default: 1

scaleZ

Description: Scaling the scene along the Z-axis.

Type: Number

Default: 1

path.settings.shiftX

Description: Shifting the scene along the X-axis.

Type: Number

Default: 0

path.settings.shiftY

Description: Shifting the scene along the Y-axis.

Type: Number

Default: 0

path.settings.shiftZ

Description: Shifting the scene along the Z-axis.

Type: Number

Default: 0

path.settings.rotationAngleXY

Description: Rotating the scene in the X-Y plane.

Type: Number

Default: 0

path.settings.rotationAngleZX

Description: Rotating the scene in the Z-X plane.

Type: Number

Default: 0

path.settings.rotationAngleZY

Description: Rotating the scene in the Z-Y plane.

Type: Number

Default: 0

path.settings.rotateElements

Description: Applying path.settings.rotationAngleXY, path.settings.rotationAngleZY, path.settings.rotationAngleZX not only to rotaion path but also to element's plane.

Type: bool

Default: false

perspective

Description: Perspective. The larger the perspective, the less impact the distance along the Z-axis has on the object size.

Type: Number

Default: 1000

mode3D

Description: 3D mode.

Type: String

Default: "z"

Property Values:

"z" Real 3D.

"scale" Simulated 3D mode that is based on object scaling. 'Scale' differs from 'Real 3D' in that with distance along the Z axis items do not shift to the center of the scene.

rotationAnimationEasing

Description: Defines the velocity curve when the carousel changes its position. Effects one position shift only. When rotation involves several position shifts, the easing velocity remains the same.

Type: String

Default: "easeOutCubic"

rotationAnimationDuration

Description: Duration of one rotation of the carousel.

Type: Number

Default: 500

sensitivity

Description: Sensitivity to mouse movements and touches. Negative values make the carousel move in the direction that is opposite to the mouse direction.

Type: Number

Default: 1

minKeyDownFrequency

Description: The carousel ignores key board hits done after the last interval that is shorter than the specified value.

Type: Number

Default: 0

verticalRotation

Description: Gesture recognition mode. False - horisontal gestures, true vertical gestures.

Type: bool

Default: false

mousewheelEnabledv1.5

Description: If False the carousel does not process mousewheel events.

Type: bool

Default: true

keyboardEnabledv1.5

Description: If False the carousel does not process keyboard events.

Type: bool

Default: true

gesturesEnabledv1.6

Description: If False the carousel does not react on mouse and touch gestures.

Type: bool

Default: true

inertiaFriction

Description: The friction parameter in the physical model of inertia movement. Effects how far the carousel will be rotated after the user releases the mouse key.

Type: Number

Default: 10

inertiaHighFriction

Description: The friction parameter in the physical movement model behind the extreme right and left positions of the carousel.

Type: Number

Default: 50

autorotation

Description: If true, carousel rotates automatically.

Type: bool

Default: false

autorotationDirection

Description: Direction of automatic rotation.

Type: String

Default: "right"

Property Values:

"right"

"left"

autorotationPause

Description: Pause in milliseconds between auto-rotation steps.

Type: Number

Default: 0

path.type

Description: The path along which the items are arranged.

Type: String

Default: "parabola"

Property Values:

"line" Line.

"parabola" Parabola.

"cubic" Cubic parabola.

"archimedes_spiral" Archimedes’ spiral.

"ellipse" Ellipse.

"cubic_bezier" Cubic Bezier curve.

path.settings.endless

Description: Circular rotation.

Type: bool

Default: false

path.settings for parabola
path.settings.wideness

Description: Width of parabola branches.

Type: Number

Default: 200

path.settings for cubic
path.settings.wideness

Description: Width of parabola branches.

Type: Number

Default: 200

path.settings for archimedes_spiral
path.settings.fi

Description: Distance between the spiral rings.

Type: Number

Default: 10

path.settings.flatness

Description: Indicates how flat the spiral is in the Z-axis. When set to '0', all items reside in the same plane. The larger the value, the more distant the items are from the current one in the Z-axis.

Type: Number

Default: 10

path.settings for ellipse
path.settings.a

Description: Width.

Type: Number

Default: 200

path.settings.b

Description: Depth.

Type: Number

Default: 200

path.settings for cubic_bezier
path.settings.pathLength

Description: The entire curve length. Together with the distance parameter defines the number of items that can be displayed in the curve at a time.

Type: Number

Default: 1000

path.settings.zeroPosition

Description: Position in the curve which defines location of the selected item.

Type: Number

Default: 0.5

path.settings.width

Description: Curve width.

Type: Number

Default: 1000

path.settings.height

Description: Curve height.

Type: Number

Default: 1000

path.settings.xyPathBezierPoints

Description: Bezier curve in the X-Y plane.

Type: Object

Default: { p1: { x: -100, y: 0 }, p2: { x: 0, y: 0 }, p3: { x: 0, y: 0 }, p4: { x: 100, y: 0 } }

path.settings.xzPathBezierPoints

Description: Bezier curve in the X-Z plane. The setting is used only if path.settings.depth is not '0'.

Type: Object

Default: { p1: { x: -100, y: 0 }, p2: { x: 0, y: 0 }, p3: { x: 0, y: 0 }, p4: { x: 100, y: 0 } }

path.settings.depth

Description: Curve depth.

Type: Number

Default: 1000

path.settings.xyArcLengthBezierPoints

Description: Bezier curve that defines the distribution density of items in the main path.

Type: Object

Default: { p1: { x: 0, y: 0 }, p2: { x: 50, y: 50 }, p3: { x: 50, y: 50 }, p4: { x: 100, y: 100 } }

allignElementsWithPath

Description: Aligns the items to the path.

Type: bool

Default: false

allignElementsWithPathCoefficient

Description: Rotation factor.

Type: Number

Default: 1

shadow

Description: Applies the shadow effect.

Type: bool

Default: false

shadowBlurRadius

Description: Blur radius.

Type: Number

Default: 100

shadowSpreadRadius

Description: Shadow radius.

Type: Number

Default: 0

fadeAway

Description: Transparency of distant items.

Type: bool

Default: false

fadeAwayNumberOfConfigurableElements

Description: The number of items to the left and to the right of the item to which the configuration is applicable. All items located farther will be as transparent as the last item that is being configured.

Type: Number

Default: 5

fadeAwayBezierPoints

Description: Cubic Bezier curve defines the change of transparency in the interval starting from the current one with the length defined by fadeAwayNumberOfConfigurableElements.

Type: Object

Default: { p1: { x: 0, y: 100 }, p2: { x: 50, y: 50 }, p3: { x: 50, y: 50 }, p4: { x: 100, y: 0 } }

rotation

Description: Rotation of items.

Type: bool

Default: false

rotationNumberOfConfigurableElements

Description: The number of items to the left and to the right of the item to which the configuration is applicable. All elements located farther will have the same rotation factor as the last item that is being configured.

Type: Number

Default: 5

rotationBezierPoints

Description: Cubic Bezier curve defines the change of rotation factor of the item in the interval starting from the current one with the length defined by rotationNumberOfConfigurableElements.

Type: Object

Default: { p1: { x: 0, y: 0 }, p2: { x: 50, y: 0 }, p3: { x: 50, y: 0 }, p4: { x: 100, y: 0 } }

rotationVectorX

Description: X-coordinate of the vector around which the rotation occurs.

Type: Number

Default: 0

rotationVectorY

Description: Y-coordinate of the vector around which the rotation occurs.

Type: Number

Default: 0

rotationVectorZ

Description: Z-coordinate of the vector around which the rotation occurs.

Type: Number

Default: 0

rotationInvertForNegative

Description: Inverts rotation to the negative for items located to the left of the selected one.

Type: bool

Default: false

sizeAdjustment

Description: Size adjustment of the object.

Type: bool

Default: false

sizeAdjustmentNumberOfConfigurableElements

Description: The number of items to the left and to the right of the item to which the configuration is applicable. All elements located farther will have the same size adjustmen as the last item that is being configured.

Type: Number

Default: 5

sizeAdjustmentBezierPoints

Description: Cubic Bezier curve defines the change of size adjustment of the item in the interval starting from the current one with the length defined by sizeAdjustmentNumberOfConfigurableElements.

Type: Object

Default: { p1: { x: 0, y: 100 }, p2: { x: 50, y: 100 }, p3: { x: 50, y: 100 }, p4: { x: 100, y: 100 } }

popoutSelected

Description: Shift of the selected item.

Type: bool

Default: false

popoutSelectedShiftX

Description: Shift along the X-axis.

Type: Number

Default: 0

popoutSelectedShiftY

Description: Shift along the Y-axis.

Type: Number

Default: 0

popoutSelectedShiftZ

Description: Shift along the Z-axis.

Type: Number

Default: 0

reflection

Description: Reflection of elements.

Type: bool

Default: false

reflectionBelow

Description: Distance between the element and the reflection.

Type: Number

Default: 0

reflectionHeight

Description: Indicates the size of the reflection.

Type: Number

Default: 0

Methods

moveTo( index )

Description: Moves the carousel to the item defined in the parameter.


index

Type: Number

moveBack( )

Description: Moves the carousel one position to the right.

moveForward( )

Description: Moves the carousel one position to the left.

getIsInMotion( )

Description: Returns true if the carousel is now in motion, and false otherwise.

getIsFallbackMode( )

Description: Returns true if the carousel is in fallback mode, and false otherwise.

invalidate( )

Description: Updates the positions of all items of the carousel.

update( )v1.4

Description: Updates the carousel when some items has been added or deleted.

destroy( )

Description: Removes all event handlers added by the carousel from the DOM objects.

Events

change

Description: The index of the object has been changed.

Handler Example:

function (e, data) {
    console.log(data.index); // selectedIndex
};

motionStart

Description: The carousel started its motion.

Handler Example:

function (e, data) {
    console.log(data.index); // selectedIndex
};

motionEnd

Description: The carousel ended its motion.

Handler Example:

function (e, data) {
    console.log(data.index); // selectedIndex
};

How to...

Adding Carousel to a Web page

The carousel has been designed as a jQuery plug-in. Thus, to add it to a Web page is as easy as any other plug-in.

$('selector').theta_carousel({ /*options*/ });

Add carousel to a AngularJS appv1.6

Starting from version 1.6.0 Theta Carousel includes AngularJS directive. To use Theta Carousel in your AngularJS App yo need:

  1. Add theta-carousel-angular-directive.min.js to your code.
    <script src="theta-carousel-angular-directive.min.js"></script>
  2. Add the theta module as a dependency to your application module.
    angular.module('MyApp', ['theta'])
  3. Add theta-crousel tag to your markap
    <theta-crousel ng-model="controller.items"
        selected-index="controller.selectedItemIndex">
            <div ng-repeat="item in controller.items">
                ....
            </div>
    </theta-crousel>
  4. Configure carousle using our visual Configurator.
  5. Get carousel tag snippet using "Get AngularJS Tag" button, and put it into your markap.

Configurator

The rich API allows configuring practically any aspect of the carousel behavior from visual effects to the parameters of physical model. To facilitate understanding of some complex parameters, we designed the Configurator. It allows changing any parameter of the carousel in interactive mode and see how the change effects the carousel behavior. This makes the configuration process fast, easy, intuitive and even engaging. After the carousel configuration is over, click the Get Script button to instantly get the configuration script. The Configurator is not built-in in the carousel, which eliminates the issue of downloading excessive scripts. To start the Configurator, simply run the following script in the browser console:

(function(id) {
    var js, hjs = document.getElementsByTagName('script')[0];
    if (document.getElementById(id)) return;
    js = document.createElement('script'); 
    js.id = id;
    js.src = "http://theta-carousel.com/scripts/boot.js";
    hjs.parentNode.insertBefore(js, hjs);
}('theta-carousel-config'));

This script downloads the Configurator directly from our website. Once the Configurator is downloaded, hover over the mouse on the carousel to view the Configure button in the upper-right corner. By clicking the button, you will launch the configuration interface.

Method invocation

The carousel has been designed as a jQuery plug-in. Thus, you can use the same method invocation syntax as for any other plug-in.

$('selector').theta_carousel('moveForward');
// or
$('selector').theta_carousel('moveTo', 10); // for methods with arguments

Bind an event listener to event

The carousel has been designed as a jQuery plug-in. Thus, you can use the same event listener attaching syntax as for any other plug-in.

$('selector').on('change', function(e, data){

});

Update property value

The carousel has been designed as a jQuery plug-in. Thus, you can use the same update property syntax as for any other plug-in.

$('selector').theta_carousel({
    'path.settings.shiftZ': 0,
    'path.settings.shiftY': 0,
    'path.settings.a': 500,
    'path.settings.b': 500
});

Get property value

The carousel has been designed as a jQuery plug-in. Thus, you can use the same get property syntax as for any other plug-in.

$('selector').theta_carousel('option', 'path.settings.shiftZ');

Get carousel version number

To get the version of theta carousel that you use, just execute the following code in browser console:

$.theta.carousel.version;