Codakey
Play
← Back to fronteed/icheck

How to Deploy & Use fronteed/icheck

iCheck Deployment & Usage Guide

iCheck v1.0.3 — Highly customizable checkboxes and radio buttons for jQuery and Zepto.

1. Prerequisites

  • jQuery v1.7+ or Zepto.js (with polyfill, event, data modules)
  • Modern web browser (Chrome, Firefox, Safari, Edge, IE9+)
  • Web server (recommended for local testing, though not strictly required)
  • Optional: Node.js/npm (if installing via package manager or using build tools)

2. Installation

Option A: CDN (Recommended for Quick Start)

<!-- Include iCheck CSS (choose a skin) -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/iCheck/1.0.3/skins/minimal/minimal.css">

<!-- Include jQuery -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

<!-- Include iCheck -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/iCheck/1.0.3/icheck.min.js"></script>

Option B: Package Manager

# npm
npm install icheck

# Bower (legacy)
bower install icheck

Option C: Manual Download

git clone https://github.com/drgullin/icheck.git
cd icheck
# Copy icheck.js and desired skin CSS files to your project

Available Skin Files (located in /skins/):

  • minimal/ — Minimal skin (gray/white)
  • square/ — Square style
  • flat/ — Flat UI colors
  • line/ — Line style
  • polaris/ — Polaris theme
  • futurico/ — Futurico theme

3. Configuration

Basic HTML Structure

Ensure your checkboxes/radio buttons follow standard HTML:

<!-- Checkbox -->
<label>
  <input type="checkbox" name="terms" checked>
  I agree to terms
</label>

<!-- Radio buttons -->
<input type="radio" name="gender" id="male" value="male">
<label for="male">Male</label>

<input type="radio" name="gender" id="female" value="female" checked>
<label for="female">Female</label>

JavaScript Initialization

Initialize iCheck on your inputs:

// Basic initialization (all checkboxes and radios)
$('input').iCheck();

// Specific selector
$('.mycheckboxes').iCheck();

// With custom options
$('input').iCheck({
  checkboxClass: 'icheckbox_minimal',
  radioClass: 'iradio_minimal',
  increaseArea: '20%', // increases clickable area
  cursor: true
});

Key Configuration Options

OptionTypeDefaultDescription
checkboxClassString'icheckbox'Base class for checkboxes
radioClassString'iradio'Base class for radio buttons
checkedClassString'checked'Class when input is checked
disabledClassString'disabled'Class when input is disabled
hoverClassString'hover'Class on mouse hover
increaseAreaString''Increase clickable area by % (e.g., '20%' or '-10%' )
ariaBooleanfalseEnable ARIA accessibility attributes
inheritClassBooleanfalseInherit original input's class name
cursorBooleanfalseSet pointer cursor on enabled inputs

Skin-Specific Setup

Each skin requires its specific class configuration:

// Minimal skin (red theme)
$('input').iCheck({
  checkboxClass: 'icheckbox_minimal-red',
  radioClass: 'iradio_minimal-red'
});

// Square skin (blue theme)
$('input').iCheck({
  checkboxClass: 'icheckbox_square-blue',
  radioClass: 'iradio_square-blue'
});

// Flat skin (green theme)
$('input').iCheck({
  checkboxClass: 'icheckbox_flat-green',
  radioClass: 'iradio_flat-green'
});

4. Build & Run (Local Development)

Setting up a Test Environment

  1. Create test HTML file:
<!DOCTYPE html>
<html>
<head>
  <title>iCheck Test</title>
  <link rel="stylesheet" href="skins/minimal/minimal.css" />
  <style>
    body { padding: 50px; font-family: Arial; }
    label { margin-right: 20px; }
  </style>
</head>
<body>
  <h2>iCheck Demo</h2>
  
  <label>
    <input type="checkbox" checked> Option 1
  </label>
  <label>
    <input type="checkbox"> Option 2
  </label>
  
  <hr>
  
  <label>
    <input type="radio" name="demo" checked> Radio A
  </label>
  <label>
    <input type="radio" name="demo"> Radio B
  </label>

  <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
  <script src="icheck.js"></script>
  <script>
    $(document).ready(function(){
      $('input').iCheck({
        checkboxClass: 'icheckbox_minimal',
        radioClass: 'iradio_minimal'
      });
    });
  </script>
</body>
</html>
  1. Serve locally (to avoid CORS issues with local files):
# Python 3
python -m http.server 8000

# Node.js (if http-server is installed)
npx http-server -p 8000

# PHP
php -S localhost:8000
  1. Open browser: Navigate to http://localhost:8000

Integration with Modern Build Tools

Webpack/Vite/Rollup usage:

// Import CSS
import 'icheck/skins/minimal/minimal.css';

// Import iCheck
import 'icheck';

// Initialize
$(document).ready(function(){
  $('input').iCheck({
    checkboxClass: 'icheckbox_minimal',
    radioClass: 'iradio_minimal'
  });
});

5. Deployment (Production)

Strategy A: CDN Deployment (Simplest)

Use in production HTML:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/iCheck/1.0.3/skins/square/blue.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/iCheck/1.0.3/icheck.min.js"></script>

Pros: Cached by browser, zero build step Cons: External dependency, requires SubResource Integrity (SRI) for security

Strategy B: Bundled with Application

Include in your project's build pipeline:

// webpack.config.js or vite.config.js
// Ensure jQuery is available globally if needed
plugins: [
  new webpack.ProvidePlugin({
    $: 'jquery',
    jQuery: 'jquery'
  })
]

Copy skin assets to your dist folder:

# Example build script
cp -r node_modules/icheck/skins/* dist/assets/icheck-skins/

Strategy C: WordPress/Drupal Integration

Enqueue in your theme's functions.php (WordPress):

wp_enqueue_style('icheck-minimal', get_template_directory_uri() . '/assets/icheck/minimal.min.css');
wp_enqueue_script('icheck', get_template_directory_uri() . '/assets/icheck/icheck.min.js', array('jquery'), '1.0.3', true);

Performance Optimization

  1. Minify: Use icheck.min.js (1kb gzipped)
  2. Sprite sheets: Skin images are already sprites (Retina-ready)
  3. Selective initialization: Don't use $('input') on large DOMs—target specific classes
  4. Preconnect: If using CDN, add <link rel="preconnect" href="https://cdnjs.cloudflare.com">

6. Troubleshooting

Issue: iCheck not styling inputs

Symptoms: Checkboxes appear as default browser inputs
Solution:

  • Verify jQuery is loaded before iCheck: console.log(typeof jQuery)
  • Check that CSS file is loaded (look for 404s in Network tab)
  • Ensure initialization runs after DOM is ready: $(document).ready(function(){ ... })
  • Verify selector matches your inputs: $('input[type="checkbox"]').iCheck()

Issue: "iCheck is not a function" error

Solution:

  • jQuery is likely loaded twice (conflict). Ensure only one jQuery instance
  • If using module bundlers: import $ from 'jquery'; window.jQuery = window.$ = $;

Issue: Skins not displaying (broken images)

Symptoms: Missing checkbox graphics, only text labels appear
Solution:

  • Check browser console for 404 errors on skin images (PNG files)
  • Verify CSS path matches your folder structure: ../img/ references in CSS
  • For custom deployments, ensure skin image folders are copied alongside CSS

Issue: Touch devices not responding

Solution:

  • Ensure viewport meta tag is set: <meta name="viewport" content="width=device-width, initial-scale=1">
  • Check if increaseArea is set to negative value accidentally
  • For hybrid apps, ensure FastClick library isn't conflicting (exclude iCheck elements)

Issue: Form validation plugins not working

Symptoms: jQuery Validate or similar doesn't recognize iCheck inputs
Solution: iCheck wraps inputs in divs, breaking some validation selectors. Use:

$('input').iCheck({
  inheritClass: true  // Preserves original classes for validators
});

Issue: ARIA/Screen reader issues

Solution: Enable accessibility mode:

$('input').iCheck({
  aria: true  // Adds ARIA attributes for screen readers
});

Issue: Checked state not updating visually

Solution: Use iCheck methods instead of jQuery prop:

// Wrong
$('input').prop('checked', true);

// Correct
$('input').iCheck('check');
$('input').iCheck('uncheck');

API Quick Reference

Methods (call after initialization):

$('input').iCheck('check');      // Check input
$('input').iCheck('uncheck');    // Uncheck input
$('input').iCheck('toggle');     // Toggle state
$('input').iCheck('disable');    // Disable input
$('input').iCheck('enable');     // Enable input
$('input').iCheck('update');     // Apply input changes
$('input').iCheck('destroy');    // Remove iCheck and restore original

Callbacks:

$('input').on('ifChecked', function(event){
  console.log('Checked: ' + $(this).val());
});

$('input').on('ifUnchecked', function(event){
  console.log('Unchecked');
});

Note: For iCheck v2.0 (release candidate with improved performance), see the 2.x branch.

← Project overviewView alternatives to fronteed/icheck →