Foundation 4 Migration Guide

If you're upgrading from Foundation 3.x to 4.0+, this will help you learn the differences.

Foundation 4 Migration Guide

If you're upgrading from Foundation 3.x to 4.0+, this will help you learn the differences.

← Go Home

Getting Started

Foundation 4 was rebuilt from the ground up to be syntactically similar, but not identical, to Foundation 3. Much of what you already know about Foundation still applies, including how to use the Grid, many of the common elements, and how the responsive aspects work (only now the media queries are written opposite because we architected Foundation 4 mobile-first).

With that being said, there are significant differences to be aware of. In some cases, markup had to be modified to support a new case or to be more customizable or extensible. In other cases we've streamlined the framework so that there's less extra styling, so some extraneous classes will no longer take effect.

Read through this guide to familiarize yourself with the changes and you should be in good shape to make the switch.

The Grid

An important change from Foundation 3 to 4 is the grid, specifically the syntax.The syntax may be different, but the way the Grid is actually constructed hasn't changed from 3.

The same concepts apply when building the grid in Foundation 4 — we have a small grid and a large grid. The columns all float next to eachother and have percentage width with a single breakpoint for small devices. The big change is the grid classes are now .small-#.columns and .large-#.columns. We did this to give us tons of control over how we treat the mobile grid. Going mobile first meant four columns wasn't good enough. Now there are a full 12 columns for the small grid and the same for the large.


Along the same lines as the main grid syntax change, we've also updated a few others. Offsets are now written with two separate classes, as well. You can use .small-offset-# or .large-offset-#. If you use the small offset only, it will carry over into the large breakpoint. Using the large offset will override the small one.


We did the same with the centering classes in Foundation 4. You can now choose which grid to center on using the same type of class naming scheme. The classes are .small-centered and .large-centered. Using only the small class will keep it the same past the breakpoint.

Source Ordering

Source ordering works exactly the same way as it did in Foundation 3, but you have to think about it in the opposite way now. Instead of thinking about where you want it for desktop and then ordering for small devices, start small and reorder for large. The syntax is similar as well, .push-#, and there isn't a separate large and small version because that didn't make sense.

View the Grid Docs →

Block Grids

We also updated the block grids. We wanted to make them a little more flexible and architected Mobile First, of course. In Foundation 4, you have access to two separate block grids that can change or stay the same past the breakpoint. The syntax is a little bit different as well. Now you'll use .small-block-grid-# or .large-block-grid-#. The same rule applies here: if you use only the small block grid, the layout will stay the same across the breakpoint. If you want to change the layout, just add the large block grid class to the chain and it will override the small one.

View the Block Grid Docs →


In Foundation 4, we wanted to get rid of dependancies in the core, so we removed things like Modular Scale and Compass. We're still using a modular scale to size our typography, but the functions aren't built in as they were in 3. If you're using Sass, you can easily add it back on top and use it in your own project. We've also changed the typography to be built in ems rather than pixels and have a default body copy size of 16px, which equals 1em.

View the Typography Docs →


Another thing we noticed that could be improved with the rewrite of Foundation was dropdowns. We had various dropdown styles in different UI elements that made building them a little complex and not very flexible. The new dropdown plugin lets you attach a div that can hide/show by clicking the element you put it on. This implementation makes endless possibilities, and we're excited to see how people build off of this. You can have link lists or plain content inside a dropdown.

We've included some sizing classes for these dropdowns as well, which attach a max-width: .tiny, .small, .medium, .large. If the screen is too small the dropdown will still shrink to fit.

View the Dropdown Docs →


For those using CSS, the syntax for buttons hasn't changed. If you are using Sass, you now have access to mixins and variables to make your button creation even more flexible and fun!

View the Buttons Docs →

Button Groups (Now a Navigation Bar as Well)

The button groups in Foundation 4 are exactly the same as they were in 3. You build them out of buttons wrapped in a ul and control the width and stacking with the grid.

An important note: We found it pretty confusing to have a nav bar and a top bar in the core of Foundation. We really like what the top bar gives people and the nav bars didn't do anything really special. By using button groups mixed with our new dropdown plugin, you'll be able to easily create the same UI affordance. To get a full width nav bar, you just wrap the button group in a div and give it the same background color and style.

View the Button Groups Docs →

Dropdown Buttons

Dropdown buttons are essentially the same in Foundation 4 from a style perspective. The main difference is that the dropdown isn't included in the style of a button. Now you'll use the dropdown plugin to add a dropdown to the button itself. These dropdowns can have link lists or content like we mentioned above.

View the Dropdown Buttons Docs →

Split Buttons

Like the aforementioned dropdowns, spilt buttons haven't changed either, from a style perspective. The split isn't a button style and you'll use the plugin to add it to the button itself. These can also have link lists or content.

View the Split Buttons Docs →


We also haven't really changed anything to do with the forms or their syntax. You can still use forms in the same way you're used to!

View the Forms Docs →

Custom Forms

We recently ported changes over to our custom forms that makes them a lot easier to build — and they have a new, sleeker style that matches other form elements better. The syntax is basically the same as before.

View the Custom Forms Docs →


One element that got added to Foundation 4 was a radio switch that contains no JS, but looks amazing! We modeled it after the iOS radio switch, but kept the style simple and lightweight. You simply wrap some input elements and labels inside a div.switch and CSS will do the rest for you!

You have the option to add size classes and radius classes to build the switch that best suits your design. If you are feeling Sassy, we've made mixins and variables that make these switches even more customizable without needing to override a bunch of styles.

View the Switch Docs →

Sections: New Tabs, Accordion and Vertical Nav

A big effort with this rewrite was to make the core even smaller and more flexible. Part of this was removing all images from Foundation, another part was rewriting the JS with Zepto. Part of the JS rewrite included thinking through some of our plugins and asking ourselves if they were worth it. All in all, we trimmed our JS way down.

With Foundation 4, we created this awesome UI element that we call section, which will take on the role of accordion by default, but can be made into tabs or a vertical nav on large devices. See an example of the syntax to the right, the rest can be learned in the docs.

This will create a bit of work for some people, but we think it's worth it to have such a versatile plugin. If you have tabs, you'll need to notice that the content is all held within the container of the section instead of being linked from the outside.

View the Section Docs →

Visibility Classes

We kept the same class names for our visibility classes, but they're now written Mobile First. The list of visibility classes is pretty extensive and can give you quite a bit of control over your layout.

The list of classes are as follows, .show-for- or .hide-for:

  • small
  • medium-down
  • medium
  • medium-up
  • large-down
  • large
  • large-up
  • landscape
  • portrait
  • touch

View the Visibility Docs →

Top Bar

The top bar is a beast from code to syntax. We packed a lot into this UI element and are proud of how people have used it. With the release of Foundation 4, we've slightly rebuilt this plugin to be more efficient and easier to style. Our first pass at the CSS for this was a little sloppy and the desktop first approach made that code cruft even higher. Since we went mobile first with Foundation 4, we were able to add the very basic styles used by the mobile layout for desktop, rather than undo everything we'd already done. This makes the code lighter and easier to override going forward.

Part of this revamp was improving some of the class names and changing the toggle icon to use the ubiquitous "three lines" icon to represent menu; you can also have the words "menu" next to the icon if you want. The class names that changed are:

  • The first ul that holds the title list items now has a class of title-area
  • The list item that hold .toggle-topbar now has another class chained of menu-icon.
    • This adds styles for the icon. You'll also wrap a span around the word.
    • To remove the icon, just remove the span.

View the Top Bar Docs →

Other Components

The rest of the components in Foundation should essentially be exactly the same from a markup point of view. In some cases, we altered the styles slightly to simplify adding styles on top of the default.

Browser Support

Just like Foundation 3, IE7 is bye-bye. This time we've built the code base Mobile First, meaning browsers that don't support media queries get very basic styles (IE8) for the grid and other UI elements. Browsers that support media queries will render the mobile styles if they are below 768px wide and everything else will get the desktop layouts, using percentages to handle width changes.

Need IE8 Grid Support?

We know it can be hard to get clients to ditch support for IE8. We're hoping with the auto-update to IE10 release from Microsoft, we won't need to worry about it anymore. Until then, here's a gist with a grid grid that will work in IE8, just like it did in Foundation 3.

Foundation IE8 Grid
Stay on top of what's happening in responsive design with Responsive from ZURB.

Sign up to receive monthly Responsive Reading highlights. Read Last Month's Edition »