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.1.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.

New in v2.1.0: Fluid Layout!

If I had a nickel for every time responsive layouts were requested, I could probably afford a fastfood lunch. With Kwicks v2.1.0, I'm happy to announce that fluid layouts are finally here! Previously, the container element needed to have fixed dimensions. As of v2.1.0, containers may be completely fluid. To make this practical, the following additions have been made:

  • maxSize and minSize may now be specified in pixels or as a percentage.
  • Panel dimensions are recalculated automatically when the window itself is resized.
    • ...unless autoResize is set to false.
    • Resize logic can be trigger manually as well, through the $(container).kwicks('resize') method.
  • The size option has been rendered obsolete, so it has been completely removed.

Getting Started

Dependencies

Source

Kwicks is available on GitHub. You can download Kwicks 2.1.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);

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)

The distance (in pixels) separating each panel.

Default: 5

duration:(Type: number)

The number of milliseconds for the animation to run.

Default: 500

isVertical:(Type: bool)

Indicates whether or not the panels should be arranged vertically.

Default: false

easing:(Type: string)

The name of the easing function to use for the animation.

Default: none

behavior:(Type: string)

Indicates if/what out-of-the-box behavior should be enabled. By far the most common request I received from earlier versions was the ability to "peak" on hover and "select" on click, so this is what the "menu" behavior provides. Now the most common request I get is how to make it do something other than the menu behavior...

Please note that Kwicks behavior should primarily be controlled through the API methods (below), so if the "menu" behavior doesn't suit your needs, keep reading! :)

Possible values: 'menu'

Default: none

autoResize:(Type: bool)

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

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,

$(panel).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:

$(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');

events

Certain 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.
  • 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: