KNMultiItemSelector is a versatile drop in multiple items selector for iOS projects. It works with both iPhone and iPad for several usage scenarios. See features and screenshots below.

Features:

• Multiple items selector with simple NSArray
• Subclass of UIViewController
• Enable/Disable table index
• Enable/Disable search control
• Enable/Disable recent items
• Optional image with out-of-box caching
• Facebook friends selector demo project

Basic Demo & Facebook Friends Selector Demo

iPhone and iPad screenshots

Requirements

• Xcode 4.2 and above
• You are using ARC for this project
• Minimum deployment target is iOS 4.2

Installation

1. Drag and drop the entire KNMultiItemSelector into your project
2. #import "KNMultiItemSelector.h" in your implementation
3. Add these required Frameworks in your project: ImageIO, CoreGraphics
4. If your project already has SDWebImage you could remove the one bundled with this control
5. See examples below or run KNFBFriendSelectorDemo

Creating array of items

Simply create a NSArray which contains multiple KNSelectorItem. You can have a separate selected value such as user's ID as part of the item.

NSArray * items = [NSMutableArray array];
[items addObject:[[KNSelectorItem alloc] initWithDisplayValue:@"Apple Seed"]];
[items addObject:[[KNSelectorItem alloc] initWithDisplayValue:@"Apple Seed" selectValue:@"appl" imageUrl:nil]];

Optional sorting

There are two built-in sort methods to allow sorting by displayValue or selectValue. You must do this before creating the selector

NSArray * sortedItems = [items sortedArrayUsingSelector:@selector(compareByDisplayValue:)];
NSArray * sortedItems = [items sortedArrayUsingSelector:@selector(compareBySelectValue:)];

Creating and presenting the selector

Create the selector instance using one of the init methods, you have the option to change the title string and the search control placeholder string here

KNMultiItemSelector * selector = [[KNMultiItemSelector alloc] initWithItems:items delegate:self];
// or
KNMultiItemSelector * selector = [[KNMultiItemSelector alloc] initWithItems:items
                                                           preselectedItems:nil
                                                                      title:@"Select a flavor"
                                                            placeholderText:@"Search for something"
                                                                   delegate:self];

Then you can present the selector just like another UIViewController, take note of the UINavigationController.

UINavigationController * uinav = [[UINavigationController alloc] initWithRootViewController:selector];
uinav.modalTransitionStyle = UIModalTransitionStyleFlipHorizontal; // iPhone
uinav.modalPresentationStyle = UIModalPresentationFormSheet;       // iPad only
[self presentModalViewController:uinav animated:YES];

Optional configurations

You must set these properties before presenting the selector

// Turn on/off table index for items, default to NO
selector.useTableIndex = YES;

// Turn on/off search field at the top of the list, default to NO, only recommend for large list
selector.allowSearchControl = YES;

// Turn on/off displaying and storing of recent selected items.
// recentItemStorageKey   : If you have multiple selectors in your app, you need to set different storage key for each of the selectors.
// maxNumberOfRecentItems : Defaults to 5.
selector.useRecentItems = YES;
selector.recentItemStorageKey = @"your_key";
selector.maxNumberOfRecentItems = 5;

Image caching

If you decide to set imageUrl for your KNSelectorItem items. Then these images will be loaded using SDWebImage library. It will handle image caching and loading automatically.

You can get the full source-code from Github: github.com/kentnguyen/KNMultiItemSelector

KNMultiItemSelector is licensed under MIT License Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

TODO

• Custom UItableViewCell class
• Custom row height
• Highlighted search term in result rows
• More language customization
• Supports landscape orientation on iPhone
• Option to use UISegmentedControl to switch modes

Support

For bug report and suggestions to improve the library, please contact me through my Twitter @ntluan or my website kentnguyen.com
Don't forget to buy me a coffee ;)