Upgrading From Foundation 4

Need to upgrade from Foundation 4? No problem. This handy migration guide makes it super easy!

Upgrade your Rails project

Change the following line in your Gemfile:

gem 'zurb-foundation'


gem 'foundation-rails'

Then run bundle install.

Upgrade using our CLI and Compass

Before continuing you'll need to install the following on your system:

Our CLI can help you upgrade your Foundation 4 project to Foundation 5. It can be installed using the following commands in terminal:

gem install foundation foundation version #=> should say v1.0.3 or higher

So let's assume you have a project in ~/Sites/PROJECT_NAME. To upgrade it to Foundation 5 you would run the following in terminal:

cd ~/Sites/PROJECT_NAME foundation upgrade

Upgrade manually with Compass

Before continuing you'll need to install the following on your system:

Starting in Foundation 5 there's no longer a Compass extension. Instead we use bower to keep Foundation assets up to date within your project. Here's how you can update your project:

Step 1: Create a bower.json file

In the root of your Compass project create a file called bower.json with this content:

{ "name": "PROJECT_NAME", "dependencies": { "foundation": "~5.1.0" } }

Step 2: Install Foundation 5

Now run bower install. This will create a directory called bower_components/ in your project. Foundation's Sass and JavaScript files will be placed in the bower_components/foundation folder.

Step 3: Tell Compass where Foundation resides

You'll want to update your config.rb folder to change this line from:

require "zurb-foundation"


add_import_path "bower_components/foundation/scss"

Any references to the JavaScript files in your project will have changed. Links to Foundation JavaScript files should be changed from:

<script src="javascripts/foundation.min.js"></script>


<script src="bower_components/foundation/js/foundation.min.js"></script>

This will ensure that when you run bower update to fetch the latest version of Foundation that the JavaScript is also updated.

Step 5: Recompile your project

Now run compass watch to recompile your project. If you see any errors please jump down to the upgrading your Sass section.

Upgrading the Sass

In Foundation 5 we removed the following components:

@import "foundation/components/sections"; @import "foundation/components/custom-forms";

Upgrading the JavaScript

We have built a migration plugin, foundation-migrate, that will guide you through moving your old Foundation JavaScript over to the new syntax.

Foundation 5 removes support for Zepto. Here's how you can switch Zepto for jQuery:


<!-- old Foundation 4 embed code --> <script> document.write('<script src=/js/vendor/' + ('__proto__' in {} ? 'zepto' : 'jquery') + '.js><\/script>'); </script>

All you need to do is add jQuery to the end of your body:


<script src="/js/vendor/jquery.js"></script>

After you have included jQuery, you can drop in the Foundation library and initialize Foundation:


<script src="/js/vendor/jquery.js"></script> <script src="/js/foundation/foundation.min.js"></script> <script> $(document).foundation(); </script>

In Foundation 4, you could pass a string of the plugins you want to initialize like $(document).foundation('topbar reveal');. You can no longer do this in Foundation 5. Everything is initialized by default.

Configuration changes

Configuration options are passed a little differently to the Foundation libraries:

The old way

$(document).foundation('dropdown', {is_hover: false});

The new way

$(document).foundation({dropdown: {is_hover: false}});

In Foundation 5 you can reconfigure variables on the fly after the page has loaded and Foundation has been initialized:


$('#myTarget').foundation({dropdown: {is_hover: true}});

Javascript Variable Changes

All Javascript configuration variables are now under_score instead of camelCase:

Library Foundation 4 Foundation 5
dropdown activeClass active_class
topbar stickyClass sticky_class
joyride tipLocation tip_location
nubPosition nub_position
scrollSpeed scroll_speed
startTimeOnClick start_timer_on_click
startOffset start_offset
nextButton next_button
tipAnimation tip_animation
pauseAfter pause_after
tipAnimationFadeSpeed tip_animation_fade_speed
cookieMonster cookie_monster
cookieName cookie_name
cookieDomain cookie_domain
cookieExpires cookie_expires
tipContainer tip_container
postRideCallback post_ride_callback
postStepCallback post_step_callback
preStepCallback pre_step_callback
preRideCallback pre_ride_callback
postExposeCallback post_expose_callback
exposeAddClass expose_add_class
magellan activeClass active_class
reveal animationSpeed animation_speed
closeOnBackgroundClick close_on_background_click
closeOnEsc close_on_esc
dismissModalClass dismiss_modal_class
bgClass bg_class
tooltip additionalInheritableClasses additional_inheritable_classes
tooltipClass tooltip_class
touchCloseText touch_close_text
appendTo append_to
tipTemplate tip_template
Stay on top of what’s happening in responsive design.

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