RailsHow-ToBeginner · 4 min read

How to Use Layouts in Rails: Syntax, Example, and Tips

In Rails, use layouts to wrap views with a common structure by placing layout files in app/views/layouts. Specify a layout in a controller with layout 'layout_name' or use the default application.html.erb layout automatically.

📐

Syntax

Layouts in Rails are HTML templates that wrap around your views to provide a consistent look. They live in app/views/layouts. You can specify which layout a controller uses with layout 'layout_name'. If you don't specify, Rails uses application.html.erb by default.

Inside a layout, <%= yield %> marks where the view content will appear.

ruby+erb

class PostsController < ApplicationController
  layout 'blog'

  def index
    # renders views/posts/index.html.erb inside layouts/blog.html.erb
  end
end

# layouts/blog.html.erb
<!DOCTYPE html>
<html>
<head>
  <title>Blog Layout</title>
</head>
<body>
  <header>My Blog Header</header>
  <%= yield %>
  <footer>My Blog Footer</footer>
</body>
</html>

💻

Example

This example shows a controller using a custom layout named blog. The layout wraps the view content with a header and footer. The <%= yield %> tag in the layout inserts the view's HTML.

ruby+erb

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  layout 'blog'

  def index
    @posts = ['Post 1', 'Post 2']
  end
end

# app/views/layouts/blog.html.erb
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Blog Layout</title>
</head>
<body>
  <header><h1>Welcome to My Blog</h1></header>
  <main>
    <%= yield %>
  </main>
  <footer><p>© 2024 My Blog</p></footer>
</body>
</html>

# app/views/posts/index.html.erb
<ul>
  <% @posts.each do |post| %>
    <li><%= post %></li>
  <% end %>
</ul>

Output

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Blog Layout</title> </head> <body> <header><h1>Welcome to My Blog</h1></header> <main> <ul> <li>Post 1</li> <li>Post 2</li> </ul> </main> <footer><p>© 2024 My Blog</p></footer> </body> </html>

⚠️

Common Pitfalls

Forgetting to include <%= yield %> in your layout will cause views not to render inside the layout.
Specifying a layout name that does not exist in app/views/layouts will cause an error.
Using render layout: false in views disables layouts, which might be unintended.
Not restarting the Rails server after adding new layouts can cause changes not to appear.

erb

# Wrong: Missing yield in layout
# layouts/missing_yield.html.erb
<html><body>
  <h1>Header</h1>
  <!-- Missing <%= yield %> here -->
  <footer>Footer</footer>
</body></html>

# Right: Include yield
<html><body>
  <h1>Header</h1>
  <%= yield %>
  <footer>Footer</footer>
</body></html>

📊

Quick Reference

Layout usage tips:

Default layout file: app/views/layouts/application.html.erb
Set layout per controller: layout 'name'
Use yield to insert view content
Disable layout in controller action: render layout: false
Layouts can include shared HTML like headers, footers, and navigation

✅

Key Takeaways

Layouts wrap views to provide a consistent page structure in Rails.

Use layout 'name' in controllers to specify a layout file.

Always include <%= yield %> in layouts to render view content.

The default layout is application.html.erb in app/views/layouts.

Restart the server after adding or changing layout files to see updates.