Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Blocks"
description: "Learn how to utilize blocks to build your Spree Storefront"
canonical: "https://spreecommerce.org/docs/v5/developer/storefront/rails/blocks"
---
Blocks are the lowest level of components in Spree Storefront. They are nested inside [sections](/v5/developer/storefront/rails/sections) and represent individual content elements like headings, text, buttons, and images.
## How Blocks Work
Each section can contain multiple blocks that store staff can manage through the Page Builder:
- Add new blocks
- Edit block content and settings
- Reorder blocks via drag-and-drop
- Remove blocks
Not all sections support blocks. A section must explicitly enable block support by implementing `blocks_available?` and `available_blocks_to_add` methods.
## Built-in Block Types
Spree comes with several built-in block types:
### Content Blocks
| Block | Description | Class |
|-------|-------------|-------|
| Heading | Large text headings | [Spree::PageBlocks::Heading](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/heading.rb) |
| Subheading | Smaller secondary headings | [Spree::PageBlocks::Subheading](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/subheading.rb) |
| Text | Rich text content | [Spree::PageBlocks::Text](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/text.rb) |
| Buttons | Call-to-action buttons with links | [Spree::PageBlocks::Buttons](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/buttons.rb) |
| Image | Image with optional link | [Spree::PageBlocks::Image](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/image.rb) |
### Navigation Blocks
| Block | Description | Class |
|-------|-------------|-------|
| Nav | Simple navigation links | [Spree::PageBlocks::Nav](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/nav.rb) |
| Mega Nav | Mega menu navigation | [Spree::PageBlocks::MegaNav](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/mega_nav.rb) |
| Link | Single link item | [Spree::PageBlocks::Link](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/link.rb) |
### Product Blocks
These blocks are used in the Product Details section:
| Block | Description | Class |
|-------|-------------|-------|
| Title | Product title | [Spree::PageBlocks::Products::Title](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/title.rb) |
| Price | Product price display | [Spree::PageBlocks::Products::Price](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/price.rb) |
| Description | Product description | [Spree::PageBlocks::Products::Description](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/description.rb) |
| Variant Picker | Size/color selector | [Spree::PageBlocks::Products::VariantPicker](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/variant_picker.rb) |
| Quantity Selector | Quantity input | [Spree::PageBlocks::Products::QuantitySelector](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/quantity_selector.rb) |
| Buy Buttons | Add to cart button | [Spree::PageBlocks::Products::BuyButtons](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/buy_buttons.rb) |
| Share | Social sharing buttons | [Spree::PageBlocks::Products::Share](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/share.rb) |
## Architecture
### Base Class
All blocks inherit from [Spree::PageBlock](https://github.com/spree/spree/blob/main/core/app/models/spree/page_block.rb):
```ruby
module Spree
class PageBlock < Spree.base_class
include Spree::HasPageLinks
belongs_to :section, class_name: 'Spree::PageSection'
has_rich_text :text
has_one_attached :asset
# Default preferences
preference :text_alignment, :string, default: 'left'
preference :container_alignment, :string, default: 'left'
preference :size, :string, default: 'medium'
preference :width_desktop, :integer, default: 100
preference :top_padding, :integer, default: 0
preference :bottom_padding, :integer, default: 0
end
end
```
### Default Preferences
Every block has these default preferences:
| Preference | Type | Default | Description |
|------------|------|---------|-------------|
| `text_alignment` | String | `left` | Text alignment (left, center, right) |
| `container_alignment` | String | `left` | Container alignment |
| `size` | String | `medium` | Block size (small, medium, large) |
| `width_desktop` | Integer | `100` | Width percentage on desktop |
| `top_padding` | Integer | `0` | Top padding in pixels |
| `bottom_padding` | Integer | `0` | Bottom padding in pixels |
### Associations
- **Section**: Each block belongs to a section (`section`)
- **Links**: Blocks can have multiple links (`links`) via `Spree::HasPageLinks`
- **Asset**: Blocks can have an attached image (`asset`)
- **Rich Text**: Blocks can have rich text content (`text`)
## Accessing Blocks
```ruby
# Get all blocks for a section
section.blocks
# Get blocks with eager loading
section.blocks.includes(:rich_text_text, :links)
# Find specific block type
section.blocks.where(type: 'Spree::PageBlocks::Heading')
```
## Rendering Blocks
In storefront section views, blocks are rendered within their parent section:
```erb
<% section.blocks.each do |block| %>
<% case block.type %>
<% when 'Spree::PageBlocks::Heading' %>
<h2 <%= block_attributes(block) %>>
<%= block.text %>
</h2>
<% when 'Spree::PageBlocks::Text' %>
<div <%= block_attributes(block) %>>
<%= block.text %>
</div>
<% when 'Spree::PageBlocks::Buttons' %>
<div <%= block_attributes(block) %>>
<% if block.link %>
<%= page_builder_link_to block.link, class: 'btn-primary' %>
<% end %>
</div>
<% end %>
<% end %>
```
The `block_attributes(block)` helper returns data attributes needed for Page Builder editing.
## Creating a Custom Block
### Step 1: Create the Model
```ruby app/models/spree/page_blocks/quote.rb
module Spree
module PageBlocks
class Quote < Spree::PageBlock
SIZE_DEFAULT = 'large'
TEXT_ALIGNMENT_DEFAULT = 'center'
preference :author_name, :string
preference :author_title, :string
preference :text_color, :string
preference :background_color, :string
def icon_name
'quote'
end
def display_name
text.to_plain_text.truncate(30)
end
end
end
end
```
### Step 2: Register the Block
```ruby config/initializers/spree.rb
Rails.application.config.after_initialize do
Spree.page_builder.page_blocks += [
Spree::PageBlocks::Quote
]
end
```
### Step 3: Add to Section's Available Blocks
In your section model, add the new block type:
```ruby
def available_blocks_to_add
[
Spree::PageBlocks::Heading,
Spree::PageBlocks::Text,
Spree::PageBlocks::Quote # Your new block
]
end
```
### Step 4: Create Admin Form
```erb app/views/spree/admin/page_blocks/forms/_quote.html.erb
<div class="form-group">
<%= f.label :text, Spree.t(:quote_text) %>
<%= f.rich_text_area :text, data: { action: 'auto-submit#submit' } %>
</div>
<div class="form-group">
<%= f.label :preferred_author_name, Spree.t(:author_name) %>
<%= f.text_field :preferred_author_name,
class: 'form-control',
data: { action: 'auto-submit#submit' } %>
</div>
<div class="form-group">
<%= f.label :preferred_author_title, Spree.t(:author_title) %>
<%= f.text_field :preferred_author_title,
class: 'form-control',
data: { action: 'auto-submit#submit' } %>
</div>
```
### Step 5: Render in Section View
Add rendering logic to your section's storefront view:
```erb
<% when 'Spree::PageBlocks::Quote' %>
<blockquote <%= block_attributes(block) %> class="text-<%= block.preferred_text_alignment %>">
<p class="text-xl italic"><%= block.text %></p>
<% if block.preferred_author_name.present? %>
<footer class="mt-4">
<cite>
<strong><%= block.preferred_author_name %></strong>
<% if block.preferred_author_title.present? %>
<br><span class="text-sm text-gray-500"><%= block.preferred_author_title %></span>
<% end %>
</cite>
</footer>
<% end %>
</blockquote>
```
## Block with Links
To add link support to your block, include the `Spree::HasOneLink` concern:
```ruby
module Spree
module PageBlocks
class CallToAction < Spree::PageBlock
include Spree::HasOneLink
preference :button_style, :string, default: 'primary'
# Called when the link is destroyed
def link_destroyed(_link)
destroy if page_links_count.zero?
end
end
end
end
```
## Block with Image
Blocks automatically have an `asset` attachment available:
```ruby
# Check if image is attached
block.asset.attached?
# Display image in view
<% if block.asset.attached? %>
<%= spree_image_tag block.asset, width: 400, height: 300 %>
<% end %>
```
## Key Methods
| Method | Description |
|--------|-------------|
| `display_name` | Name shown in Page Builder sidebar |
| `icon_name` | Icon from [Tabler Icons](https://tabler.io/icons) |
| `form_partial_name` | Name of the admin form partial |
## Related Documentation
- [Sections](/v5/developer/storefront/rails/sections) - Parent containers for blocks
- [Links](/v5/developer/storefront/rails/links) - Adding links to blocks
- [Media](/v5/developer/core-concepts/media) - Working with images