jQuery plugin: Easy List Splitter

Blog

After a couple of hours spent on the lookout for a simple and clean jQuery plugin to columnize lists with no success, I decided to create my own one. It took me a couple of nights but the result is pretty good and hopefully it will help you whenever you need to split a list into different columns.

Version 1.0.2 has just been released!

To keep it as simple and flexible as possible I didn’t set any CSS rules or column widths in the JavaScript. The plugin simply generates clean and valid HTML code that you can then style as you wish, floating the lists or doing whatever you like.

The plugin will get your list, wrap it into a container div, generate as many lists as the number of columns you require and evenly split the list items into the different list elements. If the list items are not enough to evenly fill in all the columns, the plugin will hide the columns in excess (this might happen only if you’re ordering your list items vertically as per default).

You can see the Easy List Splitter Plugin in action here. As usual, all of that will be realized in an unobtrusive and accessible way.

What’s new?

Easy List Splitter keeps the HTML to the minimum. No unnecessary elements or inline styles are added to the code. You’ll get a clean plain HTML with some classes that you can use as hooks to easily style your lists. Choose whether to order your list items vertically or horizontally. You can then decide whether to modify the default CSS or apply a new one.

Features

  • Split any ordered (OL) or unordered (UL) list
  • Define the number of columns in which you want your lists to be split
  • Target more than one list on the same page and set different number of columns for each of them
  • CSS is completely separated from the javascript. You can either modify the default one or create your own
  • A class “last” will be added to each last UL or OL so that you can easily remove side padding or margin
  • NEW: Easy List Splitter Plugin preserves nested lists now!
  • NEW: You can now choose whether to order your list items vertically or horizontally
  • There is no need to modify your HTML. Just target your list element using any of the JQuery-selectors.
  • No dependencies at all!
  • Plugin size 4KB!

Planned additions

I’m totally open for suggestions. Here are some future additions that came out of the comments below:

  • Allow for custom class on the wrapper div

Usage

Here is the HTML code for a simple list:

We need now to  include three different files in the head of the document: the jQuery library, the EasyListSplitter plugin and our Script file from where we’re going to call the plugin. If you do not know yet how to set up your jQuery environment, you can find a detailed explanation in my first jQuery tutorial, otherwise just keep reading!

You can target any list elements using the powerful JQuery-selectors. The plugin requires one argument only, the column number. Here is a sample that shows you how to activate the plugin using a class. Bare in mind that you can also target the list element straight away (eg. $(‘ul’)). If you don’t set the colNumber argument, the plugin will generate two columns by default:

$('.my-list').easyListSplitter({ colNumber: 3 });

Also, if you don’t specify the direction parameter, the plugin will order the list items vertically by default as follows:

list item 1      list item 4      list item 7
list item 2      list item 5      list item 8
list item 3      list item 6

With version 1.0.1 you can now choose whether ordering your list items vertically as above or horizontally, getting the following layout:

list item 1      list item 2      list item 3
list item 4      list item 5      list item 6
list item 7      list item 8

What you have to do is simply specify the direction:’horizontal’ parameter when you call the plugin:

$('.my-list').easyListSplitter({
   colNumber: 3,
   direction: 'horizontal'
});

Apply your CSS

Here comes the easiest part. The plugin has just split our list into three different lists. What we have to do to get a multi-column list is simply apply some CSS. You can either modify the default one or apply your own. Basically we just want to set a float property to all the lists and apply some margin.

Conclusion

This plugin is totally free. A link back to this post and a small donation would be much appreciated! You can get the Easy List Splitter plugin full sample here (8KB – zip file) or get the JavaScript file only below.

Buy us a beer!

Posted on Thursday 30 September 2010 at 10:26

69 commenti all'articolo

  1. Brently says:

    I have posted for help in stackoverflow, but no one seems to want to help me there. Here is the link to my question:http://stackoverflow.com/questions/21651855/i-cannot-get-easy-list-splitter-to-actually-split-my-list-into-columns. I have followed all instructions for the EasySplit and it will not work.

  2. Great plug in! But I’ve got a problem: I’m developing a Single Page Application, so the transition between pages does not request a new page from the server. Also my content is dinamically added to each page-content. So, when I first enter a page with a list, EasyListSplitter works fine. If I move to another page and return, the itens are duplicated! And this process continues: each time I re-entered the page, my list itens are duplicated (6 itens to 12 itens to 24 itens…). Is there any way to “reset” the list or function to prevent EasyLIstSplitter to behave this way?

  3. Peter Benoit says:

    Does not appear to keep OL numbering across columns? So if there were 6 items in a list, and the list had 2 columns with 3 items in the first column, I would expect the second column to start with 4, but it resets to 1.

  4. Furzery says:

    Hey there.. is there a way to let the code make his own amount of rows by looking at the amount of ‘s there are?

    For example there can be 10 ‘s below eachother, after that a new column will be created untill 20 and than a third column is made for the 21st

  5. Justin says:

    This doesn’t work for dynamically created lists, it results in duplication of the records.

  6. alper says:

    Hi,
    This is very useful add-on.. Is it possible to make this script as a joomla plugin?

  7. Sarah says:

    This is awesome, and I mean that
    thanks for all the sources you’ve put here

  8. Ishiki says:

    Isnt working for me on Chrome and IE 9.
    Uncaught TypeError: Object has no method ‘appendChild’

  9. Lore says:

    I would like the option to leave out the container div. I’m trying to split the lists, then use Masonry on the split lists, but all these extra divs are making me confused & it’s not working. How about an option not to wrap the container? Thanks.

    Also, I haven’t seen anywhere a plugin that will split a list and then align the blocks to bottom. Even Masonry won’t do this, as far as I can tell from the documentation.

  10. brand new travel agency says:

    It’s awesome to pay a visit this web site and reading the views of all colleagues concerning this article, while I am also zealous of getting knowledge.

  11. Cezary says:

    HI, how can I do ?

    List Item
    Sub Item
    Sub Item
    Sub Item

    List Item
    List Item
    List Item
    List Item

    List Item
    List Item
    List Item
    List Item

  12. Alex says:

    Much appreciated!

  13. MOhamed IJas says:

    I have modified the plugin to add an extra class like ‘splitted’, So when u style the columized ULs, it will be easy.

    var j=1;(function(a){a.fn.easyListSplitter=function(b){var c={colNumber:2,direction:”vertical”};this.each(function(){var d=a(this);var e=a.extend(c,b);var f=a(this).children(“li”).size();var g=Math.ceil(f/e.colNumber);var h=a(this).attr(“class”);for(i=1;i<=e.colNumber;i++){if(i==1){a(this).addClass("listCol1 splitted").wrap('’)}else if(a(this).is(“ul”)){a(this).parents(“.listContainer”+j).append(”)}else{a(this).parents(“.listContainer”+j).append(”)}a(“.listContainer”+j+” > ul,.listContainer”+j+” > ol”).addClass(h)}var k=0;var l=1;var m=0;if(e.direction==”vertical”){a(this).children(“li”).each(function(){k=k+1;if(k>g*(e.colNumber-1)){a(this).parents(“.listContainer”+j).find(“.listCol”+e.colNumber).append(this)}else{if(k<=g*l){a(this).parents(".listContainer"+j).find(".listCol"+l).append(this)}else{a(this).parents(".listContainer"+j).find(".listCol"+(l+1)).append(this);l=l+1}}});a(".listContainer"+j).find("ol,ul").each(function(){if(a(this).children().size()==0){a(this).remove()}})}else{a(this).children("li").each(function(){m=m+1;if(m<=e.colNumber){a(this).parents(".listContainer"+j).find(".listCol"+m).append(this)}else{m=1;a(this).parents(".listContainer"+j).find(".listCol"+m).append(this)}})}a(".listContainer"+j).find("ol:last,ul:last").addClass("last");j=j+1})}})(jQuery)

  14. dee says:

    hey,
    is there some sort if support on this?
    done the css/the js/ the html

    clearly im missing something,
    is there a support email I can get you on?

    Thanks!

  15. Gary Byrd says:

    Hello,

    So far I am luvin’ this little plugin.

    I am attempting to implement it with a navigation system where my sub-level list items are columnized.

    The trouble I am having is that I can not get the script to columnize sub-items … it only wants to columnize top-level list items.

    Example:

    List Item
    List Item
    List Item

    Sub Item
    Sub Item
    Sub Item

    List Item
    List Item

    Is it possible to columnize only the sub-level items?

    Thanks

  16. Sandra says:

    Nice work :) Very usefull for my project.

    Two little questions though:
    - Is there a way to center the whole list. I tried on dozens of different ways, but nothing seems to work. And since in your demo all lists are aligned left too …

    - I adjusted my script.js to 10 colums, but it is showing only 8, and yes, there is definately space for at least one more (at first I had more items and then there were showing 9)

    Cheers!

  17. Valentin GUENICHON says:

    Great !!
    In the Santa’s stocking I would add the ability to choose where the list should split (position number of the element(s))

  18. Eric Curtis says:

    Thank you for the plugin, it worked like a charm on a site I am developing.

    Not sure if you are interested, but I have been adding many great utility functions like this to my github watch list and I was wondering if you might consider adding your code there.

  19. Michal says:

    Is there a way to columnize a hidden list? My list is initially hidden (dropdown menu).

  20. Sam says:

    That only works if you want a horizontal list. What this plug-in does is create a vertical list.

  21. Very nice. Thank you for sharing! It saved me a lot of time….
    Website Design London

  22. I found something with nested list that shoud be fixed I think. I have a nested list where the each item contain list with following number of items:
    item 1. contains 11 items
    item 2 contains 1 item
    item 3 contains 2 items
    item 4 contains 1 item
    item 5 contains 5 items
    item 6 contains 1 item
    item 7 contains 1 item

    so if splitted into 3 columns the first column is the very tall in comparisson to others because it is splitted by number of parent items without taking care of number of children items inside every parent.
    so first column is:
    item 1. contains 11 items
    item 2 contains 1 item
    item 3 contains 2 items

    second column is:
    item 4 contains 1 item
    item 5 contains 5 items
    item 6 contains 1 item

    and last column is:
    item 7 contains 1 item

    If you count all items together column 1 contains 17 items(3 parent & 14 children) column 2 contains 7 items(3 parent & 7 children) and last column shows 2 items(1 parent and 1 children)

    Is it possible to make option to count all items together and divide whole number of items by number of columns?

  23. Tamara says:

    Can anyone give me exactly what should be in this script.js file ()

    ?? Beginner :)

    Thanks

  24. julie says:

    thanks :) saved me a bunch of time

  25. Rajasekar says:

    Really Nice. good one./

  26. Web Design says:

    Thanks for the plugin. Other plugins found the need to force inline CSS. How silly! Thanks for keeping the results clean for CSS. My suggestion would be to even the columns out a bit more. I have a list with 7 items that I divided into 3 columns and the plugin has created the columns as: 3 items, 3 items, 1 item. Should probably be: 3 items, 2 items, 2 items. Will keep the picky designers happy! Thanks again!

  27. kampret says:

    very nice ………….

  28. gmclelland says:

    Sorry, I mean’t to say change the .listCol1 to something like .listCol1of4 or .listCol2of3.

  29. gmclelland says:

    Love the plugin, very useful.

    Couple of feature requests:

    1. Make column number dynamic for use in CMSs. When using a CMS you don’t always know the amount of list items you will have to split. Depending on how many list items you might want to split into different columns. For example, if the number of list items is greater than 20 use 4 columns else use three columns.

    2. Add classes to the list items like .1of3 or .2of4, this way you can style the items ahead of time. This would better support dynamic column styling.
    The OOCSS framework uses classes similar to that for it’s grid layout classes.
    http://github.com/stubbornella/oocss/blob/master/core/grid/grids.css

    Thanks

  30. Adhi says:

    Nice useful article keep posting like this.. Thanks for sharing this info.
    My Blog

  31. Bartezz says:

    Really nice plugin! Although folks have reqeusted to preserve nested links I would like to request making this a setting.

    My list consists of nested lists with a total depth of 3.

    For instance;

    Vehicles
    - Man-powered
    – Unicylcle
    – Bicycle
    – Bigwheel
    - Motorized
    – Aeroplane
    – Car
    – Jetski
    – Motorcycle
    – Tank
    – Train
    Colors
    - Primary colors
    – Red
    – Yellow
    – Blue
    - Other colors
    – Magenta
    – Yellow
    – Cyan
    – Black

    It would be cool if this list was split, into let’s say 5 columns, it would split them as followed;

    Vehicles
    - Man-powered
    – Unicylcle
    – Bicycle
    – Bigwheel

    - Motorized
    – Aeroplane
    – Car
    – Jetski
    – Motorcycle

    – Tank
    – Train
    Colors
    - Primary colors
    – Red

    – Yellow
    – Blue
    - Other colors
    – Magenta
    – Yellow

    – Cyan
    – Black

    Hope I’ve explained well :) If I did, do you think this is something you would be able support as a feature?

    Cheers

  32. great ! i added a link from my web site Javascript Plugins

  33. Hey guys, I just launched a new version of the Easy List Splitter Plugin (1.0.2)… it now preserves nested lists!

  34. Sweet! Saved me a lot of time.

    Thank you.

  35. Really nice plugin – I hope that nested ULs will be fixed soon. :)

  36. Eric Curtis says:

    Thank you for the plug-in. Quick question it works but the page is rendering the list complete and then splitting it into two which results in a quick flash when the page is loading. Any suggestions on how to avoid this?

  37. Mike Knowles says:

    Exactly what I needed. The content even wraps as expected when an individual li exceeds the defined width. Thank you!

  38. Sven says:

    Great plugin, but when will the nested list feature be implemented? I need it soon. :)

  39. This is very nice. I went looking for something along these lines. Another plugin weighed in @ 12k MINIMIZED. Looked like 2x or 3x the code this has. Your code looks short and sweet, and I’m using it – thanks!

  40. Emran Hasan says:

    Hi There,

    Nice plugin. I had a need of using it to split a long list of form elements based on dl-dt-dd markup. I was able to achieve that pretty easily – thanks to your clear and easy to follow code. I’m planning to post that as a short blog in my site with a link to this. Lemme know if that’s okay.

    Thanks

    Emran

  41. Viki Pandit says:

    Nice Work, but I didn’t get the idea of using Javascript when a minimal css would suffice?

    Thanks,
    viki

  42. Fero says:

    Please delete previous comment, I should really think first and then click enter. It works like dream. Thanks

  43. Fero says:

    I think it is not working with 1.4.2 jquery. Only think I do to test is maki list and use your script with #defined and it splits into 2 parts but it wont move right to be on same horizont. Am I doing something wrong ?

  44. Jason says:

    My issue now is that I am unable to filter the list items using any jquery filter by class. I’m assuming this is because your plugin splits the lists into seperate lists?

    any workaround?

  45. Jason says:

    Now I only have one issue. I am trying to filter the list items and any filter I try is only working on the first column. I can’t seem to find a way for any filter to work on the entire group.

    help?

    thanks so much!

  46. Jason says:

    I have been banging my head for days looking for a way to filter divs that are laid out with .masonry. But filtering lists is doable – enter your plugin. I can get a layout similar to masonry (divs float vertically instead of horizontally) and be able to use quicksand or some other filter.

    My hats off to you.

  47. Fero says:

    Excellent plugin, really helpful tool to have …

  48. Biju Subhash says:

    Nice plugin….
    and cool web site and the paintbrush too….

  49. Liam says:

    Hi there.
    I added a first class to the first list item and a general class to them all.
    It is useful for to have these in there.

    I am modding this as well so it can support adding Headers for each new list (a h5 for example)

    My modding goal is so you can properly use this great plugin for mega drop downs in a CMS which can only handle a normal list.

  50. Hi guys, thank you all for your comments!

    @Alan: I’m not sure if that’s something that needs to be part of the plugin itself. Getting classes on even/odd lists and list items is very easy and can be achieved by adding the following code to your script file. Make sure you add this after the call to the plugin.

    $('ul[class*="listCol"],ol[class*="listCol"]').each(function(){
      $(this).parent().find('ul:even,ol:even').addClass('even-list');									 
      $(this).find('li:even').addClass('even-row');
    })

    @George Connor: Yeah, you’re absolutely right. I will definitely make sure that nested lists are preserved with the next release of the Easy List Splitter plugin.

    @Chris From Detroit: Anchors are not required at all. All you need is a simple ordered or unordered list. Simple text works fine

    @Ben: Thanks Ben, I’m glad you like the paintbrush ;-)

    @Luca Goria: I know!!! That’s just awesome. I couldn’t believe that my plugin was tweeted by the Smashing Magazine guys!

    @Acanski Petar: That’s true only when all the list items have the same height. In fact, if they have different heights (e.g. one item goes on two lines) and you simply float the LIs, the list items on the next lines will get a wrong positioning. Not sure, if I made myself clear. It’s probably easier to understand if you try it yourself.

    @Ryan Chouinard: That’s another good suggestion! I will definitely implement the custom class in the new release. Thanks!

  51. Ryan Chouinard says:

    Very nice! It *almost* meets a requirement I have in a current project. This may serve as a good starting point rather than trying to code something up completely from scratch.

    The main requirement I have is adding a custom wrapper / pre-and-post-fix to the split lists. For example, I need to take a list like ul>li*40 and make it (div.myClass>ul>li*10)*4. Hope my shorthand makes sense, but the idea is that if this plugin allowed a custom wrapper, it would be pretty close to perfect! So, I guess that’s my suggestion for a future release.

    Anyway, thanks for the contribution, it’ll definitely save me an afternoon of coding.

  52. comunicarte says:

    Nice Stuff! :)

  53. For direction: ‘horizontal’ you don’t need JS. That can be done with CSS only.

  54. This is great as we needed something just like this for when we are describing our courses. One long list is soo boring, this splits it up nicely.

    Thanks.

    !

  55. Luca Goria says:

    Spettacolo è stato twittato anche su Smashingmag, la bibbia del web!

  56. Allan says:

    Ah, I see, this maintains the vertical sort; what I said would sort sequential items next to each other rather than above/below.

    Nice work :)

  57. Allan says:

    Couldn’t you just do this with CSS? Set a width and height on the UL (or on a container div), set a divisible width on the LIs and float them left.

  58. Pol Moneys says:

    thanks for sharing, sweet. split and win.

  59. Mike says:

    Ha, this is awesome. I’ve been hesitating to work on a project since I was going to need something exactly like this. Thanks.

  60. Chad says:

    Thank you for sharing this. I had an issue a few weeks back that would have needed this.

  61. Ben says:

    As cool as the paintbrush. Nice!

  62. TMarsiglia says:

    Very nice! :)

  63. Chris From Detroit says:

    Are anchors required inside these lists?

    I was wondering if the lists could contain just text in this format:

    Quisque facilisis erat a dui.
    Quisque facilisis erat a dui.

  64. Víctor says:

    Very nice. Thank you for sharing!

  65. George Connor says:

    Very nice.

    It would be cool if lists nested inside column items could be preserved.

  66. Nice work! That’s a neat little plugin. Since many menus are designed using lists one can arrange them with column layouts with your code.

    Thx for sharing it.

    ubuntu administrator

  67. Alan says:

    One suggestion is to have the option of adding a class for even or odd rows and columns (even_row, odd_column). That way people can style the contents of the columns and rows easily with css and have alternating backgrounds and other effects.

Leave a comment

Please rate this article and help us plan future posts. Comments are moderated. Do not spam for any reason. Ever!