Sexy form elements with jQuery. Now with HTML5 attributes!
Version 2.0
Works well with jQuery 1.6+, but we've received patches and heard that this works with jQuery 1.3.
Licensed under the MIT License
Installation of Uniform is quite simple. First, make sure you have jQuery installed. Then you’ll want to link to the jquery.uniform.js file and uniform.default.css in the head area of your page. Here's what your <head> tag contents should probably contain:
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"></script>
<script src="jquery.uniform.js"></script>
<link rel="stylesheet" href="uniform.default.css" media="screen" />
This relies upon a copy of jquery.uniform.js, uniform.default.css and the various images all being available on your webserver.
Using Uniform is easy. Simply tell it what elements to style:
// Style all <select> elements
$("select").uniform();
To "uniform" all possible form elements, just do something like this. Things that can't get styled appropriately will be skipped by Uniform.
// Style everything
$("select, input, a.button, button").uniform();
You can exclude elements too by using more jQuery selectors or methods:
// Avoid styling some elements
$("select").not(".skip_these").uniform(); // Method 1
$('select[class!="skip_these"]').uniform(); // Method 2
A complete set of tags in the HEAD section of your site can therefore look like this:
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"></script>
<script src="jquery.uniform.js"></script>
<link rel="stylesheet" href="uniform.default.css" media="screen" />
<script type='text/javascript'>
// On load, style typical form elements
$(function () {
$("select, input, button").uniform();
});
</script>
You can pass in extra parameters to control certain aspects of Uniform. To pass in parameters, use syntax like this:
$("select").uniform({
param1: value,
param2: value,
param3: value
});
Alternately, you can specify global defaults by using the defaults property. Note: The property name changed in v2.0.
$.uniform.defaults.checkedClass = "uniformCheckedClass";
$.uniform.defaults.fileBtnText = "Pick a file";
Default: "active"
Sets the class given to elements when they are active (pressed).
$("select").uniform({activeClass: 'myActiveClass'});
Default: true
If this option is set to true, Uniform will hide the new elements if the existing elements are currently hidden using display: none.
If you want to show a select or checkbox you'll need to show the new Uniform div instead of the child element.
Default: "button"
Sets the class given to a button that's been Uniformed
$("input[type=button]").uniform({buttonClass: 'myBtnClass'});
Default: "checker"
Sets the class given to the wrapper div for checkbox elements.
$(":checkbox").uniform({checkboxClass: 'myCheckClass'});
Default: "checked"
Sets the class given to elements when they are checked (radios and checkboxes).
$(":radio, :checkbox").uniform({checkedClass: 'myCheckedClass'});
Default: "disabled"
Sets the class given to elements when they are disabled.
$("select").uniform({disabledClass: 'myDisabledClass'});
Default: ".uniform"
Binds events using this namespace with jQuery. Useful if you want to unbind them later. Shouldn't probably need to be changed unless it conflicts with other code.
$("select").uniform({eventNamespace: '.uniformEvents'});
Default: "action"
Sets the class given to div inside a file upload container that acts as the "Choose file" button.
$(":file").uniform({fileButtonClass: 'myFileBtnClass'});
Default: "Choose File"
Sets the text written on the action button inside a file upload input.
$(":file").uniform({fileButtonText: 'Choose …'});
Default: "uploader"
Sets the class given to the wrapper div for file upload elements.
$(":file").uniform({fileClass: 'myFileClass'});
Default: "No file selected"
Sets the text written in the filename div of a file upload input when there is no file selected.
$(":file").uniform({fileDefaultText: 'Select a file please'});
Default: "filename"
Sets the class given to div inside a file upload container that spits out the filename.
$(":file").uniform({filenameClass: 'myFilenameClass'});
Default: "focus"
Sets the class given to elements when they are focused.
$("select").uniform({focusClass: 'myFocusClass'});
Default: "hover"
Sets the class given to elements when they are currently hovered.
$("select").uniform({hoverClass: 'myHoverClass'});
Default: "uniform"
If useID is set to true, this string is prefixed to element ID’s and attached to the container div of each Uniformed element. If you have a checkbox with the ID of "remember-me" the container div would have the ID "uniform-remember-me".
$("select").uniform({idPrefix: 'container'});
Default: "radio"
Sets the class given to the wrapper div for radio elements.
$(":radio").uniform({radioClass: 'myRadioClass'});
Default: "Reset"
This text is what's shown on form reset buttons. It is very similar to submitDefaultText.
$("input[type='reset']).uniform({resetDefaultText: "Clear"});
Default: false
This parameter allows you to use a jQuery-style selector to point to a "reset" button in your form if you have one. Use false if you have no "reset" button, or a selector string that points to the reset button if you have one.
$("select").uniform({resetSelector: 'input[type="reset"]'});
Default: true
If this option is set to true, Uniform will try to fit the select width to the actual content. If the select is populated via JavaScript, it is recommended to set a custom width for the element (style="width:XX") or uniform it after being populated.
Default: "selector"
Sets the class given to the wrapper div for select elements, but not multiselects.
$("select").uniform({selectClass: 'mySelectClass'});
Default: "uniform-multiselect"
Sets the class given to the wrapper div for select elements that are multiselects.
$("select").uniform({selectMultiClass: 'myMultiSelectClass'});
Default: "Submit"
This text is what's shown on form submit buttons. It is very similar to resetDefaultText.
$("input[type='submit']).uniform({resetDefaultText: "Submit Form"});
Default: "uniform"
The class that is applied to textarea elements.
$("textarea").uniform({textareaClass: "myTextareaClass"});
Default: true
If true, sets an ID on the container div of each form element. The ID is a prefixed version of the same ID of the form element.
$("select").uniform({useID: false});
In addition to the parameters, there are a couple of other ways you can interact with Uniform.
If you need to change values on the form dynamically you must tell Uniform to update that element’s style. Fortunately, it’s very simple. Just call this function, and Uniform will do the rest.
$.uniform.update("#myUpdatedCheckbox");
If you don't mind updating all Uniformed elements or just don’t specifically know which element to update, you can just leave out the parameter (see below) and Uniform will update all Uniformed elements on the page:
$.uniform.update();
If you want to "un-uniform" something, simply call this function. It will remove the inline styles, extra dom elements, and event handlers, effectively restoring the element to it's previous state.
$.uniform.restore("select");
You can get an array of all the elements that have been Uniformed at any time using this public variable. I don't advise changing the contents!
var uniforms = $.uniform.elements;
To edit the CSS of Uniform it is highly recommended to not edit the theme files, but to override them using CSS. Make sure your CSS file comes after the Uniform theme css file in the HEAD section.
It's common to want to resize the selects or other elements. The best way is to set the width property on the div element, span element and the form element itself. Resizing "select" lists is a bit tougher as you need to change the line height. I suggest looking at the _base theme's SCSS file to see where the various width and height variables are used.
If you'd like to create your own theme, take a peek at theme-kit/README.md. It's on github and included in the theme kit.
Uniform is supposed to be pretty simple, but there are a few things that can be tricky. Here are some tips that may make your experience simpler:
-
Remember to change the CSS classes in the theme if you change the parameters for elements’ classes. This can be tedious work, but if you don’t do it, it’s not going to look correct. Find and Replace is your friend.
-
Uniform cannot automatically sniff out dynamic value changes. If you make changes to elements in JavaScript or using a reset button of some kind, remember to call $.uniform.update(); to sync the changes with Uniform. See Issue #270 for the little bit of code you will need.
-
Likewise, when you add elements to the DOM, perhaps via AJAX, and they need to get styled, you will need to use $('#newElement').uniform() on it so the styling is applied.
-
Uniform is disabled in IE6. It’s not possible to fix due to the way IE6 handles form elements. If you care about IE6 users, give it a quick look to make sure your "naked" form elements look alright in there.
-
There is a bug in Safari 5.1 that will cause the web rendering process to crash when you use custom fonts. For more information, see Issue #183.
-
With IE 7-9, sometimes the "change" event doesn't get fired or doesn't get triggered at the right time. When we detect a change, Uniform may submit its own "change" event on the element. See Issue #152 and Issue #238.
-
With IE9, you may have problems with some fonts on your site. See Issue #226 if you mysteriously see a blank page or blank form elements. The fonts in Uniform have been arranged to work around this, but custom themes may not work properly.
-
If you have ideas, or bugs, please post them in GitHub. We rely on our users' for improvement ideas and bug reports. Without your participation, Uniform will stay static.
Your sprite map will now support many new things and will need to be updated. If you use custom backgrounds that are not in the sprite map, those will need updating as well.
The uniform.options object was renamed to uniform.defaults since they are the default options. Other properties were renamed to be consistent or have less ambiguous names, such as fileBtnClass becoming fileButtonClass.
Previously, calls to update() would render all elements with the most recent set of options. This has been fixed, but may change how your page looks. Test to make sure things still render as expected.
$.uniform.noSelect is no longer exposed and has been updated to version 1.0.3.
The sprite changed a bit. The caps for select lists were moved to the left-hand side. Button theming was added and the file upload images were reordered to match the select list order. See the theme-kit/README.md file for further reading on this topic.
It sure would be handy if you could create a test page to help illustrate bugs. When you use the GitHub Issue Tracker, you could clone this bug template gist to help illustrate your point.
Even if you don't do that, all sorts of feedback is welcome, but narrowing down your problem or providing an example would immediately help narrow down the problem quickly.