API Reference

Table of contents

1. EncodedId::Rails::Model
   1. Instance Methods
      1. #encoded_id
      2. #slugged_encoded_id
      3. #annotation_for_encoded_id
      4. #name_for_encoded_id_slug
   2. Class Methods
      1. .find_by_encoded_id(encoded_id)
      2. .find_by_encoded_id!(encoded_id)
      3. .find_all_by_encoded_id(encoded_id)
      4. .where_encoded_id(encoded_id)
      5. .encode_encoded_id(id)
2. EncodedId::Rails::PathParam
   1. Instance Methods
      1. #to_param
3. EncodedId::Rails::SluggedPathParam
   1. Instance Methods
      1. #to_param
4. EncodedId::Rails::ActiveRecordFinders
   1. Class Methods (Overridden)
      1. .find
      2. .find_by_id
   2. Example Usage
5. EncodedId::Rails::Persists
   1. Instance Methods
      1. #set_normalized_encoded_id!
6. EncodedId::Rails::Configuration
   1. Configuration Options
7. EncodedId::Rails::AnnotatedId
8. EncodedId::Rails::SluggedId

EncodedId::Rails::Model

The main module to include in your ActiveRecord models.

class User < ApplicationRecord
  include EncodedId::Rails::Model
end

Including this module adds the following instance methods to your model:

Instance Methods

#encoded_id

Returns the encoded ID for this record, with optional annotation.

user = User.find(123)
user.encoded_id  # => "user_p5w9-z27j"

The annotation prefix is determined by the #annotation_for_encoded_id method, which by default returns the model’s parameterized name.

#slugged_encoded_id

Returns the encoded ID with a human-readable slug prepended.

user = User.find(123)
user.name = "John Doe"
user.slugged_encoded_id  # => "john-doe--user_p5w9-z27j"

The slug is generated by the #name_for_encoded_id_slug method, which must be implemented in your model.

#annotation_for_encoded_id

Returns the annotation prefix for the encoded ID. Override this method to customize.

class User < ApplicationRecord
  include EncodedId::Rails::Model
  
  def annotation_for_encoded_id
    "usr"  # Custom annotation
  end
end

user = User.find(123)
user.encoded_id  # => "usr_p5w9-z27j"

By default, returns the underscored model name.

#name_for_encoded_id_slug

Returns the string to use as the slug part of #slugged_encoded_id. Must be implemented in your model.

class User < ApplicationRecord
  include EncodedId::Rails::Model
  
  def name_for_encoded_id_slug
    full_name.presence || "user-#{id}"
  end
end

If not implemented, calling #slugged_encoded_id will raise an error.

Class Methods

.find_by_encoded_id(encoded_id)

Finds a record by its encoded ID.

# These all work:
User.find_by_encoded_id("user_p5w9-z27j")  # Annotation included
User.find_by_encoded_id("p5w9-z27j")       # Just the hash
User.find_by_encoded_id("john-doe--user_p5w9-z27j")  # Slugged version

Returns nil if no record is found.

.find_by_encoded_id!(encoded_id)

Same as find_by_encoded_id, but raises ActiveRecord::RecordNotFound if no record is found.

User.find_by_encoded_id!("user_p5w9-z27j")
# => #<User id: 123, name: "John Doe">

User.find_by_encoded_id!("invalid-id")
# => ActiveRecord::RecordNotFound

.find_all_by_encoded_id(encoded_id)

Finds all records with the given encoded ID. Useful when the encoded ID encodes multiple IDs.

# Encoded ID that contains multiple record IDs
User.find_all_by_encoded_id("7aq6-0zqw")
# => [#<User id: 78>, #<User id: 45>]

.where_encoded_id(encoded_id)

Returns an ActiveRecord relation for the given encoded ID.

User.where_encoded_id("user_p5w9-z27j").where(active: true)

This method handles all encoded ID formats:

• Annotated IDs: "user_p5w9-z27j"
• Slugged IDs: "john-doe--user_p5w9-z27j"
• Hash only: "p5w9-z27j"

If the encoded ID doesn’t correspond to a valid record, this will raise ActiveRecord::RecordNotFound.

.encode_encoded_id(id)

Encodes a record ID using the model’s configuration.

User.encode_encoded_id(123)  # => "p5w9-z27j"

EncodedId::Rails::PathParam

Module to include in your model to make it use encoded IDs in URL helpers.

class User < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::PathParam
end

user = User.find(123)
user.to_param  # => "user_p5w9-z27j"

Instance Methods

#to_param

Returns the encoded ID for use in URLs.

# In routes:
# resources :users, param: :encoded_id

# In views:
link_to "View User", user_path(user)  # => "/users/user_p5w9-z27j"

EncodedId::Rails::SluggedPathParam

Module to include in your model to make it use slugged encoded IDs in URL helpers.

class User < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::SluggedPathParam
  
  def name_for_encoded_id_slug
    full_name
  end
end

user = User.find(123)
user.name = "John Doe"
user.to_param  # => "john-doe--user_p5w9-z27j"

Instance Methods

#to_param

Returns the slugged encoded ID for use in URLs.

# In routes:
# resources :users, param: :encoded_id

# In views:
link_to "View User", user_path(user)  # => "/users/john-doe--user_p5w9-z27j"

EncodedId::Rails::ActiveRecordFinders

Module to include in your model to automatically handle encoded IDs in standard ActiveRecord finder methods.

class Product < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::ActiveRecordFinders
end

Important: This module should NOT be used with models that use string-based primary keys (e.g., UUIDs) as it will cause conflicts between string IDs and encoded IDs.

Class Methods (Overridden)

.find

Overrides the default ActiveRecord find method to automatically handle encoded IDs.

# Standard ActiveRecord finds by ID
Product.find(123)  # => #<Product id: 123>

# Now also works with encoded IDs
Product.find("product_p5w9-z27j")  # => #<Product id: 123>
Product.find("p5w9-z27j")  # => #<Product id: 123>
Product.find("cool-product--product_p5w9-z27j")  # => #<Product id: 123>

# Also handles encoded IDs containing multiple IDs
Product.find("z2j7-0dmw")  # => [#<Product id: 78>, #<Product id: 45>]

Raises ActiveRecord::RecordNotFound if the ID can’t be found or if the encoded ID fails to decode.

.find_by_id

Overrides the default ActiveRecord find_by_id method to handle encoded IDs.

# Standard behavior
Product.find_by_id(123)  # => #<Product id: 123>

# Now handles encoded IDs
Product.find_by_id("product_p5w9-z27j")  # => #<Product id: 123>

# Returns nil for non-existent records (instead of raising an error)
Product.find_by_id("invalid-id")  # => nil

Example Usage

class Product < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::ActiveRecordFinders
  include EncodedId::Rails::SluggedPathParam  # Optional
end

# Create a product and get its encoded ID
product = Product.create(name: "Example Product")
encoded_id = product.encoded_id  # => "product_p5w9-z27j"

# Now you can use standard ActiveRecord methods with encoded IDs
Product.find(encoded_id)                # => #<Product id: 1, name: "Example Product">
Product.find_by_id(encoded_id)          # => #<Product id: 1, name: "Example Product">

# Use with slugged IDs
slugged_id = product.slugged_encoded_id  # => "example-product--product_p5w9-z27j"
Product.find(slugged_id)                 # => #<Product id: 1, name: "Example Product">

# In controllers, you can simply use params[:id] directly
def show
  @product = Product.find(params[:id])  # Works with regular IDs and encoded IDs
end

EncodedId::Rails::Persists

Module to include in your model to persist encoded IDs in the database.

class User < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::Persists
end

Requires the following database columns:

• normalized_encoded_id (string): The encoded ID without formatting
• prefixed_encoded_id (string): The complete encoded ID with annotation

Instance Methods

#set_normalized_encoded_id!

Updates the persisted encoded ID columns for this record.

user = User.find(123)
user.set_normalized_encoded_id!

This method is called automatically when a record is created.

EncodedId::Rails::Configuration

Configuration for the Rails integration.

# In config/initializers/encoded_id.rb
EncodedId::Rails.configure do |config|
  config.salt = "my-secret-salt"
  config.min_hash_length = 8
  config.split_at = 4
  config.split_with = "-"
  config.alphabet = EncodedId::Alphabet.modified_crockford
  config.annotation_method_name = :annotation_for_encoded_id
  config.annotated_id_separator = "_"
  config.slug_value_method_name = :name_for_encoded_id_slug
  config.slugged_id_separator = "--"
  config.model_to_param_returns_encoded_id = false
end

Configuration Options

Option	Type	Default	Description
salt	String	Required	The salt used for encoding
id_length	Integer	8	Minimum length of the encoded hash
character_group_size	Integer or nil	4	Split encoded string every X characters
group_separator	String or nil	"-"	Character to split with
alphabet	EncodedId::Alphabet	EncodedId::Alphabet.modified_crockford	The alphabet to use for encoding
annotation_method_name	Symbol or nil	:annotation_for_encoded_id	Method to call for annotation prefix
annotated_id_separator	String	"_"	Separator between annotation and ID
slug_value_method_name	Symbol	:name_for_encoded_id_slug	Method to call for slug value
slugged_id_separator	String	"--"	Separator between slug and ID
model_to_param_returns_encoded_id	Boolean	false	Whether all models should override to_param
encoder	Symbol	:hashids	ID encoding engine (:hashids or :sqids)
blocklist	Array, Set, or nil	nil	Words to prevent in encoded IDs
hex_digit_encoding_group_size	Integer	4	For hex encoding (experimental)

EncodedId::Rails::AnnotatedId

Class for creating annotated IDs.

annotated_id = EncodedId::Rails::AnnotatedId.new(
  id_part: "p5w9-z27j",
  annotation: "user",
  separator: "_"
)
annotated_id.annotated_id  # => "user_p5w9-z27j"

EncodedId::Rails::SluggedId

Class for creating slugged IDs.

slugged_id = EncodedId::Rails::SluggedId.new(
  id_part: "user_p5w9-z27j",
  slug_part: "john-doe",
  separator: "--"
)
slugged_id.slugged_id  # => "john-doe--user_p5w9-z27j"