docs/oss/api-reference/view-helpers-api.md
Once the bundled files have been generated in your app/assets/webpack folder, and you have registered your components, you will want to render these components on your Rails views using the included helper method, react_component.
react_component(component_name,
props: {},
prerender: nil)
html_options: {})
Uncommonly used options:
trace: nil,
replay_console: nil,
raise_on_prerender_error: nil,
id: nil,
{ renderedHtml, clientProps?, redirectLocation?, routeError? }), or a "renderer function" that manually renders a React component to the DOM (client-side only). Note, a "renderer function" is a special type of "Render-Function." A "renderer function" takes a 3rd param of a DOM ID.
All options except props, id, html_options will inherit from your react_on_rails.rb initializer, as described here.REACT_ON_RAILS_PRERENDER_OVERRIDE=true|false to force prerendering on or off globally.
Precedence is: REACT_ON_RAILS_PRERENDER_OVERRIDE > component option (prerender:) > initializer default (config.prerender).append_javascript_pack_tag and append_stylesheet_pack_tag under the hood.display:inline-block. You may also use an option of tag: "span" to replace the use of the default DIV tag to be a SPAN tag.railsContext and your props.logging_on_server set to true, you'll still see the errors on the server.clientProps merge behavior: If a prerender result includes clientProps, React on Rails merges them into the generated client hydration props payload (props.merge(clientProps)). The original props: value must be a Ruby Hash or a JSON string representing an object.React 19 Alternative: For metadata use cases (page titles, meta tags, canonical URLs), consider using React 19 Native Metadata with
react_componentorstream_react_componentinstead. React 19 natively hoists<title>,<meta>, and<link>tags to<head>, eliminating the need for a render-function andreact_component_hash. See the migration guide for step-by-step instructions.
react_component_hash is used to return multiple HTML strings for server rendering, such as for
adding meta-tags to a page. It is exactly like react_component except for the following:
prerender: true is automatically added to options, as this method doesn't make sense for
client only rendering.Here is an example of ERB view code:
<% react_helmet_app = react_component_hash("ReactHelmetApp", prerender: true,
props: { helloWorldData: { name: "Mr. Server Side Rendering"}},
id: "react-helmet-0", trace: true) %>
<% content_for :title do %>
<%= react_helmet_app['title'] %>
<% end %>
<%= react_helmet_app["componentHtml"] %>
And here is the JavaScript code:
export default (props, _railsContext) => {
const componentHtml = renderToString(<ReactHelmet {...props} />);
const helmet = Helmet.renderStatic();
const renderedHtml = {
componentHtml,
title: helmet.title.toString(),
};
return { renderedHtml };
};
You can call rails_context or rails_context(server_side: true|false) from your controller or view to see what values are in the Rails Context. Pass true or false depending on whether you want to see the server-side or the client-side rails_context. Typically, for computing cache keys, you should leave server_side as the default true. When calling this from a controller method, use helpers.rails_context.
A "renderer function" is a Render-Function that accepts three arguments (rather than 2): (props, railsContext, domNodeId) => { ... }. Instead of returning a React component, a renderer is responsible for installing a callback that will call ReactDOM.render (in React 16+, ReactDOM.hydrate) to render a React component into the DOM. The "renderer function" is called at the same time the document ready event would instantiate the React components into the DOM.
Why would you want to call ReactDOM.hydrate yourself? One possible use case is code splitting. In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call ReactDOM.hydrate at a later time. In the case of code splitting with server rendering, the server-rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any async code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen.
For modern code splitting with server-side rendering, see the React on Rails Pro loadable-components guide.
Renderer functions are not meant to be used on the server since there's no DOM on the server. Instead, use a Render-Function. Attempting to server render with a renderer function will throw an error.
React Router is supported via manual integration, including server-side rendering. See:
TanStack Router has a first-class SSR helper through react-on-rails-pro/tanstack-router (requires React on Rails Pro). See TanStack Router guide.
server_render_js(js_expression, options = {})
replay_console (boolean)This is a helper method that takes any JavaScript expression and returns the output from evaluating it. If you have more than one line that needs to be executed, wrap it in an IIFE. JS exceptions will be caught and console messages handled properly.
The following view helpers are available exclusively with React on Rails Pro. These require a valid React on Rails Pro license and will not be available if the Pro gem is not installed or properly licensed.
Fragment caching helpers that cache React component rendering to improve performance. The API is the same as react_component and react_component_hash, but with these differences:
cache_key takes the same parameters as any Rails cache view helper.Example usage:
<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
some_slow_method_that_returns_props
end %>
Progressive server-side rendering using React 18+ streaming with renderToPipeableStream. This enables:
See the Streaming Server Rendering guide for usage details.
Renders React Server Component (RSC) payloads in NDJSON format for client-side consumption. Used in conjunction with RSC support to enable:
See the React on Rails Pro Configuration for RSC setup.
See the lib/react_on_rails/helper.rb source.