Skip to content

Instantly share code, notes, and snippets.

@sharvit sharvit/
Last active Apr 26, 2018

What would you like to do?
BreadcrumbBar toturial



Breadcrumbs display a users location within an application hierarchy. They act as a resource to help users navigate more efficiently and provide additional context.

The Breadcrumb Switcher provides a shortcut for users to quickly navigate to parallel pages, rather than navigating back to the previous page and making a new selection.


In version 1.18 we have introduced the new BreadcrumbBar that should eventually replace the two-pane navigation.

Notice: the two-pane is deprecated now and will be removed in version 1.19.

How to use it

The easiest way to apply the BreadcrumbBar on your page is to keep using the LayoutHelper::title as you use it today.

# app/views/posts/show.html.erb

<% title("Post 1") %>

It will make the BreadcrumbBar appear in edit and show pages. It will try to match the best set of configurations for the current page and will apply it on the BreadcrumbBar. see app/services/breadcrumbs_options.rb

Override the default configurations

In some cases, the generic configurations won't fit your page, and you will need to set the configurations manually. To do so, you will need to migrate from using the LayoutHelper::title to use the new LayoutHelper::breadcrumbs.

The LayoutHelper::breadcrumbs function will use the same default configurations while you can pass your own configurations as a hash. It will override only the configurations you actually passed.

# app/views/posts/edit.html.erb

<%= breadcrumbs(
    items: [
        caption: "Posts",
        url: "/posts"
        caption: "Edit Post 1"
    switchable: true,
    name_field: "title",
    resource_url: "/resource-item-url",
    switcher_item_url: "/switcher-item-url-template/:id/edit"

The breadcrumbs_options hash

  • nothing is required
Key Type Description Default Value
items Array(breadcrumb_item) Breadcrumb items to show BreadcrumbsOptions::items
switchable boolean Whether or not to show the BreadcrumbSwitcher BreadcrumbsOptions::switchable?
name_field string If switchable, the name_field will be the display field from the switcher results BreadcrumbsOptions::model_name_field
resource_url string If switchable, it will be used to fetch switcher items when opening the switcher "/api/v2/#{controller_name}"
switcher_item_url string If switchable, it will be used as a template to create urls for each switcher item. :id will be replaced with the actual id of the switcher item. BreadcrumbsOptions::switcher_url_template

The breadcrumb_item hash

Key Type Description
caption string The link text
url string The link URL

How to migrate from two-pane to the new BreadcrumbBar

  1. Disable the two-pane functionality by removing the table-two-pane class from your index.html.erb file.
-<table class="<%= table_css_classes('table-two-pane table-fixed') %>">
+<table class="<%= table_css_classes('table-fixed') %>">
  1. The BreadcumbBar should get mounted to the view when navigating to new/edit/show pages with the default configurations.

  2. If the default configurations are not enough, override the needed fields in each view new/edit/show.

+<%= breadcrumbs name_field: 'description' %>

Migration PR examples

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.