Collections
Notice: This component will be deprecated over the next few months in favor of the Cards and List components. See our public tracker for more details on timing and the deprecation plan.
Collection view classes that adhere to Material Design layout and styling.
Design & API Documentation
- Material Design guidelines: Collection List Specs
- API: MDCCollectionViewController
- API: MDCCollectionViewEditing
- API: MDCCollectionViewEditingDelegate
- API: MDCCollectionViewStyling
- API: MDCCollectionViewStylingDelegate
Installation
Installation with CocoaPods
To add this component to your Xcode project using CocoaPods, add the following to your Podfile:
pod 'MaterialComponents/Collections'
Then, run the following command:
pod install
Overview
The Collections component consists of a set of collection view related classes that adhere to
Material Design layout and styling. Typically you will subclass the MDCCollectionViewController,
which in turn subclasses UICollectionViewController. This controller provides the collection view
used as its content.
In addition, MDCCollectionViewController also provides two key properties used to style and
interact with the collection view. Firstly, the styler property, which conforms to the
MDCCollectionViewStyling protocol, provides methods and properties to change the styling of the
collection view. The default styler values will provide a look and feel consistent with Material
Design principles, however it is also customizable. Secondly, the editor property, which conforms
to the MDCCollectionViewEditing protocol, allows putting the collection view into various editing
modes. Some of the available editing interactions are swipe-to-dismiss sections and/or index paths,
multi-select rows for deletion, and reordering of rows.
The MDCCollectionViewController conforms to both the MDCCollectionViewStylingDelegate and
MDCCollectionViewEditingDelegate protocols which provide a mechanism for your subclasses to
set styling and editing properties both at index paths as well as for the entire collection view.
By implementing the editing delegate methods, you may receive notifications of editing state changes
allowing your data to stay in sync with any edits.
Table of Contents
- Importing
- Use
MDCCollectionViewControlleras a view controller - Provide own UICollectionView
- Styling the collection view
- Editing the collection view
Usage
Importing
Before using Collections, you'll need to import it:
Swift
import MaterialComponents.MaterialCollections
Objective-C
#import "MaterialCollections.h"
Use MDCCollectionViewController as a view controller
The following four steps will allow you to get a basic example of a MDCCollectionViewController
subclass up and running.
Step 1: Subclass MDCCollectionViewController in your view controller interface.
Swift
import MaterialComponents.MaterialCollections
class MyCollectionsExample: MDCCollectionViewController {
}
Objective-C
#import "MaterialCollections.h"
@interface MyCollectionsExample : MDCCollectionViewController
@end
Step 2: Setup your data.
Swift
let colors = [ "red", "blue", "green", "black", "yellow", "purple" ]
Objective-C
NSArray *colors = @[ @"red", @"blue", @"green", @"black", @"yellow", @"purple" ];
Step 3: Register a cell class.
Swift
self.collectionView?.register(MDCCollectionViewTextCell.self,
forCellWithReuseIdentifier: reusableIdentifierItem)
Objective-C
[self.collectionView registerClass:[MDCCollectionViewTextCell class]
forCellWithReuseIdentifier:kReusableIdentifierItem];
Step 4: Override UICollectionViewDataSource protocol required methods.
Swift
override func collectionView(_ collectionView: UICollectionView,
numberOfItemsInSection section: Int) -> Int {
return colors.count
}
override func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
var cell = collectionView.dequeueReusableCell(withReuseIdentifier: reusableIdentifierItem, for: indexPath)
if let cell = cell as? MDCCollectionViewTextCell {
cell.textLabel?.text = colors[indexPath.item]
}
return cell
}
Objective-C
- (NSInteger)collectionView:(UICollectionView *)collectionView
numberOfItemsInSection:(NSInteger)section {
return colors.count;
}
- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView
cellForItemAtIndexPath:(NSIndexPath *)indexPath {
MDCCollectionViewTextCell *cell =
[collectionView dequeueReusableCellWithReuseIdentifier:kReusableIdentifierItem
forIndexPath:indexPath];
cell.textLabel.text = colors[indexPath.item];
return cell;
}
Provide own UICollectionView
It is possible to use the MDCCollectionViewController class while providing your own
UICollectionView subclass. That provided collection view may still receive styling and editing
capabilities that the MDCCollectionViewController class provides.
Swift
override func viewDidLoad() {
super.viewDidLoad()
// Here we are setting a custom collection view.
self.collectionView = CustomCollectionView(frame: (self.collectionView?.frame)!,
collectionViewLayout: (self.collectionViewLayout))
...
}
Objective-C
- (void)viewDidLoad {
[super viewDidLoad];
// Here we are setting a custom collection view.
self.collectionView = [[CustomCollectionView alloc] initWithFrame:self.collectionView.frame
collectionViewLayout:self.collectionViewLayout];
...
}