iCheck - Documentation

What is iCheck?

iCheck is a highly customizable jQuery plugin that enhances the standard checkbox and radio inputs with visually appealing and user-friendly custom skins. It replaces the default browser renderings with modern, consistent, and interactive elements, improving the overall user experience and providing developers with extensive control over styling and behavior. iCheck offers a variety of pre-built skins, allowing for easy integration with different design themes, and also allows for complete customization through CSS and options.

Why use iCheck?

Browser Compatibility

iCheck supports all major modern browsers including:

Note: For older browsers, ensure you include appropriate polyfills for necessary features. While iCheck strives for broad compatibility, the appearance and functionality might vary slightly depending on the browser and its rendering engine.

Getting Started: Installation and Setup

  1. Include jQuery: iCheck requires jQuery. Make sure you’ve included the jQuery library in your HTML file before including iCheck. You can download it from https://jquery.com/ or use a CDN. For example:
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
  1. Include iCheck: Download the iCheck files (usually icheck.min.js and icheck.min.css) and place them in your project’s directory. Then include them in your HTML, after jQuery:
<link rel="stylesheet" href="icheck.min.css">
<script src="icheck.min.js"></script>
  1. Initialize iCheck: Use the icheck() method to initialize iCheck on your checkboxes and radio buttons. You can apply it to all elements with a specific class or to individual elements:
// Initialize all checkboxes with the class 'icheckbox_square-blue'
$('input[type="checkbox"]').iCheck({
    checkboxClass: 'icheckbox_square-blue',
    radioClass: 'iradio_square-blue'
});

// Initialize a specific checkbox
$('#myCheckbox').iCheck({
  checkboxClass: 'icheckbox_flat-green'
});

Remember to replace icheckbox_square-blue and iradio_square-blue with the desired skin class names from the iCheck documentation. Consult the iCheck documentation for a complete list of available skin classes and options to further customize your checkboxes and radio buttons.

Basic Usage

Basic Checkbox Styling

To style checkboxes using iCheck, simply include the iCheck CSS file and then call the iCheck() method on your checkbox inputs. iCheck provides several pre-defined skin classes that you can use to quickly style your checkboxes. For example, to use the “square-blue” skin:

  1. Include iCheck CSS: Ensure you’ve included the iCheck CSS file in your HTML (as described in the “Getting Started” section).

  2. Apply iCheck: Use the following jQuery code to apply the “square-blue” skin to all checkboxes on your page:

$('input[type="checkbox"]').iCheck({
  checkboxClass: 'icheckbox_square-blue'
});

This will replace the default checkbox rendering with the “square-blue” styled version. You can find other skin class names in the iCheck documentation or by inspecting the provided CSS file.

Basic Radio Button Styling

Styling radio buttons is similar to styling checkboxes. You use the radioClass option within the iCheck() method to specify the desired skin class. For instance, to use the “flat-green” skin for all radio buttons:

$('input[type="radio"]').iCheck({
  radioClass: 'iradio_flat-green'
});

This will replace the default radio button appearance with the visually enhanced “flat-green” version. Ensure that the corresponding CSS class exists in your included iCheck CSS file.

Customization Options

The iCheck() method accepts several options to further customize the appearance and behavior. Some key options include:

Refer to the full iCheck documentation for a comprehensive list of options and their functionalities.

Styling with Custom Classes

While iCheck provides many pre-defined skins, you can create your own custom styles. Create custom CSS classes and assign them to the checkboxClass and radioClass options. For example:

/* my-custom-checkbox.css */
.my-custom-checkbox {
  background-color: #f00; /*Example styling*/
  border: 2px solid #000;
}

.my-custom-checkbox.checked {
  background-color: #0f0; /*Example styling for checked state*/
}
$('input[type="checkbox"]').iCheck({
  checkboxClass: 'my-custom-checkbox'
});

This allows for complete control over the visual presentation. Remember that the structure of the generated HTML by iCheck needs to be considered when writing your custom styles. Inspect the rendered HTML elements to target the correct elements for styling.

Default Themes

iCheck ships with a collection of pre-defined themes offering various styles. These are generally identified by their class names, such as:

These themes provide a starting point for styling and can be further customized using your own CSS. Refer to the iCheck documentation and the included CSS file for a complete list and examples.

Advanced Customization

Customizing Colors and Appearance

Beyond using pre-defined skins, you can deeply customize iCheck’s colors and appearance through CSS. Inspect the generated HTML after applying iCheck to identify the specific elements (e.g., .icheckbox_square, .icheckbox_square-checked, etc.) and target them with your custom CSS rules. For example, to change the background color of a checked “square-blue” checkbox:

.icheckbox_square-blue.checked {
  background-color: #FF0000; /* Red */
}

You can similarly adjust borders, text colors, and other visual aspects. Remember that the class names might vary slightly depending on the specific skin you are using. Always inspect the rendered HTML to ensure you’re targeting the correct elements.

Using Icons

iCheck doesn’t directly support embedding arbitrary icons. However, you can achieve icon-based checkboxes and radio buttons by combining iCheck with an icon library like Font Awesome or similar. You would need to:

  1. Include the icon library: Add the necessary CSS and/or JavaScript files for your chosen icon library to your project.

  2. Style with icons: Use CSS to position icons within the iCheck elements. This often involves using pseudo-elements (:before or :after) on the iCheck container elements. For example:

.icheckbox_square-icon.checked:after {
    content: "\f00c"; /* FontAwesome check icon */
    font-family: FontAwesome;
    position: absolute;
    /* ... other positioning styles ... */
}

This approach requires careful adjustment of positioning and sizing to ensure proper alignment with the iCheck elements.

Creating Custom Skins

To create a completely custom skin, you’ll need to understand the structure of iCheck’s generated HTML and create your own CSS to style it. This involves creating new class names and defining all the necessary states (checked, unchecked, disabled, etc.) in your CSS file. It’s advisable to start by copying and modifying an existing iCheck skin as a template, making adjustments to suit your specific design needs. This avoids recreating all the necessary elements from scratch.

Advanced Styling with CSS

Advanced CSS techniques like pseudo-classes (:hover, :focus, :disabled) and pseudo-elements (:before, :after) can be used to add even more intricate styling. You can use these to enhance the visual feedback of user interactions, such as adding hover effects or visual indicators for disabled elements. Remember to consider the specificity of your CSS selectors to ensure your rules override iCheck’s default styles as intended.

Handling Different Input Types

While iCheck primarily focuses on checkboxes and radio buttons, you might need to adapt the approach for other input types. The core functionality of iCheck is tied to those specific input types, so directly applying iCheck() to other input types won’t work. You could, however, create custom styling for other input types using CSS, potentially mimicking the visual style of iCheck checkboxes or radio buttons for consistency. This would require manually creating the visual elements and handling the necessary JavaScript interactions. You would not be leveraging the core functionality of the iCheck plugin itself for these elements.

Working with iCheck

Event Handling

iCheck triggers several events that you can use to respond to user interactions and changes in the checkbox or radio button state. These events are triggered on the underlying input element, not the iCheck-generated elements. To listen for these events, use jQuery’s .on() method:

Example:

$('input[type="checkbox"]').on('ifChecked', function(event){
    console.log('Checkbox checked:', this.id);
    // Perform actions when checkbox is checked
});

$('input[type="radio"]').on('ifChanged', function(event){
    console.log('Radio button changed:', this.value);
    // Perform actions when radio button state changes
});

Note that the event object provides access to information about the triggering element. You should use this to reference the original input element within the event handler, not the iCheck-generated elements.

Programmatic Control

You can control the checked state of checkboxes and radio buttons programmatically using iCheck’s methods:

Example:

$('#myCheckbox').iCheck('check'); // Checks the checkbox with ID 'myCheckbox'
$('#myRadio').iCheck('uncheck'); // Unchecks the radio button

let isChecked = $('#anotherCheckbox').iCheck('state'); // Get the state
console.log("Checkbox is checked:", isChecked);

Working with Forms

iCheck seamlessly integrates with HTML forms. When a checkbox or radio button styled with iCheck is submitted as part of a form, the underlying input element’s value is included in the form data. No special handling is needed from the iCheck plugin’s perspective. You handle the form submission as you normally would. The values are correctly submitted even though the visual representation has been altered.

Integration with JavaScript Frameworks

iCheck is designed to work with jQuery and can be easily integrated into projects using other JavaScript frameworks such as React, Angular, or Vue.js. The basic approach is consistent:

  1. Include iCheck: Include the iCheck CSS and JavaScript files in your project.

  2. Initialize iCheck: Use jQuery to call the iCheck() method after the DOM is fully loaded. This usually involves using appropriate lifecycle hooks provided by the framework. For instance, in React, you might initialize iCheck within a componentDidMount() method. The core interaction with iCheck remains the same; you utilize jQuery to apply iCheck to your input elements.

  3. Manage state: Handle the state of the checkboxes/radio buttons within your framework’s state management system. Update your framework’s state when iCheck events are fired, and trigger iCheck’s programmatic methods (check, uncheck, toggle) as needed to update the UI.

Accessibility Considerations

While iCheck enhances the visual appearance, ensure you also address accessibility:

Troubleshooting

Common Issues and Solutions

Debugging Techniques

Troubleshooting CSS Conflicts

CSS conflicts often arise when your custom styles or other CSS rules override iCheck’s styles unintentionally. To resolve this:

Compatibility Problems

API Reference

This section provides a detailed reference for iCheck’s API, including methods, options, events, and properties. Note that the exact availability and behavior of certain features might depend on the version of iCheck you are using. Always consult the latest documentation for the most up-to-date information.

Methods

iCheck provides several methods to control and interact with the plugin:

These methods are called using jQuery’s chaining syntax on the element(s) you wish to manipulate. For example: $('#myCheckbox').iCheck('check');

Options

These options are passed as a single object to the iCheck() method during initialization.

Events

iCheck triggers several events on the underlying input element:

Listen for these events using jQuery’s .on() method.

Properties

iCheck doesn’t expose public properties directly in the way that some other plugins might. The iCheck('state') method provides access to the checked state, but there aren’t other properties that can be accessed directly. Instead, you can access relevant information through the underlying input element using jQuery. For example, to access the value of a radio button, you’d use $('#myRadio').val(). The plugin itself is primarily focused on the visual modification and event handling, not on exposing specific internal properties for direct manipulation.