gitlab-org--gitlab-foss/doc/development/fe_guide/view_component.md

stage	group	info
Ecosystem	Foundations	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

ViewComponent

ViewComponent is a framework for creating reusable, testable & encapsulated view components with Ruby on Rails, without the need for a JavaScript framework like Vue. They are rendered server-side and can be seamlessly used with template languages like Haml.

Refer to the official documentation to learn more or watch this introduction video.

Pajamas components

Some of the components of our Pajamas design system are available as a ViewComponent in app/components/pajamas.

NOTE: We have a small but growing number of Pajamas components. Reach out to the Foundations team if the component you are looking for is not yet available.

Available components

Alert

The Pajamas::AlertComponent follows the Pajamas Alert specification.

Examples:

By default this creates a dismissible info alert with icon:

= render Pajamas::AlertComponent.new(title: "Almost done!")

You can set variant, hide the icons and more:

= render Pajamas::AlertComponent.new(title: "All done!",
  variant: :success,
  dismissible: :false,
  show_icon: false)

For the full list of options, see its source.

Banner

The Pajamas::BannerComponent follows the Pajamas Banner specification.

Examples:

In its simplest form the banner component looks like this:

= render Pajamas::BannerComponent.new(button_text: 'Learn more', button_link: example_path,
  svg_path: 'illustrations/example.svg') do |c|
  - c.title { 'Hello world!' }
  %p Content of your banner goes here...

If you have a need for more control, you can also use the illustration slot instead of svg_path and the primary_action slot instead of button_text and button_link:

= render Pajamas::BannerComponent.new do |c|
  - c.illustration do
    = custom_icon('my_inline_svg')
  - c.title do
    Hello world!
  - c.primary_action do
    = render 'my_button_in_a_partial'

For the full list of options, see its source.

Button

The Pajamas::ButtonComponent follows the Pajamas Button specification.

Examples:

The button component has a lot of options but all of them have good defaults, so the simplest button looks like this:

= render Pajamas::ButtonComponent.new do |c|
  = _('Button text goes here')

The following example shows most of the available options:

= render Pajamas::ButtonComponent.new(category: :secondary,
  variant: :danger,
  size: :small,
  type: :submit,
  disabled: true,
  loading: false,
  block: true) do |c|
  Button text goes here

You can also create button-like looking <a> tags, like this:

= render Pajamas::ButtonComponent.new(href: root_path) do |c|
  Go home

For the full list of options, see its source.

Card

The Pajamas::CardComponent follows the Pajamas Card specification.

Examples:

The card has one mandatory body slot and optional header and footer slots:

= render Pajamas::CardComponent.new do |c|
  - c.header do
    I'm the header.
  - c.body do
    %p Multiple line
    %p body content.
  - c.footer do
    Footer goes here.

If you want to add custom attributes to any of these or the card itself, use the following options:

= render Pajamas::CardComponent.new(card_options: {id: "my-id"}, body_options: {data: { count: 1 }})

header_options and footer_options are available, too.

For the full list of options, see its source.

Toggle

The Pajamas::ToggleComponent follows the Pajamas Toggle specification.

= render Pajamas::ToggleComponent.new(classes: 'js-force-push-toggle',
  label: s_("ProtectedBranch|Toggle allowed to force push"),
  is_checked: protected_branch.allow_force_push,
  label_position: :hidden)
  Leverage this block to render a rich help text. To render a plain text help text, prefer the `help` parameter.

NOTE: The toggle ViewComponent is special as it depends on the Vue.js component. To actually initialize this component, make sure to call the initToggle helper from ~/toggles.

For the full list of options, see its source.

Best practices

• If you are about to create a new view in Haml, use the available components over creating plain Haml tags with CSS classes.
• If you are making changes to an existing Haml view and see, for example, a button that is still implemented with plain Haml, consider migrating it to use a ViewComponent.