DevSmash Developer Portal

Kwicks for jQuery

Overview

Welcome to the Kwicks for jQuery home page. Kwicks for jQuery started off as a port of the insatiably attractive Mootools effect (of the same name), but has evolved into a highly customizable and versatile widget. Please check out the examples to see it in action. Thank you for visiting!

Download

The latest version of Kwicks can be found at the following links:

Please note that Kwicks 1.5.1 fixes a bug in IE7+ (it was my fault, not theirs). A special thanks goes out to Rúbel Mujica who identified, diagnosed, and even prescribed the correct fix for this bug (original comment).

Other than grabbing the new plugin version, no code changes are required to implement this release. I also threw in some very minor performance related tweaks, but you will likely not notice any differences in those regards.

For older versions, feel free to browse the repository.

Documentation

Kwicks Options

The following options are provided:

max: Required*
The width or height (in pixels) of a fully expanded kwick element. If isVertical is true, then max refers to the height - otherwise it is the width.

* You must provide max OR min, but not both.
min: Required*
The width or height (in pixels) of a fully collapsed kwick element. If isVertical is true, then min refers to the height - otherwise it is the width.

* You must provide max OR min, but not both.
isVertical: Defaults to false
Kwicks will align vertically if true.
sticky: Defaults to false
One kwick will always be expanded if true.
defaultKwick: Defaults to 0
The initially expanded kwick (if and only if sticky is true).
Note: Zero based, left-to-right (or top-to-bottom).
event: Defaults to 'mouseover'
The event that triggers the expand effect. Other likely candidates are click and dblclick.
duration: Defaults to 200
The number of milliseconds required for each animation to complete.
easing:
A custom easing function for the animation (requires easing plugin).
spacing: Defaults to 0
The width (in pixels) separating each kwick element.

Special Considerations

Potential Safari 3.1.1 issue: If your stylesheets are included below your JavaScript references, Safari 3.1.1 will execute the code before the CSS is applied. Since the script relies on some of these styles, you will see unexpected results. To avoid this problem, simply insure that your stylesheets are included above your JavaScript references.

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

  • All kwicks are converted to absolute positioning.
  • Margins on the kwicks are stripped, but the spacing option is respected through absolute positioning.
  • The height of the containing ul tag is set to match the height of the kwick elements.
  • The width of the containing ul tag is set to match the width and spacing of all the kwick elements combined.

Even though the kwicks' 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 commented css file contained in the Kwicks example.

Lastly, note that the "active" (expanded/expanding) kwick is given an extra class of "active". This allows you to specify extra style rules on the active kwick.

Examples

Default CSS

Note that all of the examples on this page are using this as their default stylesheet:

/* defaults for all examples */
.kwicks {
	list-style: none;
	position: relative;
	margin: 0;
	padding: 0;
}
.kwicks li{
	display: block;
	overflow: hidden;
	padding: 0;
	cursor: pointer;
}

Each example has additional styling that is unique to that particular Kwicks instance. If you are going to try out any of the examples, make sure you include these styles as well.

Example 1: A la Mootools

True to Kwick's origins, here's an example that mimics the original effect on the Mootools homepage.

View Example 1

The HTML

<ul class="kwicks" >
	<li id="kwick1"></li>
	<li id="kwick2"></li>
	<li id="kwick3"></li>
	<li id="kwick4"></li>
</ul>

The CSS

.kwicks li{
	float: left;
	width: 125px;
	height: 100px;
	margin-right: 5px;
}
#kwick1 { 
	background-color: #53b388;
	background-image: url('images/meet.gif');
}
#kwick2 {
	background-color: #5a69a9;
	background-image: url('images/kwicks.gif');
}
#kwick3 {
	background-color: #c26468;
	background-image: url('images/for.gif');
}
#kwick4 { 
	background-color: #bf7cc7;
	background-image: url('images/jquery.gif');
	margin-right: none;
}

The JavaScript

$().ready(function() {
	$('.kwicks').kwicks({
		max : 205,
		spacing : 5
	});
});

Example 2: Using "Active" Class

Kwicks adds an extra class of "Active" to the currently active Kwick. This example demonstrates how you can use this class to jazz things up a bit. Note: if this example doesn't remind you of "Simon Says", then we didn't grow up in the same era.

View Example 2

The HTML

<ul class="kwicksl" >
	<li id="kwick1"></li>
	<li id="kwick2"></li>
	<li id="kwick3"></li>
	<li id="kwick4"></li>
</ul>

The CSS

.kwicks li {
	float: left;
	width: 125px;
	height: 100px;
	margin-right: 5px;
}
#kwick1 { 
	background-color: #53b388;
}
#kwick1.active { 
	background-color: #86e6bb;
}
#kwick2 {
	background-color: #5a69a9;
}
#kwick2.active {
	background-color: #8d9cdc;
}
#kwick3 {
	background-color: #c26468;
}
#kwick3.active {
	background-color: #f5979b;
}
#kwick4 { 
	background-color: #bf7cc7;
	margin-right: none;
}
#kwick4.active { 
	background-color: #efaffa;
}

The JavaScript

$().ready(function() {
	$('.kwicks').kwicks({
		max: 205,
		spacing:  5
	});
});

Example 3: Vertical Arrangement (finally!)

One of the big new features this release is the vertical arrangement. The primary addition in using this new feature is the isVertical option. Note that there are some necessary changes to the CSS as well.

View Example 3

The HTML

<ul class="kwicksl" >
	<li id="kwick1"></li>
	<li id="kwick2"></li>
	<li id="kwick3"></li>
	<li id="kwick4"></li>
</ul>

The CSS

.kwicks li{
	width: 125px;
	height: 100px;
	margin-bottom: 3px;
}
#kwick1 { 
	background-color: #FF5100;
}
#kwick2 {
	background-color: #B33900;
}
#kwick3 {
	background-color: #FFD000;
}
#kwick4 { 
	background-color: #B39200;
	margin-bottom: none;
}

The JavaScript

$().ready(function() {
	$('.kwicks').kwicks({
		max : 205,
		spacing : 3,
		isVertical : true
	});
});

Example 4: Use Min instead of Max

The previous release required you to specify the width of the active kwick using the maxWidth option. With the arrival of the vertical arrangement, maxWidth has been replaced with max, since it may refer to the maximum height as well. However, as of v1.5, developers may opt to use a new property, min, in place of max. Instead of setting the maximum width/height of the expanded kwick, min allows you to specify the minimum width/height of all of the non-expanded kwicks. Please note that you must use one or the other, but not both.

View Example 4

The HTML

<ul class="kwicksl" >
	<li id="kwick1"></li>
	<li id="kwick2"></li>
	<li id="kwick3"></li>
	<li id="kwick4"></li>
</ul>

The CSS

.kwicks li{
	width: 125px;
	height: 100px;
	margin-bottom: 3px;
}
#kwick1 { 
	background-color: #008DA3;
}
#kwick2 {
	background-color: #F07000;
}
#kwick3 {
	background-color: #A33100;
}
#kwick4 { 
	background-color: #8CAB2B;
	margin-bottom: none;
}

The JavaScript

$().ready(function() {
	$('.kwicks').kwicks({
		min : 30,
		spacing : 3,
		isVertical : true
	});
});

Example 5: Using Sticky and Custom Event

In this example you will see two more new features to this release. Sticky mode causes one kwick to always be open, defaulting to the first. The event option also let's you specify the trigger event of your choosing ('click' in this example). While these two options have no dependency on each other, they do make a nice combination, providing something close to an accordion effect.

View Example 5

The HTML

<ul class="kwicks">
	<li id="kwick1"></li>
	<li id="kwick2"></li>
	<li id="kwick3"></li>
	<li id="kwick4"></li>
</ul>

The CSS

.kwicks li {
	width: 125px;
	height: 100px;
	margin-bottom: 3px;
}
#kwick1 { 
	background-color: #4D9AA8;
}
#kwick2 {
	background-color: #82A616;
}
#kwick3 {
	background-color: #F29A1F;
}
#kwick4 { 
	background-color: #A66A16;
	margin-bottom: none;
}

The JavaScript

$().ready(function() {
	$('.kwicks').kwicks({
		min : 30,
		spacing : 3,
		isVertical : true,
		sticky : true,
		event : 'click'
	});
});

Example 6: Custom Easing and Duration

Some of the easing animations, such as the one used in this example, appear better with a longer duration to complete the "effect". This example demonstrates using a custom easing function as well as setting an appropriate duration.

View Example 6

The HTML

<ul class="kwicks">
	<li id="kwick1"></li>
	<li id="kwick2"></li>
	<li id="kwick3"></li>
	<li id="kwick4"></li>
</ul>

The CSS

.kwicks li {
	float: left;
	width: 125px;
	height: 100px;
	margin-right: 5px;
}
#kwick1 { 
	background-color: #53b388;
}
#kwick2 {
	background-color: #5a69a9;
}
#kwick3 {
	background-color: #c26468;
}
#kwick4 { 
	background-color: #bf7cc7;
	margin-right: 0px;
}

The JavaScript

$().ready(function() {
	$('.kwicks').kwicks({
		max: 320,
		spacing: 5,
		duration: 1500,
		easing: 'easeOutBounce'
	});
});

Example 7: Be Creative!

The Kwicks plugin is intended to be fun! At the risk of being cheesy, here's an example showing what a little creativity can give you...

View Example 7

The HTML

<ul class="kwicks">
	<li>
		<div class="kwicks_inner_inner">
			<div class="bigLetter">L</div>
			<div class="smallLetters">is for the way you look at me</div>
		</div>
	</li>
	<li>
		<div class="kwicks_inner">
			<div class="bigLetter">O</div>
			<div class="smallLetters">is for the only one I see</div>
		</div>
	</li>
	<li>
		<div class="kwicks_inner">
			<div class="bigLetter">V</div>
			<div class="smallLetters">is very, very extraordinary</div>
		</div>
	</li>
	<li>
		<div class="kwicks_inner">
			<div class="bigLetter">E</div>
			<div class="smallLetters">is even more... I refuse to finish...</div>
		</div>
	</li>
</ul>

The CSS

.kwicks li {
	float: left;
	width: 90px;
	height: 100px;
}
.kwicks .kwicks_inner {
	width: 200px;
}
.kwicks .bigLetter {
	font-size: 60px;
	width: 90px;
	height: 100px;
	color: red;
	float: left;
}
.kwicks .smallLetters {
	display: none;
	text-align: center;
	width: 140px;
	color: #ccc;
	font-size: 16px;
	margin-top: 13px;
	float: right;
}
.kwicks li.active .smallLetters {
	display: block;
}

The JavaScript

$().ready(function() {
	$('.kwicks').kwicks({
		max: 200,
		duration: 400,
        sticky: true
	});
});

Showcase

I figured it could be helpful to see some real world uses of the Kwicks plugin. If you would like to have your site listed here, please just send me an email (jmar777[at]gmail[dot]com).