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: "Links"
sidebarTitle: "Links"
description: "Learn how to use links for navigation in your Spree Storefront"
canonical: "https://spreecommerce.org/docs/v5/developer/storefront/rails/links"
---
Links are used to create navigation throughout the storefront. They can be assigned to [sections](/v5/developer/storefront/rails/sections) and [blocks](/v5/developer/storefront/rails/blocks), enabling users to navigate to different pages, products, categories, or external URLs.
## How Links Work
The `Spree::PageLink` model provides a flexible way to link to various content types:
- **Internal pages** - Link to Pages, Products, Taxons, Posts
- **External URLs** - Link to any external website
- **Special links** - Email (`mailto:`) and phone (`tel:`) links
Links are managed through the Page Builder interface, where store staff can select what each link points to.
## Link Model
The [Spree::PageLink](https://github.com/spree/spree/blob/main/core/app/models/spree/page_link.rb) model has these key attributes:
| Attribute | Type | Description |
|-----------|------|-------------|
| `label` | String | Display text for the link |
| `url` | String | Custom URL (for external links) |
| `linkable` | Polymorphic | Reference to internal content (Page, Product, etc.) |
| `parent` | Polymorphic | Section or Block the link belongs to |
| `open_in_new_tab` | Boolean | Whether to open in new browser tab |
| `position` | Integer | Order when multiple links exist |
## Linkable Types
Links can point to various Spree models:
| Linkable Type | Description |
|---------------|-------------|
| `Spree::Page` | Internal pages (Home, Shop All, Custom pages) |
| `Spree::Product` | Product detail pages |
| `Spree::Taxon` | Category/collection pages |
| `Spree::Post` | Blog posts |
| Custom URL | Any external or internal URL |
## Using Links in Sections
### Single Link
For sections that need one link (like a banner):
```ruby app/models/spree/page_sections/promo_banner.rb
module Spree
module PageSections
class PromoBanner < Spree::PageSection
has_one :link, ->(ps) { ps.links },
class_name: 'Spree::PageLink',
as: :parent,
dependent: :destroy,
inverse_of: :parent
accepts_nested_attributes_for :link
def default_links
@default_links.presence || [
Spree::PageLink.new(label: Spree.t(:shop_now))
]
end
end
end
end
```
### Multiple Links
For sections that need multiple links (like navigation):
```ruby app/models/spree/page_sections/footer.rb
module Spree
module PageSections
class Footer < Spree::PageSection
# Links are provided by Spree::HasPageLinks concern
# which is included in Spree::PageSection by default
def default_links
@default_links.presence || [
Spree::PageLink.new(label: 'About Us'),
Spree::PageLink.new(label: 'Contact'),
Spree::PageLink.new(label: 'Privacy Policy')
]
end
end
end
end
```
## Using Links in Blocks
Blocks can also have links. Use the `Spree::HasOneLink` concern for single links:
```ruby app/models/spree/page_blocks/cta_button.rb
module Spree
module PageBlocks
class CtaButton < Spree::PageBlock
include Spree::HasOneLink
preference :button_style, :string, default: 'primary'
# Called when the link is deleted
def link_destroyed(_link)
destroy if page_links_count.zero?
end
end
end
end
```
## Accessing Links
```ruby
# Single link on a section
section.link
section.link.label
section.link.linkable_url
# Multiple links on a section
section.links
section.links.each do |link|
link.label
link.linkable_url
end
# Link on a block
block.link
block.link.label if block.link.present?
```
## Rendering Links
### Using the Helper
The `page_builder_link_to` helper renders links with Page Builder support:
```erb
<%# Basic usage %>
<%= page_builder_link_to section.link %>
<%# With custom label %>
<%= page_builder_link_to section.link, label: 'Click Here' %>
<%# With CSS class %>
<%= page_builder_link_to section.link, class: 'btn-primary' %>
<%# Open in new tab %>
<%= page_builder_link_to section.link,
target: (section.link.open_in_new_tab ? '_blank' : nil),
rel: (section.link.open_in_new_tab ? 'noopener noreferrer' : nil) %>
<%# With block content %>
<%= page_builder_link_to section.link do %>
<span class="icon">→</span>
<%= section.link.label %>
<% end %>
```
### Manual Link Rendering
For more control, you can render links manually:
```erb
<% if section.link.present? %>
<%= link_to section.link.linkable_url,
target: (section.link.open_in_new_tab ? '_blank' : nil),
rel: (section.link.open_in_new_tab ? 'noopener noreferrer' : nil),
class: 'btn-primary' do %>
<%= section.link.label %>
<% end %>
<% end %>
```
### Rendering Multiple Links
```erb
<nav class="footer-links">
<% section.links.each do |link| %>
<%= page_builder_link_to link, class: 'footer-link' %>
<% end %>
</nav>
```
## Admin Form for Links
In your section's admin form, render the link editor:
### Single Link
```erb app/views/spree/admin/page_sections/forms/_promo_banner.html.erb
<%= render 'spree/admin/shared/page_section_image', f: f %>
<div class="py-2">
<%= f.fields_for :link do |lf| %>
<div class="form-group">
<%= lf.label :linkable_type, Spree.t(:link) %>
<%= lf.select :linkable_type,
@page_section.allowed_linkable_types,
{ include_blank: false },
{ class: 'custom-select mb-3', data: { action: 'auto-submit#submit' } } %>
<div id="linkable_type_dropdown">
<%= render 'spree/admin/page_links/linkable_type_dropdown',
page_link: lf.object,
form_name: 'page_section[link_attributes]' %>
</div>
</div>
<div class="custom-control custom-checkbox">
<%= lf.check_box :open_in_new_tab,
class: 'custom-control-input',
data: { action: 'auto-submit#submit' } %>
<%= lf.label :open_in_new_tab, class: 'custom-control-label' %>
</div>
<% end %>
</div>
```
## Link URL Resolution
The `linkable_url` method returns the appropriate URL:
```ruby
link = Spree::PageLink.new(linkable: product)
link.linkable_url
# => "/products/red-shirt"
link = Spree::PageLink.new(url: "https://example.com")
link.linkable_url
# => "https://example.com"
link = Spree::PageLink.new(url: "example.com")
link.formatted_url
# => "http://example.com" # Adds protocol automatically
link = Spree::PageLink.new(url: "mailto:[email protected]")
link.formatted_url
# => "mailto:[email protected]" # Preserves mailto: protocol
```
## Creating Links Programmatically
```ruby
# Link to an internal page
link = Spree::PageLink.create!(
parent: section,
label: 'Shop Now',
linkable: store.pages.find_by(type: 'Spree::Pages::ShopAll')
)
# Link to a product
link = Spree::PageLink.create!(
parent: section,
label: product.name,
linkable: product
)
# Link to a taxon
link = Spree::PageLink.create!(
parent: section,
label: 'New Arrivals',
linkable: store.taxons.find_by(name: 'New Arrivals')
)
# External link
link = Spree::PageLink.create!(
parent: section,
label: 'Visit Our Blog',
url: 'https://blog.example.com',
open_in_new_tab: true
)
```
## Automatic Label Setting
When a link's `linkable` is set, the label is automatically populated from the linked resource:
```ruby
link = Spree::PageLink.new(linkable: product)
link.valid?
link.label
# => "Red T-Shirt" (from product.name)
```
The label is derived from (in order):
1. `linkable.title`
2. `linkable.display_name`
3. `linkable.name`
## Related Documentation
- [Sections](/v5/developer/storefront/rails/sections) - Adding links to sections
- [Blocks](/v5/developer/storefront/rails/blocks) - Adding links to blocks
- [Pages](/v5/developer/storefront/rails/pages) - Understanding internal page linking