Rails
Get started using Primer ViewComponents in your Rails application.
Primer ViewComponents is an implementation of the Primer Design System, using ViewComponent.
In your Gemfile, add:
gem "primer_view_components"
In config/application.rb, add after the application definition:
require "view_component"require "primer/view_components/engine"
Optionally, to add the JavaScript behaviours, in your application.html.erb in the <head> tag add:
<%= javascript_include_tag("primer_view_components") %>
Or alternatively, you can install the @primer/view-components npm package and in your JavaScript code add:
import '@primer/view-components'
You can also import only the components you need:
import '@primer/view-components/tab_container'
Render Primer ViewComponents in Rails templates:
<%= render(Primer::Beta::Counter.new(count: 25)) %>
In addition to the dependencies declared in the gemspec, Primer ViewComponents assumes the presence of Primer CSS.
Primer ViewComponents are routinely deprecated as they mature. The following guides detail performing component upgrades.
Many Primer CSS use cases are supported by Primer ViewComponents.
When migrating from Primer CSS classes to ViewComponents, use this mapping to help guide your implementation. This list includes components currently in stable status.
| Primer CSS Class | ViewComponent |
|---|---|
State | Primer::Beta::State |
breadcrumb-item | Primer::Beta::Breadcrumbs |
Counter | Primer::Beta::Counter |
Subhead | Primer::Beta::Subhead |
blankslate | Primer::Beta::Blankslate |
As Primer ViewComponents are updated, there are often breaking changes and deprecations that require changes which cannot be auto-corrected with Rubocop or other tools. These guides will walk you through the upgrade process for specific components.
| Deprecated Component | Replacement Component | Guide |
|---|---|---|
Primer::ButtonComponent | Primer::Beta::Button | Upgrade to Primer::Beta::Button |
Primer::LayoutComponent | Primer::Alpha::Layout | Upgrade to Primer::Alpha::Layout |
Primer::LocalTime | Primer::Beta::RelativeTime | Upgrade to Primer::Beta::RelativeTime |
Primer::TimeAgoComponent | Primer::Beta::RelativeTime | Upgrade to Primer::Beta::RelativeTime |
Primer::Truncate | Primer::Beta::Truncate | Upgrade to Primer::Beta::Truncate |
See the primer/view_components repository for more information about how to use and contribute to Primer ViewComponents. For component-specific documentation, check out the Rails section of component guidelines (example: ActionList).