The jQuery Linkselect plug-in converts <select /> elements into a combination
of an anchor tag associated with a dropdown menu. This combination allows you to highly
customize the look and feel of the select element, without losing any functionality.
While there are many similar plug-ins, the key differentiator with the Linkselect plug-in
is that is designed to fit in limited real estate. One key design issue with the <select />
is that it's hard to control how much screen real estate is taken up by the element. If your
<select /> contains options of varying sizes, the width of the <select />
element can quickly get out of hand.
In a recent project we were working on, we required the functionality of a <select />
element, but had to work within a very confined design area. Because we had no control
over how much data or the length of the items that appeared in the <select />
element, we knew couldn't use the element as-is. What we need was a <select />
element that would allow us to wrap long options to another line. This is what lead
to the development of the Linkselect plug-in.
The Linkselect Plug-in resolves this space by replacing the <select /> element
with an anchor tag that provides all the same functionality of a single item select
In order to use the Linkselect plug-in, you need the following:
jQuery v1.4.3 (or higher)*
jquery.bgiframe.js Plug-in (Optional; for fixing overlay issues in IE6)
To convert your <select /> elements into linkselect elements, just invoke the jQuery plug-in using the following syntax:
The width of the drop down based on the width of the anchor tag. If anchor tag happens to
be an inline element (i.e. display: inline;,) then the width will be based
on the anchor's parent element. If the fixedWidth is set to false,
then the drop down will be further adjusted to make sure that the width of the drop down
is wide enough. You can set a maximum width by setting the max-width property
of the .linkselect-container class.
This argument is optional and allows you to customize the settings used for each instance of the plug-in. For a list of all available options, see the Options section.
The Linkselect converts the standard <select /> element to a specialized UI element. There are a few key
attributes from both the <select /> and <option /> elements which are used by the Linkselect plug-in
and special funcationality. Below is a list of the attributes that provided special functionality to the Linkselect plug-in.
This attribute is required and is used as the id
attribute of the hidden input element that is created by the plug-in. If no name attribute
exists, then the id is used as the name attribute of the hidden element
that is created.
This attribute is optional and is used as the name
attributes of the hidden input element that is created by the plug-in.
This attribute is optional and is used to provide a title bar to the Linkselect's dropdown
This attribute is optional and is used to set the tabindex of the anchor tag. This just
duplicates the original <select /> element's tabindex.
This attribute is optional and will be fired just like the original onchange event would.
However, when this function is triggered, it will have access to the same arguments that the normal change
The Linkselect Plug-in was designed only for single select style elements. It will not allow you to
select more than one option.
The text of the <option /> is used as the text shown in the dropdown for the item.
This attribute is option and is used as the value for the selected item.
This attribute is optional and is used to define which option is selected
This attribute is optional and is used to define any classes that should
be applied to the option in the dropdown.
You can also supply an optional "placeholder" class (see options) to
an option element to have the option tag used as a selectable title for the
Now that we have a reference to the widget, we can invoke any of the public API calls.
Returns the current value for the linkselect element.
Sets the value of the linkselect element.
Returns the text label for the selected linkselect option.
Places focus on the Linkselect's anchor tag. This is like doing a $("a").focus();
Blur's the focus from the Linkselect's anchor tag. This is like doing a $("a").blur();
Triggers the "change" event for the Linkselect element. You can use this to trigger
off the change events for the default selected item.
Opens the Linkselect's dropdown menu.
Closes the Linkselect's dropdown menu.
Disables (true) or enables (false) the Linkselect element. Disabled elements still pass
their form value when the form is submitted to the server, but the user can not change the value
via the UI.
This destroys the linkselect element and places the original select element back in the
DOM. The select element will reflect any changes made to the option elements
done by the replaceOptions API call.
Replaces the options in the dropdown with the array of objects passed into the options argument.
You can use this API method to repopulate a Linkselect with options via an AJAX call.
You can use the includeFilter argument to specify a jQuery selector of elements
to not replace. This is useful if you want to preserve your placeholder items, or other items in the
select element that you do not want replaced.
When the options are replaced, the change callback is triggered for the newly selected item.
You can set the doCallback to false to prevent callback from being triggered.
Also supported are the keys "selected" (which can be true for any single item that needs selecting) and the
"className" key, which can be used to define a class for the <option /> element.
Returns a reference to the internal $.Linkselect object. This is for advanced usage only. Examine the source code for uses of the $.Linkselect object.
There are a number of options available for customizing the look and feel of the Linkselect widget.
style: "linkselect" // the default style to use
, classLink: "" // additional classes to use for the anchor tag
, yAxis: "top" // the position of the dropdown relative to the link (can be either
// "top" or "bottom")
, titleAlign: "right" // location of dropdown's title bar if dropdown is on right edge of
// the screen (can be either "right" or "left")
, fixedWidth: false // false = dropdown sizes to width of options, true = dropdown uses width of link
, init: null // callback that occurs when a linkselect menu is initialized
, change: null // callback that occurs when an option is selected
, format: null // callback that occurs when rendering the HTML to use for an item in the dropdown
, open: null // callback that occurs when the menu is opened
, close: null // callback that occurs when the menu is closed
The linkselect's keyboard functionality is set to mimic the behavior of Internet Explorer 6's handling
of the <select /> element. When a Linkselect element has focus you can:
Press the first letter of an option to jump to the first instance of that item in the dropdown. Subsequent presses of the same key will cycle through all items that start with the matching character. When a new key is pressed, it will attempt to jump to the first item that starts with the new keyboard character typed.
Press [UP ARROW] or [DOWN ARROW] to cycle through valid options
Press [HOME] to jump to the first item
Press [END] to jump to the last item
Press [PAGE UP] to jump up one page of options
Press [PAGE DOWN] to jump down one page of options
Before you can invoke an instance of the Linkselect widget, you must have one or more <select /> elements on your page.
The key attributes from your select tag (id, title, tabindex) are all supported by the Linkselect plug-in.
The next step is to actually create an instance of the Linkselect widget. You want to make sure to initialize the widget after all the necessary DOM elements are available, which makes the document.ready event a great place to initialize the widget.
Now let us take a look at what the code above produced.
Original <select /> element
Please select a category:
Same code using the Linkselect Plug-in
Please select a category:
Click on the "[none]" anchor above to open up the linkselect dropdown. As you change options, the text of the
anchor will get updated with the text from the <option /> tag. A hidden <input /> element with
with the same name/id attribute will have it's value updated with the value of the <option /> tag. The
hidden <input /> element is used to pass the value of the Linkselect element back to the server.
Linkselect's element have full keyboard support, which has been modeled after how Internet Explorer 6 handles <select /> elements. See the Keyboard Usage section for more information.
This source code is provided as-is. At this time Giva is not offering direct support for this product. If you are in need of assistance, post your question to one of the jQuery Mailing Lists. Members of the Giva development team actively participate on the jQuery Mailing lists, so if we see your question we will try our best to respond.
Copyright 2008 Giva, Inc. (http://www.givainc.com/labs/)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
The following download includes both uncompressed and minified versions of the plug-in and all the CSS and image files required to get you started. See the gettingstarted.htm file for usage instructions and a working example.
Added the "change" method for re-running the change events on the currently selected item
Fixed CSS declaration for "select" skin to use a defined font family and size and various other tweaks to improve appearance
Changes in the keyboard behavior when a placeholder is used so that PAGE UP, PAGE DOWN, END and HOME stay within the context of the dropdown menu
Revised CSS naming structure to make it to have multiple visual styles of linkselect elements on the same page.
The changes in v1.5 are not backwards compatible, so you will need to update your CSS in order to upgrage
to v1.5. You can either replace you existing CSS files with one included in the zip file, or you can modify
your existing CSS files to match the new naming syntax (which for the most part is just changing the camel
casing from "linkselectLink" to "linkselect-link", "linkselectLinkOpen" to "linkselect-link-open", etc.
Also, all CSS classes now using the prefix "linkselect-" by default.
Added new "style" option. This replaces all the previous class* options. The default style is "linkselect" and
is simply used as the prefix used for all the CSS classes. You can create custom linkselect skins by just
copying one of the included CSS files and changing the prefix to match your style option value.
Added "text" API call to return the label of the currently selected option.
Added "destroy" API call to destroy a linkselect element and return to original select element.
Changed the "replaceOptions" API to add a new "includeFilter" argument. The API change is backwards compatible.
jQuery.delegate() is now used to monitor event changes
Changed <li /> elements to use "data-" attributes for custom attributes
Changed <li /> elements to use "data-value" for storing selectable value instead of the "rel" attribute.
Fixed issue with Chrome not correctly accepting focus when the linkselect element was clicked.
Events related to closing/resizing of the open linkselect element are now registered/unregistered when
the menu opens. This helps improve performance when there are many linkselect elements on the page as it
reduces the document.click events that fire to see if the menu should be closed.
Added ability to use both "name" and "id" attributes on a select element with different values.
Added new "placeholder" functionality. You can now give an option element a class of "placeholder" to
have it used as a selectable title for the linkselect element. This allows you to use a
"Please select..." option element in your select and have it used as the title of the linkselect.
Users will be able to select this option, just like any other option element.
Fixed various positioning bugs.
Fixed issue with code using .attr("className") instead of .attr("class")
Fixed error with repaint() function when <select /> element did not have a title attribute
Fixed error with close callback
Fixed issues with IE8
Fixed bug where keyboard support did not work in Chrome (moved from using keypress to keydown)
Fixed bug in getScreenDimensions() by changing width/height calculation to use the document object instead of the body element
Fixed bug in repaint() if not using a title on your select elements
Fixed bug in repaint() if not using a title on your select elements
Added close() method (which did not exists, contrary to documentation)