Please note: This page provides documentation for an old version of Kwicks. If possible, you should check out the latest version instead.

Kwicks for jQuery (v2.0.0)

Welcome to the Kwicks for jQuery home page. Kwicks for jQuery 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.

Getting Started

Dependencies

Source

Kwicks is available on GitHub. You can download Kwicks 2.0 (with examples) here [zip], or browse the source here.

Markup

Kwicks has pretty relaxed markup requirements:

  1. A container element with two classes: kwicks and kwicks-horizontal|vertical (depending on the orientation of this instance).

  2. A single level of nested "panel" elements.

Unordered lists are a good semantic fit for most Kwicks use cases:

<ul class='kwicks kwicks-horizontal'>
    <li></li>
    <li></li>
    <li></li>
    <li></li>
</ul>

However, as noted above, Kwicks doesn't require that unordered lists be used. For example, see the Anchor Markup example.

If you want one of the panels to be selected on initialization, simply add a kwicks-selected class to it.

The Code

Kwicks follows the usual jQuery plugin convention:

// instantiate kwicks
$(element).kwicks(opts);

// invoke a method
$(element).kwicks('method-name' [, param]);

// handle events
$(element).on('event-name.kwicks', handler);

Unfortunately, contrary to jQuery convention, I haven't figured out how to make all configurations optional in a way that makes sense. Be sure to read the configuration info below, and check out the examples to see them in use.

Configuration

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

size:(Required)

The width or height (in pixels) of a panel in its "default" state (neither expanded nor collapsed). If isVertical is true, then size refers to the height of the panel, otherwise it refers to the width. This value is used along with spacing to calculate the overall size of the Kwicks container.

maxSize|minSize:(Required)

The width or height (in pixels) of a fully expanded|collapsed panel.

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

spacing:(Default: 5)

The distance (in pixels) separating each panel.

duration:(Default: 500)

The number of milliseconds for the animation to run.

isVertical:(Default: false)

Indicates whether or not the panels should be arranged vertically.

easing:(Default: none)

A custom easing function for the animation (requires easing plugin).

behavior:(Default: none)

Indicates if/what out-of-the-box behavior should be enabled. So far I've only included one possible value here: "menu" (used in several of the demos). By far the most common request I received from the previous version was the ability to "peak" on hover and "select" on click, so this is what the "menu" behavior will set up for you. If other popular use cases arise, I'll consider adding them here.

Methods

Kwicks provides four 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(index).kwicks('expand');

...performs the same action as the previous example

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:

$(container).children().eq(index).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');

events

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

expand.kwicks

Fired before a panel is expanded.

$(container).on('expand.kwicks', function(e, data) {
    // panel index
    console.log(data.index);

    // e.target is the panel, unless we're expanding "none"
    if (data.index === -1) {
        // e.target is the container node
    } else {
        // e.target is the panel to be expanded
    }

    // prevent the panel from expanding
    e.preventDefault();
});
select.kwicks

Same behavior as expand.kwicks, except that it is (obviously) triggered before a panel is selected:

$(container).on('select.kwicks', function(e, data) {
    // panel index
    console.log(data.index);

    // e.target is the panel, unless we're selecting "none"
    if (data.index === -1) {
        // e.target is the container node
    } else {
        // e.target is the panel to be selected
    }

    // prevent the panel from being selected
    e.preventDefault();
});

Browser Support

Kwicks is supported in the following browsers:

  • Chrome 12+
  • FF 3.6+
  • IE7+
  • Opera 11+
  • Safari 5+

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.
  • The width and height of the container is set to be consistent with the width and height of the panels (spacing included).
  • 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.

Panel classes: Whenever a panel is expanded and/or selected, it is automatically given a kwicks-expanded and/or kwicks-selected class. This allows for more flexible styling based on the state of the panel.

Bugs, feature requests, etc:

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

Previous Versions

Downloads, documentation, and examples for previous versions: