JCF - JavaScript Custom Forms

This library allows crossbrowser customization of form elements using CSS.

Check live demo.

Browser support

The script was tested in the following browsers:

Internet Explorer 8+
Firefox
Chrome
Safari
Opera
Windows 8+ Touch desktops
Windows Phone 8+
Android 4+
iOS7+

Installation

Install using npm: npm install jcf

Install using Bower: bower install jcf

CDN: this library is available at cdnjs

Usage

The script requires jQuery 1.7+ to work properly. To add script in your page simply attach core file - jcf.js and some of modules you want to use for customization:

<script src="js/jquery.js"></script>
<script src="js/jcf.js"></script>
<script src="js/jcf.select.js"></script>
<script src="js/jcf.radio.js"></script>
<script src="js/jcf.checkbox.js"></script>

When the page is loaded all you have to do is simply call function:

$(function() {
	jcf.replaceAll();
});

Please note that JCF does not replace original form elements with own components. It just creates additional DOM nodes to support CSS styling. All DOM events are invoked on original elements and in most cases JCF could be easily turned on or off without affecting your existing event listeners.

How to use JCF with AngularJS 1.x

To use this script with Angular you still need to attach all scripts above (including jQuery) and also attach directive:

<script src="js/jcf.angular.js"></script>

When the directive is connected as dependency in your app you can add jcf attribute to the form field and such element will be customized:

<!-- customize select: -->
<select jcf>
    ...
</select>

<!-- customize range input with specific options: -->
<input type="range" jcf='{"orientation": "vertical"}'>

General API Information

Global jcf object has several methods to control custom form elements on the page:

jcf.replaceAll( [context] ) - Replace elements on the whole page. Optional argument is context to use (can be CSS selector, or DOM/jQuery object). Add class jcf-ignore on the element to prevent its customization.

jcf.replace( elements [, moduleName] [, customOptions] ) - Replace certain element or multiple elements. Returns custom form element instance. The first argument is CSS selector, or DOM/jQuery object to be customized. Second argument is optional and used to specify module which should be used for customization. By default it is false which will result module to be auto detected. Third argument is module options which can be specified with object.

jcf.destroyAll( [context] ) - Destroy all custom form elements instances and restore original form elements. Optional argument is context to use (can be CSS selector, or DOM/jQuery object).

jcf.destroy( elements ) - Destroy certain element or multiple form elements. Should be applied to native form controls.

jcf.refreshAll( [context] ) - Redraw all custom form instances. Should be used when values of form elements are modified by other scripts. Optional argument is context to use (can be CSS selector, or DOM/jQuery object).

jcf.refresh( elements ) - Refresh certain element or multiple form elements.

Getting the instance of customized form element

In any time it's possible to get instance of customized form element. Use method jcf.getInstance to do this:

var countrySelect = document.getElementById('country-select');
var customFormInstance = jcf.getInstance(countrySelect);

customFormInstance.refresh();

Setting Options

There are two ways of specifying options for modules - override module defaults and specify options per element.

// set options for Checkbox module
jcf.setOptions('Checkbox', {
	checkedClass: 'test',
	wrapNative: false
});

// replace all form elements with modified default options
jcf.replaceAll();

The second way is to specify options for certain element in HTML:

<input type="checkbox" data-jcf='{"checkedClass": "test", "wrapNative": false}'>

(Please be careful and use valid JSON)

Module Options

Each module has options. Some of options are common between modules and some are unique. The most commonly used options in modules are listed below.

Select

Option	Description	Data Type	Default
`wrapNative`	Wrap native select inside fake area, so that native dropdown will be shown	boolean	`true`
`wrapNativeOnMobile`	Show native dropdown on mobile devices even if `wrapNative` is `false`	boolean	`true`
`fakeDropInBody`	Active only when custom dropdown is used. Specifies where to append custom dropdown - in document root, or inside select area	boolean	`true`
`useCustomScroll`	Use custom scroll inside custom dropdown if `Scrollable` module present	boolean	`true`
`flipDropToFit`	Flip custom dropdown if it does not fit in viewport	boolean	`true`
`maxVisibleItems`	How many options should be visible in dropdown before scrollbar appears	number	`10`

Checkbox

Option	Description	Data Type	Default
`wrapNative`	Wrap native checkbox inside fake area for better compatibility with event handlers attached by other scripts	boolean	`true`
`checkedClass`	Specify class which will be added to fake area when checkbox is checked	string	`"jcf-checked"`
`labelActiveClass`	Specify class which will be added to corresponding `<label>` when checkbox is checked	string	`"jcf-label-active"`

Radio

Option	Description	Data Type	Default
`wrapNative`	Wrap native radio inside fake area for better compatibility with event handlers attached by other scripts	boolean	`true`
`checkedClass`	Specify class which will be added to fake area when radio is checked	string	`"jcf-checked"`
`labelActiveClass`	Specify class which will be added to corresponding `<label>` when radio is checked	string	`"jcf-label-active"`

Number input

Option	Description	Data Type	Default
`pressInterval`	Specify the interval which will control how fast the value is changing while the buttons are pressed.	number	`150`
`disabledClass`	Specify class which will be added to arrow buttons when maximum or minimum number is reached	string	`"jcf-disabled"`

Range input

Option	Description	Data Type	Default
`orientation`	Specify range input orientation: `"horizontal"` or `"vertical"`	string	`horizontal`
`range`	Show range indicator. By default indicator will be shown only for inputs with multiple handles. Possible values are: `"min"`, `"max"`, `"all"`	string	`"auto"`
`minRange`	Works only when multiple slider handles are used. Sets the minimum range value that can be selected between the two handles	number	`0`
`dragHandleCenter`	Enable this option to make the cursor stick to the center of the input handle	boolean	`true`
`snapToMarks`	Snap input handle to HTML5 datalist marks	boolean	`true`
`snapRadius`	Specify snapping radius in pixels	number	`5`

File

Option	Description	Data Type	Default
`buttonText`	Specify default text for upload button (its better to specify this option from HTML for proper localization).	string	`"Choose file"`
`placeholderText`	Specify default text for input when no file is selected (its better to specify this option from HTML for proper localization)	string	`"No file chosen"`

Scrollable

Option	Description	Data Type	Default
`handleResize`	Handle resize events so that scrollable area will be responsive	boolean	`true`
`alwaysShowScrollbars`	Always show scrollbars event if they cant scroll anything	boolean	`false`
`alwaysPreventMouseWheel`	Always prevent mouse wheel scrolling when its used over scrollable element. This way page wont be scrolled even if scrollable area is at the scrolled to the top/bottom.	boolean	`false`

Textarea

Apply custom scrollbar on <textarea> (Works only when Scrollable module is available).

Option	Description	Data Type	Default
`resize`	Add resize grip to `<textarea>`	boolean	`true`

License

This script is licensed under the MIT License.

w3co/jcf