Image Picker

Image Picker is a simple jQuery plugin that transforms a select element into a more user friendly graphical interface.

View in Github or Download the project

Features

Works great on both single and multiple select elements.
Falls back nicely for clients without JavaScript enabled.
Integrates nicely with Twitter's Bootstrap markup.

What it does?

It turns a select element into a more user friendly interface, e.g.:

Note: Select items are hidden by default when using Image Picker. They are left visible in the examples for pedagogical purposes.

How it works?

Simply add the attribute data-img-src with the url of the image you want to use as a preview, e.g:

<option
  data-img-src='http://www.example.com/image.jpg'
  value='42'
>

Then just call imagepicker on the target elements.

$("select").imagepicker()

More examples

Include blanks

If you want to allow blanks, just include an extra option with an empty value and no image data associated. Clicking a selected image will deselect it.

Selects Multiple

Image Picker works great on select multiple elements too.

Limit multiple selects Original submit and idea by Jason M. Batchelor.

You can also limit the amount of images to be selected by either passing an argument to the initialization when calling imagepicker(), ej: $("select").imagepicker({limit: 2}) or adding it as data to the select element (click view html for example).

You can also trigger a callback when the limit has been reached by specifying a function in either the initialization under the attribute $("select").imagepicker({limit_reached: function(){alert('We are full')}}).

Labels

You can also use the options text as labels by passing the option show_label: true when calling imagepicker().

You can specify more complex labels by passing them as part of the option data in the attribute data-img-label. You can even specify HTML code.

Uneven images

By default, Image Picker does not resize or order your images in any way, there are better tools for it if you need it. It can look great if your images are properly designed and ordered.

Or awful if they are just some random images. Thankfully, it works great with third party grid aligning scripts like Masonry.

Grouped Options

It also works with grouped options. Each group will appear as separate nested list. You'll need to style this according to your needs.

Documentation

Image Picker Options

You can specify the following options when calling image picker:

hide_select: Default: true. Wheter the original select item should be hidden or not.
show_label: Default: false. If set to true, the text of each option will be added as a paragraph below each image.
limit: Default: undefined. If it's a select multiple and set to any value, it'll cap the selectable elements at that value.

Additionally you can specify the following callbacks, all the callbacks have the scope (value of the this variable) set to the jQuery object where the plugin was initialized.

initialized: function(imagePicker){...}
Default: undefined. Specify a function to be called when the picker has been initialized. Receives the image picker as the first argument.
changed: function(select, newValues, oldValues, event){...}
Default: undefined. Specify a function to be called when the picker has changed. Receives the original select as the first argument, old values as the second, the new values as the third and the original event that triggered this as the fourth.
clicked: function(select, picker option, event){...}
Default: undefined. Specify a function to be called when an option has been clicked. Receives the original select as the first argument, the image picker option as the second and the original event as the third argument.
selected: function(select, picker option, event){...}
Default: undefined. Specify a function to be called when an option has been selected. Receives the original select as the first argument, the image picker option as the second and the original event as the third argument.
limit_reached: function(select){...}
Default: undefined. Specify a function to be called when the limit cap has been reached. Receives the original select as the first argument.

Example:

        $("select").imagepicker({
          hide_select : true,
          show_label  : false
        })

Select data

You can also pass some data directly to the select tag:

data-limit: Optional. If it's a select multiple and set to any value, it'll cap the selectable elements at that value.

Example:

        <select multiple="multiple"
          data-limit='2'
        >

Options data

You can also pass some data on each option element of the select tag:

data-img-src: Required. The url of the image to use as a preview
data-img-label: Optional. If show_label is set to true when calling imagepicker(). Then this content will be used as a label for the displayed image. This will not be escaped so you can actually put HTML here (although I wouldn't recommend it).
data-img-class: Optional. A custom class to be added to the generated picture and container
data-img-alt: Optional. Alt propery for the image

Example:

        <option
          data-img-src='http://www.example.com/image.jpg'
          data-img-label='Just an image!'
          data-img-class="custom-class"
          data-img-alt="Just an image alt!"
          value='42'
        >

Interacting via Javascript

You can also interact directly with the ImagePicker object via JS. To retrieve the object just call .data('picker') on the jQuery element. Example:

      // Initialize the object
      $("select").imagepicker();
      // Retrieve the picker
      $("select").data('picker');

Probably the two more common interactions are to either destroy the ImagePicker or to sync it after modifying the selected options on the select element.

      // Syncs the picker with the current selected values on the 'select' element
      $("select").data('picker').sync_picker_with_select();
      // Destroyes the picker and shows the original 'select' element again
      $("select").data('picker').destroy();

However if you do some heavy changes to the 'select' element like adding or removing options you will need to reinitialize the picker. This will destroy the old version and create a new one.

        // Initialize the picker once
        $("select").imagepicker();
        ...
        // We modify the select element, we need to reinitilize the picker
        $("select").imagepicker();