Our DNA is written in Swift

Containing ViewControllers

For a project that I am currently working on I needed to implement a custom container view controller. I was feeling my way forward in the dark for the most part because this does not seem to be a widely used technique. Developers – understandably – favor reusing and skinning existing view controllers over creating new containers.

However there are some scenarios where you should prefer to make your own container because it greatly simplifies your code over trying to bend a UINavigationController or UITabBarController to your will. Do you remember the times when those two where the only two containers available?

I distinctly remember using a UINavigationController with hidden nav bar as a view controller to contain multiple full views. And you probably had do do your own view juggling and animations because for the most part the standard transitions would be useless. Fortunately we can no file this as a fond memory of the past and move on to implementing our own containers.


The first thing to wrap your head around is the notion that besides a hierarchy of views you now also have to have a consistent hierarchy of view controllers. Before iOS 5 people would often create a new view controller and then slap this VC’s view into an existing view hierarchy. Now more!

Nowadays you never would resort to this. Instead you use the mechanisms afforded by UIViewController to add and remove child view controllers.

Another notion is that we’ve trained ourselves to think of view controllers as being responsible for one entire full screen, think of the sub view controllers of a tab bar controller. But ever since UISplitViewController which arrived with the iPad this is no longer the true mantra. Viewcontrollers are supposed to manage a coherent region on the screen, that can be the entire screen for lack of space on an iPhone, but it can also be a content bar at one of the sides of the screen. Like UISplitViewController which has two sub-viewcontrollers, one for the left (“master”) panel and one for the right (“detail”) panel.

UIViewController provides two methods to add a view controller as a child and to remove it later. Those are part of the “UIContainerViewControllerProtectedMethods” category extension for UIViewController:

@interface UIViewController (UIContainerViewControllerProtectedMethods)
- (void)addChildViewController:(UIViewController *)childController;
- (void)removeFromParentViewController;

These two methods do exactly what their names suggest. Though what’s not quite obvious is how you are supposed to use them. And if and how you should combine these with addSubview and removeFromSuperview. Hence this exploration. Note: All this assumes we use ARC.

According to the docs it is up to us to define the kinds of relationships we want to model. Be it only a single VC visible at the time like nav controllers, or multiple that can be reached through tabs. Or even multiple VCs that are sort of like pages.

There are three possible things that you want to be able to do with your sub-viewcontrollers that have slightly different semantics:

  • Add it to your container
  • Remove it from your container
  • Transition to another view controller (i.e. add the new and remove the old)

For any of these you also want to be be assured that the 4 view delegate methods get properly called, as well as the new 2 delegate methods that fire before and after a VC moved to a new parent. Note that a parent of nil means that it was removed.

Why is this attention to the delegate messaging necessary? You probably use the view(Did|Will)(A|Disa)pear methods to do some last setup or teardown and so you are interested that they get properly called. And also there is an ugly warning in the console about unbalanced messages if you get something wrong here.

We’ll dive into greater detail with a sample. Let’s say we want to get an effect similar to a tabbed view controller. i.e. we have an array of view controllers and we want to switch between these. Since this container VC will be our app’s root view controller we want to show the first sub-VC when it shows.

Basic Setup

Let’s put the necessary bare bones IVARs in the implementation because we only need to have access to these inside our own ContainerViewController.

@implementation ContainerViewController
	NSArray *_subViewControllers;
	UIViewController *_selectedViewController;
	UIView *_containerView;

The subVCs will be a static array of view controllers that the developer can set. The selected VC will hold a reference to the currently showing VC and the container view will be the area where we want our sub VC’s view to be positioned. Let’s start by setting up the container view in the container’s loadView:

- (void)loadView
	// set up the base view
	CGRect frame = [[UIScreen mainScreen] applicationFrame];
	UIView *view = [[UIView alloc] initWithFrame:frame];
	view.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
	view.backgroundColor = [UIColor blueColor];
	// set up content view a bit inset
	frame = CGRectInset(view.bounds, 0, 100);
	_containerView = [[UIView alloc] initWithFrame:frame];
	_containerView.backgroundColor = [UIColor redColor];
	_containerView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
	[view addSubview:_containerView];
	// from here on the container is automatically adjusting to the orientation
	self.view = view;

I’ve colored the main view blue and the container view red for clarity. The sub-VCs will go in the red area and be automatically resized if we rotate the device.

The integration in the app delegate is a mere formality, add the import for the header, allocate an instance and set it as root VC.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
	ContainerViewController *container = [[ContainerViewController alloc] init];	
 	self.window.rootViewController = container;
    [self.window makeKeyAndVisible];
    return YES;

Next we need a couple of view controllers to play the role of the sub-VCs. Let’s create a simple UIViewController subclass that has a UILabel as it’s main view, so that we can display something there to tell them apart. Do avoid overcomplicating things for this example we simple take the view’s own description in there. This way we see if the display changes.

- (void)loadView
	// set up the base view
	CGRect frame = [[UIScreen mainScreen] applicationFrame];
	UILabel *label = [[UILabel alloc] initWithFrame:frame];
	label.numberOfLines = 0; // multiline
	label.textAlignment = UITextAlignmentCenter;
	// let's just have this view description
	label.text = [self description];
	self.view = label;

I bet you never before had a view controller which consisted only of a UILabel. For Science! 😉


Next we need to put a couple of these PageViewControllers into an array and have a method that allows us to set this array into our container. Let’s assume that you know how to create a property for the subViewControllers. In the app delegate we have these additional lines:

// make an array of 5 PageVCs
NSMutableArray *tmpArray = [NSMutableArray array];
for (int i=0; i<5; i++)
	PageViewController *page = [[PageViewController alloc] init];
	[tmpArray addObject:page];
// set these as sub VCs
[container setSubViewControllers:tmpArray];

So much for basic setup. Now let’s override the setter for the sub VCs to select the VC at index 0 and present it. Though we cannot present it in the setter, because the view might not have been loaded yet and so our _containerView IVAR is still nil.

- (void)setSubViewControllers:(NSArray *)subViewControllers
	_subViewControllers = [subViewControllers copy];
	if (_selectedViewController)
		// TODO: remove previous VC
	_selectedViewController = [subViewControllers objectAtIndex:0];
	// cannot add here because the view might not have been loaded yet
@synthesize subViewControllers = _subViewControllers;

Instead we do it at the latest possible moment, that would be in the viewWillAppear because here we are guaranteed that the loadView has taken place already. A nice lazy thing, if we find that the selected VC already has self as the parent then there’s nothing to do.

- (void)viewWillAppear:(BOOL)animated
	[super viewWillAppear:animated];
	if (_selectedViewController.parentViewController == self)
		// nowthing to do
	// adjust the frame to fit in the container view
	_selectedViewController.view.frame = _containerView.bounds;
	// make sure that it resizes on rotation automatically
	_selectedViewController.view.autoresizingMask = _containerView.autoresizingMask;
	// add as child VC
	[self addChildViewController:_selectedViewController];
	// add it to container view, calls willMoveToParentViewController for us
	[_containerView addSubview:_selectedViewController.view];
	// notify it that move is done
	[_selectedViewController didMoveToParentViewController:self];

The above shown sequence takes care of calling the viewWillAppear, viewDidAppear, willMoveToParentViewController and didMoveToParentViewController. Notice that all but the last are done for you automatically, but for some strange reason the didMove is not. So we have to do that manually. Upon starting our Demo we now see the VC at index 0.

Next we add the capability to transition from one VC to the next.


To move between the child VCs we’ll add a swipe gesture recognizer to our container. If we swipe left we want to go to the VC with a lower index in the array. If we swipe right we want to go higher. No wrapping. In loadView we add:

// add gesture support
UISwipeGestureRecognizer *swipeLeft = [[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(swipeLeft:)];
swipeLeft.direction = UISwipeGestureRecognizerDirectionLeft;
[view addGestureRecognizer:swipeLeft];
UISwipeGestureRecognizer *swipeRight = [[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(swipeRight:)];
swipeRight.direction = UISwipeGestureRecognizerDirectionRight;
[view addGestureRecognizer:swipeRight];

And the implementation of swipe is as follows. For simplicity’s sake we use two separate gesture recognizers because Apple does not provide an easy way to determine the swipe direction if you combine to directions.

- (void)swipeLeft:(UISwipeGestureRecognizer *)gesture
	if (gesture.state == UIGestureRecognizerStateRecognized)
		NSInteger index = [_subViewControllers indexOfObject:_selectedViewController];
		index = MIN(index+1, [_subViewControllers count]-1);
		UIViewController *newSubViewController = [_subViewControllers objectAtIndex:index];
		[self transitionFromViewController:_selectedViewController toViewController:newSubViewController]; 
- (void)swipeRight:(UISwipeGestureRecognizer *)gesture
	if (gesture.state == UIGestureRecognizerStateRecognized)
		NSInteger index = [_subViewControllers indexOfObject:_selectedViewController];
		index = MAX(index-1, 0);
		UIViewController *newSubViewController = [_subViewControllers objectAtIndex:index];
		[self transitionFromViewController:_selectedViewController toViewController:newSubViewController]; 

The logic to transition from one VC to another we package in transitionFromViewController:toViewController:. This is the really interesting part. There is a convenient method that again takes care of most of the boring work of adding and removing views. And again some non-obvious additional messaging is necessary to get it perfect.

- (void)transitionFromViewController:(UIViewController *)fromViewController toViewController:(UIViewController *)toViewController
	if (fromViewController == toViewController)
		// cannot transition to same
	// animation setup
	toViewController.view.frame = _containerView.bounds;
	toViewController.view.autoresizingMask = _containerView.autoresizingMask;
	// notify
	[fromViewController willMoveToParentViewController:nil];
	[self addChildViewController:toViewController];
	// transition
	[self transitionFromViewController:fromViewController
							completion:^(BOOL finished) {
								[toViewController didMoveToParentViewController:self];
								[fromViewController removeFromParentViewController];

And with that we have our transitions in the can.

You have a number of UIViewAnimationOptionTransition-s available, but you don’t have to settle for these. You can also pass 0 for the options and instead provide all animations you like the two views to execute in the animations block.

Before I discovered is method I was using the previous method of animating the views. Though this has a side-effect that we might not like in this case. Typically you want the “will” delegate methods to fire before the transition and the “did” to follow afterwards. If you animate the views yourself then iOS 5 will take care of sending these messages for you but it does so together. This looses us the ability to differentiate between stuff we want to do before and after the appearing and disappearing of the view controller.


It took me quite a bit of experimenting to also get all the messaging happening and equally balanced. The above sample has that working as it should.

But once you do figure out the two techniques outlined in this article you are on the road to implement your own view controller containment like you never did anything else.

One thing that I wasn’t able to figure out so far is why the transition method always adds the new view controller’s view to the container view controller’s main view. This simplifes the process somewhat because you don’t have to know at which stage in the transition it is ok to add and remove the views. But at the same time you might have a situation where you don’t want the animation to occur over the entire area of the container view controller.

For this scenario I can only think of covering up the parts with extra sub views. Or we could stack multiple container view controllers and have one to only cover the region where where have the container view. This could then clip its subviews and thus be only care for this area.

The main advantage of any kind of view controller containment is that rotation messages (should|will|did) reach the lowest leaves of your view controller tree. Unless you disable that by means of overriding automaticallyForwardAppearanceAndRotationMethodsToChildViewControllers and returning NO.

But who would really want that when we have waited for so long for public API to have these being forwarded? Working with view controller containers I get a feeling that they greatly simplified creating complex user interfaces consisting of multiple parts.

The project for this tutorial is in my Examples GitHub repository.

Categories: Recipes


  1. Thanks for the sample and demo!

    Two things to add:

    1) Re: “One thing that I wasn’t able to figure out so far is why the transition method always adds the new view controller’s view to the container view controller’s main view. This simplifes the process somewhat because you don’t have to know at which stage in the transition it is ok to add and remove the views. But at the same time you might have a situation where you don’t want the animation to occur over the entire area of the container view controller.”

    I would assume, one can just create his own transition, adding the subViewController’s views to the container view whenever suitable by just not using the “transitionFromViewController:toViewController:duration:options:animations:completion:” method at all. I cannot see, that the methods does any more than being a convenience method, because all control methods (add/remove child are called under your control). This is comparable to the viewWillAppear method which is like:
    a) addChildViewController (which calls willMoveToParentViewController)
    b) add child view to container view
    c) notify child view controller about move ( calling didMoveToParentViewController)

    2) Also (as far as I could check), the code comments for

    // add as child VC
    [self addChildViewController:_selectedViewController];

    // add it to container view, calls willMoveToParentViewController for us
    [_containerView addSubview:_selectedViewController.view];

    are not quite ok, the “addChildViewController” will trigger the “willMoveToParentViewController” callback, not addSubview

  2. to my point 1): my assumption was wrong, transitionFromViewController:toViewController:duration:options:animations:completion: does more work, as it will trigger the complete view lifecycle methods (viewWillAppear/Disappear, etc)

  3. Great post, I have been working with container view controllers the last couple of weeks, building a hierarchy of rather complex ones.

    One question. You add the view controllers to the container view in viewDidAppear:. What if you want to call setSubViewControllers: after the view has been loaded to completely switch the entire set of view controllers? In this case the content view will not be updated.

    My scenario is that I have a custom container controller similar to a UITabBarController, with a property method setContentViewController:, i.e. the current sub view controller. This means view controllers are not set all at once as an array (like in your example) but rather on-demand when pressing some button of the container view controller.

    This also means setContentViewController: may be called once before the view appears, when setting the initial content view controller, and then when switching content view controller.

    One approach I can think of is to check isViewLoaded in setContentViewController: and if so handle adding the view there, otherwise it will surely be loaded in viewWillAppear:.

  4. I have a similar project in development, where this technique could be very useful.

    I have a Split View Controller, that I want to swap out for a new view .. Then when finished, I want to swap back. (The sub controllers in the split view, employ Sensible Cocoa by the way).

    I have yet to figure out how to swap to the single view and maintain the ability to rotate the screen.

    Do you think by using the containment would work with split views? I’ll try it anyway.. and let you know.. But thanks for the great tutorial, and if you think I’m barking up the wrong tree, let me know..


  5. You need to simply present the single view and dismiss it when you want to get back to the split view. That was even possible with iOS 4, via presentModalViewController.

  6. Yep, it works fine when I present the view as a Modal View. I may have to put up with that. Is there no other way?


  7. The same functionality as modal view controller presenting you can build yourself with the view controller containment methods available as of iOS 5.

  8. Thanks for that, great stuff. I was going to hack a UITabBarController and hide the tab bar before I found this. Hacking the UITabBarController isn’t hard… but it’s a hack nonetheless. This is cleaner.

  9. Great tutorial thanks for the help!

    Quick note: Your swipeLeft and swipeRight methods are missing a

    _selectedViewController = newSubViewController;

    line in the sample code on the site. Looks correct in github tho.

    thsanks again

  10. One question: I think need to implement following code in viewWillAppear since there’s no need to execute once again. Is that right?

    static dispatch_once_t toke;
    dispatch_once(&toke, ^{
    // add as child VC
    [self addChildViewController:_selectedViewController];

    // add it to container view, calls willMoveToParentViewController for us
    [_containerView addSubview:_selectedViewController.view];

    // notify it that move is done
    [_selectedViewController didMoveToParentViewController:self];

  11. Great tutorial! Just one thing though – you could easily check which gesture recognizer is which in one method by checking the gestureRecognizer’s direction instead of using two separate methods like so:

    – (void)handleSwipe:(UISwipeGestureRecognizer *)gestureRecognizer
    if (gestureRecognizer.direction == UISwipeGestureRecognizerDirectionLeft) {
    //do something
    } else {
    //do something else

  12. Thanks for the sample code.

    Hector’s solution doesn’t work. (at least I couldn’t get it to work). It always gave me the same value for direction and that value was the sum of the directions that I enabled when I created the gesture recognizer.

  13. Hi, I have a problem I implement your custom container and I added two different viewController , ViewControllerOne and ViewControllerTwo . First I display ViewControllerOne but when I did a leftGesture it display the second ViewController not on all the screen I want that that the ViewControllerOne still visible behind the second Controller: ViewControllerTwo

  14. Good post, I was trying to do exaclty the same but via Interface Builder I had a lot of problems resizing the viewcontrollers, this seems to work good, only, I would like to add a button in each child ViewController to go next, instead of touch everywhere on the screen… any advise on how to do it properly?

  15. The reason that didMoveToParentViewController: is not automatically called when adding, and `willMoveToParentViewController:` is not automatically called when removing, is that the transition can be animated.

  16. Hi,
    Thanks for sharing such an amazing work with good and brief explanation.
    I have been working with containers for last few weeks. But am facing one trouble that i have created a scene which is been shared between multiple containers.Everything working fine .Only problem is that when i run this on iPad frame of view of view controller which is added in container does not conform to the bounds of container .So view moves out of container from top ,as i unchecked the clip subviews option.

    My question is how can i control the size of view added to container.

    this is my code

    ColorPaletteController * palette = [self.storyboard instantiateViewControllerWithIdentifier:@”ColorPalette”];
    [self addChildViewController:palette];
    [palette didMoveToParentViewController:self];
    palette.view.autoresizingMask = _colorContainer.autoresizingMask;
    palette.view.center = _colorContainer.center;

    palette.view.frame = _colorContainer.bounds;
    // palette.view.sizeToFit = _colorContainer.bounds.size;

    [_colorContainer addSubview:palette.view];

  17. Helped me in transitioning of views with swipe Gesture. Though i was working with Custom UIViewController Containers, it help[ed me. Thanks for the awesome post..