Easy, customizable Rails navigation tabs. Active tab highlighting with a descendant CSS selector.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Nav Tab helpers and controller filters for easily and quickly generating tabs using a decendent CSS selector to highlight the current active tab. More information on the ideas behind this can be found in a discussion here .

To use, define an array of hashed tab definitions in ApplicationController with descendant_nav_tabs using the :tabs option. The order the tabs are defined in the array defines the order they will be displayed. Each tab can be defined using three options:


  • :id – A string id for the tab. Must be unique. Ideally, this would be the controller name for the resource the tab is associated with since, by default, the active tab has an id the same as the current controller name.


  • :path – The path to the resource. If omitted, the path will be derived from the :id by adding a leading ‘/’.
  • :text – The text label displayed on the tab. If ommitted, the :id is capitalized and used instead.

Note that the order of the array is the tab order.

descendant_nav_tabs takes two additional parameters:

  • :active_tab_background – Set the background color of the active tab to a hex color value.
  • :reset_to_horizontal – Set to true in order to reset the list style to display horizonal tabs. If not set to true, tabs will be generated a naked unordered list.


    # in application.rb
    descendant_nav_tabs :nav_tabs => [{:id => 'home', :path => '/'}, {:id => 'about'}, {:id => 'people', :text => 'Contributors'}],
                    :active_tab_background => "0015FF",
                    :reset_to_horizontal => true

Alternatively, you can use descendant_nav_tabs as a normal before_filter and set the attributes on the controller itself. This is useful for using routes or instance methods in your nav tab definition.

In your layouts, include the stylesheet using the stylesheet_include_css_nav_tabs helper and set the body css id to current_tab. Both of these are required in order to highlight the active tab. A Haml example:

    # application.html.haml
        = stylesheet_include_css_nav_tabs
      %body{:id => current_tab}

To put the tabs (as an unordered list) in your views, use the nav_bar helper:

    # _header.html.haml
    = nav_bar

The css class of the unordered list generated by nav_bar is, by default, “nav-bar”, but this can be modified by passing a :class => parameter to the nav bar.

By default, the current highlighted tab is derived from the current controller name. This behavior can be customised by defining a current_tab method in the controller that requires the custom behavior. This will act as the last before filter, so it can depend on variables set in earlier filters.

    # CommentsController
      def current_tab
        case @comment.commentable
        when Post then 'posts'
        when Photo then 'photos'

Other recommendations

Note that the current_tab features of this plugin can be used without using the helpers to generate the nav_tabs and css as long as the css ids are defined properly and the body id is set to the current_tab helpers. The example above re-written with explicitly defined tabs (in Haml):

    # site_stylesheet.css
    #home #homeNav, #about #aboutNav, #people #peopleNav {
      background-color: #0015FF; }
    # application.html.haml
        = stylesheet_link_tag('site_stylesheet')
      %body{:id => current_tab}
    # _header.html.haml
        %a#homeNav{ :href => "/" }
        %a#aboutNav{ :href => "/about" }
        %a#peopleNav{ :href => "/people" }

With tabs defined explicitly in the view and the body id set to the current_tab helper, the active tab will still reflect the current controller or whatever is defined in that controller’s custom current_tab method. The only view element that needs to be dynamic for this to work is the body id. In addition to the benefit of using straight HTML and CSS rather than helpers, this also keeps as much view code out of the controllers as possible, aside from any custom current_tab definitions.

Copyright © 2008 William Melody, released under the MIT license