# Breadcrumbs On Rails
BreadcrumbsOnRails is a simple Ruby on Rails plugin for creating and managing a breadcrumb navigation for a Rails project. It provides helpers for creating navigation elements with a flexible interface.
[](https://github.com/weppos/breadcrumbs_on_rails/actions/workflows/tests.yml)
[](https://tidelift.com/subscription/pkg/rubygems-breadcrumbs.on.rails?utm_source=rubygems-breadcrumbs-on-rails&utm_medium=referral&utm_campaign=enterprise)
## Links
- [Homepage](https://simonecarletti.com/code/breadcrumbs-on-rails)
- [Repository](https://github.com/weppos/breadcrumbs_on_rails)
- [API Documentation](https://rubydoc.info/gems/breadcrumbs_on_rails)
## Requirements
- Ruby >= 2.4
- Rails >= 5
For older versions use a previous release.
## Installation
Add this line to your application's `Gemfile`:
```
gem "breadcrumbs_on_rails"
```
And then execute `bundle` to install the dependencies:
```
bundle
```
Use [Bundler](http://bundler.io/) and the `:git` option if you want to grab the latest version from the Git repository.
## Usage
Creating a breadcrumb navigation menu in your Rails app using BreadcrumbsOnRails is really straightforward.
In your controller, call `add_breadcrumb` to push a new element on the breadcrumb stack. `add_breadcrumb` requires two arguments: the name of the breadcrumb and the target path.
```ruby
class MyController
add_breadcrumb "home", :root_path
add_breadcrumb "my", :my_path
def index
# ...
add_breadcrumb "index", index_path
end
end
```
See the section "Breadcrumb Element" for more details about name and target class types.
The third, optional argument is a Hash of options to customize the breadcrumb link.
```ruby
class MyController
def index
add_breadcrumb "index", index_path, title: "Back to the Index"
end
end
```
In your view, you can render the breadcrumb menu with the `render_breadcrumbs` helper.
```html
untitled
<%= render_breadcrumbs %>
```
`render_breadcrumbs` understands a limited set of options. For example, you can pass change the default separator with the `:separator` option.
```html
<%= render_breadcrumbs :separator => ' / ' %>
```
Current possible options are:
- `:separator`
- `:tag`
To use with Bootstrap you might use the following:
```html
<%= render_breadcrumbs :tag => :li, :separator => "" %>
```
More complex customizations require a custom `Builder`.
### HTML Escaping
The text of the breadcrumb is html-escaped by default unless it is a SafeBuffer, to prevent XSS attacks.
```ruby
class MyController
add_breadcrumb "This is the Main page".html_safe
def profile
add_breadcrumb "#{@user_name} Profile", users_profile
end
end
```
In this case, if `@user_name` is `