pluginaweek/state_machine

Analysis updated 2026-07-03

★ 3,723RubyAudience · developerComplexity · 2/5Setup · easy

Mindmap

mindmap
  root((state_machine))
    What it does
      Model state transitions
      Enforce valid paths
      Fire callbacks
    Integrations
      ActiveRecord Rails
      DataMapper Mongoid
      GraphViz diagrams
    Use Cases
      Order workflows
      User lifecycle
      Game state logic
    Audience
      Ruby developers
      Rails app builders

mindmap root((state_machine)) What it does Model state transitions Enforce valid paths Fire callbacks Integrations ActiveRecord Rails DataMapper Mongoid GraphViz diagrams Use Cases Order workflows User lifecycle Game state logic Audience Ruby developers Rails app builders

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Model an order workflow in a Rails app so orders can only move from pending to processing to shipped in a valid sequence, blocking invalid jumps.

USE CASE 2

Track multiple independent states on a single Ruby object at the same time, such as a user's subscription status and email verification status.

USE CASE 3

Generate a visual diagram of your state machine transitions using GraphViz to share with teammates or include in technical documentation.

USE CASE 4

Attach callbacks to specific state transitions so an email sends or a log entry writes automatically whenever a particular change happens.

What is it built with?

RubyActiveRecordDataMapperMongoidMongoMapperSequelGraphViz

How does it compare?

	pluginaweek/state_machine	thoughtbot/clearance	feedbin/feedbin
Stars	3,723	3,733	3,745
Language	Ruby	Ruby	Ruby
Setup difficulty	easy	easy	hard
Complexity	2/5	2/5	4/5
Audience	developer	developer	developer

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 30min

Integrations with ActiveRecord and other ORMs require their respective gems to already be installed in your project.

In plain English

state_machine is a Ruby library that helps you model objects whose behavior changes depending on what "state" they are in. Think of a traffic light: it can be red, yellow, or green, and only certain transitions between those states are allowed. Without a library like this, developers usually track state by juggling multiple true/false flags on an object, which gets messy fast. state_machine replaces that approach with a clean, explicit description of what states exist, what events trigger a change between them, and what code runs before or after each change. You attach a state machine directly to any Ruby class by calling a single method in the class definition. You name your states and events, then describe which transitions are allowed. For example, a vehicle might start in a parked state, move to idling when ignited, then shift through gears from there. If someone tries to make an invalid transition (parking directly from second gear without downshifting), the machine blocks it. You can attach callbacks to run code when specific transitions happen, conditionally block transitions based on business logic, and even run multiple state machines on the same class for independent attributes. The library integrates with the most common Ruby database tools, including ActiveRecord (the default for Ruby on Rails apps), DataMapper, Mongoid, MongoMapper, and Sequel. This means state values get stored to and loaded from a database column automatically, with no extra wiring. It also supports internationalization so that state names can be translated for different languages, and it can generate visual diagrams of your state machine using a tool called GraphViz. A single class can have more than one state machine running at the same time, each tracking a different attribute. You can namespace them so their generated methods do not collide. State values can be strings, integers, or any other data type. The library also supports checking whether a transition is currently possible before attempting it, which is useful for building UI controls that enable or disable based on what actions are available. The project appears to be mature but no longer actively developed, based on the use of legacy CI infrastructure in the README. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1

I have a Rails Order model with statuses like pending, processing, and shipped. Show me how to set up state_machine with ActiveRecord to enforce valid transitions and fire a callback on each status change.

Prompt 2

How do I add two separate state machines to the same Ruby class using state_machine without their generated methods conflicting with each other?

Prompt 3

Write a state_machine definition for a traffic light with red, yellow, and green states, including a guard that prevents skipping directly from red to green.

Prompt 4

How do I use state_machine's GraphViz integration to generate a visual diagram of my state machine and export it as a PNG image?

Frequently asked questions

What is state_machine?

A Ruby library that adds formal state machines to any class, letting you define allowed states, transitions, and callbacks instead of juggling scattered boolean flags across your codebase.

What language is state_machine written in?

Mainly Ruby. The stack also includes Ruby, ActiveRecord, DataMapper.

How hard is state_machine to set up?

Setup difficulty is rated easy, with roughly 30min to a first successful run.

Who is state_machine for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Scan in gitsafehub Deploy in gitdeployhub pluginaweek on gitmyhub

Verify against the repo before relying on details.