Kwicks for jQuery (v2.2.1)

Welcome to the Kwicks for jQuery home page. Kwicks is a plugin providing sexy sliding panels with an emphasis on navigational interaction. Kwicks was originally a port of a MooTools effect (of the same name), but has since evolved into a highly configurable and versatile UI component. Please check out the examples to see it in action.

Options

The following options may be specified when instantiating a new Kwicks instance:

maxSize|minSize:(Type: number|string)

The width or height of a fully expanded|collapsed panel. If the value is a number, then the unit will be px. If the value is a string, then the units must be specified (px or %).

Examples: 400, '250px', '20%'

Please note that % dimensions are calculated based on the remainder after spacing has been removed (see the spacing option).

If isVertical is true, then minSize and maxSize refer to the height of the panel, otherwise they refer to the width.

Note that you may specify maxSize OR minSize, but not both.

Default: realistically, you're going to want to set this, but if you don't Kwicks will attempt to identify some reasonable behavior.

spacing:(Type: number|string)

The distance separating each panel. This option follows the same pattern as minSize and maxSize: if the value is a number, then the unit will be px. If the value is a string, then the units must be specified (px or %).

If the specified unit is %, then the spacing is a percentage of the container's size.

Indicates whether or not Kwicks should automatically resize itself based on window resizes.

If this is disabled (or a container resize occurs due to something other than a window resize), you may use the $(container).kwicks('resize') method to trigger the resize logic manually.

Default: true

behavior:(Type: string)

Indicates if/what out-of-the-box behavior should be enabled. These are provided purely as a convenience for common interactions, so if one of these doesn't satisfy your needs, please continue reading below on how to control Kwicks programmatically.

Default: none

Possible values:

'menu'

By default, the menu behavior expands panels on mouseenter, selects panels on click, and reverts all panels to a default state when the mouse leaves the container.

This behavior exposes some additional menu-only options to customize these interactions:

delayMouseIn:(Type: number)

The number of milliseconds to wait before expanding a panel on mouseenter.

Default:0

delayMouseOut:(Type: number)

The number of milliseconds to wait before reverting panels to a default state when the mouse leaves the container.

Default:0

selectOnClick:(Type: bool)

Indicates whether or not panels should be selected on click.

Default:true

deselectOnClick:(Type: bool)

Indicates whether or not currently selected panels should be deselected on click.

Default:false

'slideshow'

By default, the slideshow behavior configures successively panels to automatically expand at a regular interval. Additionally, mouseenter causes the progression to "pause" and the hovered panel to expand. Once the mouse leaves, the slideshow behavior resumes.

This behavior exposes some additional slideshow-only options to customize these interactions:

interval:(Type: number)

The number of milliseconds to wait before expanding the next panel.

Default:2500

interactive:(Type: bool)

Indicates whether or not the mouse interactions described above should be enabled.

Default:true

Methods

Kwicks provides several API methods that may be used for programmatic control and inspection of the plugin.

expand

Expands the panel with the specified index (use -1 to expand none).

$(container).kwicks('expand', index);

Alternatively, the expand method may also be invoked directly on a panel (rather than the container). For example,

$(container).children().eq(2).kwicks('expand');

...performs the same action as...

$(container).kwicks('expand', 2);

Sometimes it's useful to provide a slight delay before expanding a panel. To support this, the expand method may be given a delay option (specified in milliseconds):

$(container).kwicks('expand', 3, { delay: 500 });

expanded

Returns the index of the currently expanded panel (or -1 if no panels are expanded).

var index = $(container).kwicks('expanded');

select

Selects the panel with the specified index (use -1 to select none). Please note that most use cases will not require the use of select. Calling select has the same effect as calling expand, except that select is stateful. That is, once a panel has been selected, it will maintain that state even after other panels have been expanded. When $(element).kwicks('expand', -1); is invoked, the currently selected panel will be expanded, if it exists.

$(container).kwicks('select', index);

Just like expand, select may also be invoked directly on a panel:

$(panel).kwicks('select');

Note: if you want a panel to be automatically selected on initialization, simply add a kwicks-selected class to its markup.

selected

Returns the index of the currently selected panel (or -1 if no panels are selected).

var index = $(container).kwicks('selected');

resize

Forces panel dimensions to be recalculated in response to a potential change in the container dimensions. This can be useful if the autoResize option has been disabled, or if a container resize occurs due to something other than a window resize.

$(container).kwicks('resize');

destroy

Removes the kwicks functionality completely. All classes, style attributes, and event handlers added by the kwicks plugin are reverted.

$(container).kwicks('destroy');

Class Names

Kwicks adds several different classes to the DOM elements that may be useful for styling purposes.

kwicks

If not already present, Kwicks will add this class to the container element.

kwicks-horizontal|kwicks-vertical

If not already present, Kwicks will add the appropriate orientation class to the container element.

kwicks-processed

This is intended purely for internal use, and is added to the container element once the plugin has been initialized.

kwicks-expanded

The currently expanded panel (if there is one) will be given this class.

kwicks-collapsed

Whenever a panel is expanded, all other panels are given this class.

kwicks-selected

The currently selected panel (if there is one) will be given this class.

Note that if you'd like a panel to be selected on initialization, you may add this class to your markup.

Events

Certain Kwicks interactions trigger events that can be used to react to (or cancel) behavior.

Browser Support

Special Considerations

Important styling information: Please note that in order to provide the smoothest possible animations, the following style changes are made by the script:

The Kwicks container is converted to relative positioning.

All panels are converted to absolute positioning.

To keep things as "jitter free" as possible, panel styles are set by overriding the whole style attribute, which currently causes any previously specified inline styles to be lost. Make sure any styles you want to keep are set externally with a selector, rather than inline.

Margins on the panels are stripped, but the spacing option is respected through the absolute positioning.

Even though the panels' margins are stripped, in order for them to look correct in non-JS enabled browsers, they should still be given margins that correspond to the spacing option (if any). I strongly recommend that you look at the CSS in the examples.

Bugs, feature requests, etc:

Anything pertaining to bugs and/or the development of Kwicks can be dicussed on the GitHub issue queue.

Previous Versions

What I've been up to:

I've recently accepted the role of CTO for a
company called InfiniteTakes. If something on
this site has been useful to you, please
consider downloading our free app for streaming live video from your mobile device: