Get started using Primer ViewComponents in your Rails application.

Primer ViewComponents is an implementation of the Primer Design System, using ViewComponent.

This library is under active pre-1.0 development. Breaking changes are likely in patch releases.

Getting started

In your Gemfile, add:

gem "primer_view_components"

In config/application.rb, add after the application definition:

require "view_component"
require "primer/view_components"


Load CSS as a JS module into the pipeline. Update app/assets/config/manifest.js with:

//= link primer_view_components.css

Add it in your application.html.erb in the <head> tag:

<%= stylesheet_link_tag("primer_view_components") %>


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.

Migration and upgrade guides

Primer ViewComponents are routinely deprecated as they mature. The following guides detail performing component upgrades.

Migrating from Primer CSS

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.

Upgrading deprecated components

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.

More information

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).