API

Class methods

.config → [ActiveSupport::OrderedOptions]

Returns the current config.

.sidecar_files(extensions)

Find sidecar files for the given extensions.

The provided array of extensions is expected to contain strings starting without the dot, example: ["erb", "haml"].

For example, one might collect sidecar CSS files that need to be compiled.

.strip_trailing_whitespace(value = true)

Strips trailing whitespace from templates before compiling them.

class MyComponent < ViewComponent::Base
  strip_trailing_whitespace
end

.strip_trailing_whitespace? → [Boolean]

Whether trailing whitespace will be stripped before compilation.

.with_collection(collection, **args)

Render a component for each element in a collection (documentation):

render(ProductsComponent.with_collection(@products, foo: :bar))

.with_collection_parameter(parameter)

Set the parameter name used when rendering elements of a collection (documentation):

with_collection_parameter :item

Instance methods

#before_render → [void]

Called before rendering the component. Override to perform operations that depend on having access to the view context, such as helpers.

#content → [String]

The content passed to the component instance as a block.

#content? → [Boolean]

Whether content has been passed to the component.

#controller → [ActionController::Base]

The current controller. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.

#helpers → [ActionView::Base]

A proxy through which to access helpers. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.

#output_preamble → [String]

Optional content to be returned before the rendered template.

#output_postamble → [String]

Optional content to be returned after the rendered template.

#render? → [Boolean]

Override to determine whether the ViewComponent should render.

#render_in(view_context, &block) → [String]

Entrypoint for rendering components.

  • view_context: ActionView context from calling view
  • block: optional block to be captured within the view context

Returns HTML that has been escaped by the respective template handler.

#render_parent

Subclass components that call super inside their template code will cause a double render if they emit the result.

<%= super %> # double-renders
<% super %> # doesn't double-render

super also doesn’t consider the current variant. render_parent renders the parent template considering the current variant and emits the result without double-rendering.

#render_parent_to_string

Renders the parent component to a string and returns it. This method is meant to be used inside custom #call methods when a string result is desired, eg.

def call
  "<div>#{render_parent_to_string}</div>"
end

When rendering the parent inside an .erb template, use #render_parent instead.

#request → [ActionDispatch::Request]

The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.

#set_original_view_context(view_context) → [void]

Components render in their own view context. Helpers and other functionality require a reference to the original Rails view context, an instance of ActionView::Base. Use this method to set a reference to the original view context. Objects that implement this method will render in the component’s view context, while objects that don’t will render in the original view context so helpers, etc work as expected.

Configuration

.capture_compatibility_patch_enabled

Enables the experimental capture compatibility patch that makes ViewComponent compatible with forms, capture, and other built-ins. previews. Defaults to false.

.component_parent_class

The parent class from which generated components will inherit. Defaults to nil. If this is falsy, generators will use "ApplicationComponent" if defined, "ViewComponent::Base" otherwise.

#config

Returns the value of attribute config.

#current

Returns the current ViewComponent::Config. This is persisted against this class so that config options remain accessible before the rest of ViewComponent has loaded. Defaults to an instance of ViewComponent::Config with all other documented defaults set.

.default_preview_layout

A custom default layout used for the previews index page and individual previews. Defaults to nil. If this is falsy, "component_preview" is used.

.generate

The subset of configuration options relating to generators.

All options under this namespace default to false unless otherwise stated.

#sidecar

Always generate a component with a sidecar directory:

config.view_component.generate.sidecar = true

#stimulus_controller

Always generate a Stimulus controller alongside the component:

config.view_component.generate.stimulus_controller = true

#locale

Always generate translations file alongside the component:

config.view_component.generate.locale = true

#distinct_locale_files

Always generate as many translations files as available locales:

config.view_component.generate.distinct_locale_files = true

One file will be generated for each configured I18n.available_locales, falling back to [:en] when no available_locales is defined.

#preview

Always generate a preview alongside the component:

 config.view_component.generate.preview = true

#preview_path

Path to generate preview:

 config.view_component.generate.preview_path = "test/components/previews"

Required when there is more than one path defined in preview_paths. Defaults to "". If this is blank, the generator will use ViewComponent.config.preview_paths if defined, "test/components/previews" otherwise

.instrumentation_enabled

Whether ActiveSupport notifications are enabled. Defaults to false.

.preview_controller

The controller used for previewing components. Defaults to ViewComponentsController.

.preview_paths

The locations in which component previews will be looked up. Defaults to ['test/components/previews'] relative to your Rails root.

.preview_route

The entry route for component previews. Defaults to "/rails/view_components".

.render_monkey_patch_enabled

If this is disabled, use #render_component or #render_component_to_string instead. Defaults to true.

.show_previews

Whether component previews are enabled. Defaults to true in development and test environments.

.show_previews_source

Whether to display source code previews in component previews. Defaults to false.

.test_controller

The controller used for testing components. Can also be configured on a per-test basis using #with_controller_class. Defaults to ApplicationController.

.use_deprecated_instrumentation_name

Whether ActiveSupport Notifications use the private name "!render.view_component" or are made more publicly available via "render.view_component". Will default to false in next major version. Defaults to true.

.view_component_path

The path in which components, their templates, and their sidecars should be stored. Defaults to "app/components".

ViewComponent::TestHelpers

#render_in_view_context(*args, &block)

Execute the given block in the view context (using instance_exec). Internally sets page to be a Capybara::Node::Simple, allowing for Capybara assertions to be used. All arguments are forwarded to the block.

render_in_view_context(arg1, arg2: nil) do |arg1, arg2:|
  render(MyComponent.new(arg1, arg2))
end

assert_text("Hello, World!")

#render_inline(component, **args, &block) → [Nokogiri::HTML]

Render a component inline. Internally sets page to be a Capybara::Node::Simple, allowing for Capybara assertions to be used:

render_inline(MyComponent.new)
assert_text("Hello, World!")

#render_preview(name, from: __vc_test_helpers_preview_class, params: {}) → [Nokogiri::HTML]

Render a preview inline. Internally sets page to be a Capybara::Node::Simple, allowing for Capybara assertions to be used:

render_preview(:default)
assert_text("Hello, World!")

Note: #rendered_preview expects a preview to be defined with the same class name as the calling test, but with Test replaced with Preview:

MyComponentTest -> MyComponentPreview etc.

In RSpec, Preview is appended to described_class.

#rendered_content → [ActionView::OutputBuffer]

Returns the result of a render_inline call.

#vc_test_controller → [ActionController::Base]

Access the controller used by render_inline:

test "logged out user sees login link" do
  vc_test_controller.expects(:logged_in?).at_least_once.returns(false)
  render_inline(LoginComponent.new)
  assert_selector("[aria-label='You must be signed in']")
end

#vc_test_request → [ActionDispatch::TestRequest]

Access the request used by render_inline:

test "component does not render in Firefox" do
  vc_test_request.env["HTTP_USER_AGENT"] = "Mozilla/5.0"
  render_inline(NoFirefoxComponent.new)
  refute_component_rendered
end

#with_controller_class(klass)

Set the controller to be used while executing the given block, allowing access to controller-specific methods:

with_controller_class(UsersController) do
  render_inline(MyComponent.new)
end

#with_request_url(full_path, host: nil, method: nil)

Set the URL of the current request (such as when using request-dependent path helpers):

with_request_url("/users/42") do
  render_inline(MyComponent.new)
end

To use a specific host, pass the host param:

with_request_url("/users/42", host: "app.example.com") do
  render_inline(MyComponent.new)
end

To specify a request method, pass the method param:

with_request_url("/users/42", method: "POST") do
  render_inline(MyComponent.new)
end

#with_variant(variant)

Set the Action Pack request variant for the given block:

with_variant(:phone) do
  render_inline(MyComponent.new)
end

Errors

AlreadyDefinedPolymorphicSlotSetterError

A method called ‘SETTER_METHOD_NAME’ already exists and would be overwritten by the ‘SETTER_NAME’ polymorphic slot setter.

Please choose a different setter name.

ContentAlreadySetForPolymorphicSlotError

Content for slot SLOT_NAME has already been provided.

ContentSlotNameError

COMPONENT declares a slot named content, which is a reserved word in ViewComponent.

Content passed to a ViewComponent as a block is captured and assigned to the content accessor without having to create an explicit slot.

To fix this issue, either use the content accessor directly or choose a different slot name.

ControllerCalledBeforeRenderError

#controller can’t be used during initialization, as it depends on the view context that only exists once a ViewComponent is passed to the Rails render pipeline.

It’s sometimes possible to fix this issue by moving code dependent on #controller to a #before_render method.

DuplicateContentError

It looks like a block was provided after calling with_content on COMPONENT, which means that ViewComponent doesn’t know which content to use.

To fix this issue, use either with_content or a block.

DuplicateSlotContentError

It looks like a block was provided after calling with_content on COMPONENT, which means that ViewComponent doesn’t know which content to use.

To fix this issue, use either with_content or a block.

EmptyOrInvalidInitializerError

The COMPONENT initializer is empty or invalid. It must accept the parameter PARAMETER to render it as a collection.

To fix this issue, update the initializer to accept PARAMETER.

See the collections docs for more information on rendering collections.

HelpersCalledBeforeRenderError

#helpers can’t be used during initialization as it depends on the view context that only exists once a ViewComponent is passed to the Rails render pipeline.

It’s sometimes possible to fix this issue by moving code dependent on #helpers to a #before_render method.

InvalidCollectionArgumentError

The value of the first argument passed to with_collection isn’t a valid collection. Make sure it responds to to_ary.

InvalidSlotDefinitionError

Invalid slot definition. Please pass a class, string, or callable (that is proc, lambda, etc)

MissingCollectionArgumentError

The initializer for COMPONENT doesn’t accept the parameter PARAMETER, which is required to render it as a collection.

To fix this issue, update the initializer to accept PARAMETER.

See the collections docs for more information on rendering collections.

MissingPreviewTemplateError

A preview template for example EXAMPLE doesn’t exist.

To fix this issue, create a template for the example.

MultipleInlineTemplatesError

Inline templates can only be defined once per-component.

MultipleMatchingTemplatesForPreviewError

Found multiple templates for TEMPLATE_IDENTIFIER.

NilWithContentError

No content provided to #with_content for ViewComponent::NilWithContentError.

To fix this issue, pass a value.

NoMatchingTemplatesForPreviewError

Found 0 matches for templates for TEMPLATE_IDENTIFIER.

RedefinedSlotError

COMPONENT declares the SLOT_NAME slot multiple times.

To fix this issue, choose a different slot name.

ReservedParameterError

COMPONENT initializer can’t accept the parameter PARAMETER, as it will override a public ViewComponent method. To fix this issue, rename the parameter.

ReservedPluralSlotNameError

COMPONENT declares a slot named SLOT_NAME, which is a reserved word in the ViewComponent framework.

To fix this issue, choose a different name.

ReservedSingularSlotNameError

COMPONENT declares a slot named SLOT_NAME, which is a reserved word in the ViewComponent framework.

To fix this issue, choose a different name.

SlotPredicateNameError

COMPONENT declares a slot named SLOT_NAME, which ends with a question mark.

This isn’t allowed because the ViewComponent framework already provides predicate methods ending in ?.

To fix this issue, choose a different name.

SystemTestControllerNefariousPathError

ViewComponent SystemTest controller attempted to load a file outside of the expected directory.

SystemTestControllerOnlyAllowedInTestError

ViewComponent SystemTest controller must only be called in a test environment for security reasons.

TranslateCalledBeforeRenderError

#translate can’t be used during initialization as it depends on the view context that only exists once a ViewComponent is passed to the Rails render pipeline.

It’s sometimes possible to fix this issue by moving code dependent on #translate to a #before_render method.

UncountableSlotNameError

COMPONENT declares a slot named SLOT_NAME, which is an uncountable word

To fix this issue, choose a different name.