DSL
ReactiveAdmin reads your ActiveAdmin declarations as they are. Use the DSL only for hints the classic admin doesn't need. You can add four kinds of hints:
- A
reactive do ... endblock inside a resource, for search, masking, menu placement, exposure, exposed actions and render modes. apiguards, for what the API must refuse.- Named option sources, for typeahead inputs.
- A menu overlay, for placing resources and pages in the navigation.
The reactive block
Add a reactive block inside an ActiveAdmin.register block or a register_page block:
ActiveAdmin.register Author do
reactive do
search :family_name, :given_name, :email
mask :ssn
menu path: ["Editorial"], priority: 20
expose :merge, if: ->(record) { record.active? }
render_as :frame, action: :team_history
end
endThe block accepts these methods.
search
search :family_name, :given_name, :emailLists the columns that typeahead searches when this resource is the target of an association input. Only text columns count. Without this call, the gem searches the display-name methods, then common name columns such as name and first_name. Use search when those defaults don't match what operators type.
Pasting a record's id also finds that record, whichever columns you search.
mask
mask :ssn, :date_of_birthMasks the named attributes in this resource's index, show, and form. The gem sends a masked node in place of each value, and it never sends the value in a form. Use mask for a secret on one resource. Use config.masked_attributes for a name that applies across the app. See Security.
sensitive
sensitive trueMarks this resource's display names as sensitive. Lookups that return its records (typeahead, _options/lookup, _labels) publish lookup.reactiveadmin. sensitive false opts out of config.sensitive_resources. See Security.
menu
menu path: ["Setup", "Billing"], priority: 30, label: "Invoices", icon: "receipt"Places the resource in the menu without changing its AA menu call. The path lists group labels from the top. It can hold at most two labels. An empty array places the resource at the top level. The options priority, label, description, and icon are optional.
If you also declare a placement in ReactiveAdmin.menu, the overlay wins. See Menu overlay.
new_needs_parent
belongs_to :author, optional: true
reactive { new_needs_parent }For a resource with an optional belongs_to whose new can only build under its parent, for example build_new_resource calls Author.find(params[:author_id]). The manifest then leaves new and create out of the resource's actions and permissions, so the client offers no top-level New button and the crawl skips the form. Index, show and edit still work at the top level. The nested new route is unchanged.
nested_layout
reactive { nested_layout :admin_policy_permissions, :cards }Sets how a has_many section lays out its rows: :compact or :cards. Without it, the gem picks compact when every row holds exactly one visible control (a text, select or single typeahead; the hidden id aside) and the section isn't sortable, and cards otherwise. A compact section is a dense list: one line per row, the section heading as the label (without heading:, the single control's label, pluralized: "Admin policy" becomes "Admin policies"), an add control at the bottom, and pending removals shown struck through with Undo. Saved rows read as plain text; selecting one turns it into its control, and Escape puts it back. The write is the same *_attributes either way. Add max_rows: 10 to has_many to stop the client offering more rows; the server doesn't enforce it.
expose
expose :merge
expose :archive, if: ->(record) { record.active? }Lists a member action, or a GET collection action, as a header button. Without expose, an action appears only when an action item or a link in the content references it.
The if: lambda receives the record for a member action. It receives no arguments for a collection action. The lambda runs in the view context, so helpers such as current_active_admin_user are available. If the lambda raises, the button stays hidden.
Non-GET collection actions can't be exposed. They're forms, and a button alone can't submit their params.
Pass true or false instead of an action name to set exposure for the whole resource or page:
expose true # serve it under config.expose = :listed, without a menu placement
expose false # deny it, even when a menu or exposed_resources lists itBoth apply only when config.expose = :listed. See Security.
render_as
render_as :frame, action: :team_history
render_as :custom, action: :board, custom_key: "team-board"
render_as :iframeForces how a custom view is shown. Modes are native, frame, iframe, and custom. The custom mode requires custom_key:. Without action:, the override applies to every custom action of the resource, or to the page content for a page. See Custom views for what each mode means.
unsafe_gets
unsafe_gets :reset_counterMarks GET custom actions that change data. The API takes every GET and HEAD action for a read, even one that redirects or sends data, so list the rare GET that mutates. A listed action is a write: a bearer token needs the write scope for it, the write audit records it, api :read_only refuses it, and MCP's run_action asks for confirmation.
mcp
mcp :full # every tool the api guards and the policy allow
mcp :read_only # the read tools only
mcp :read_only, actions: [:approve, :tidy] # plus these custom or batch actions
mcp actions: [:approve] # the same, for short
mcp :none # left out of MCP entirelySets what AI agents get of this resource or page through the MCP server. Without it, config.mcp.default applies, which is :read_only. actions: only adds to :read_only, and any other mode with it raises ArgumentError. A mode never widens an api guard: whichever of the two refuses wins.
api
api false # everything, the same as api :deny
api :deny, only: [:impersonate, :do_impersonate]
api :deny, except: [:index, :show] # everything but these
api :deny, attributes: [:superadmin] # writes that include these
api :read_only # GET and HEAD only
api :session_only, only: [:destroy] # the React client yes, API tokens no
api :superadmin_session, only: [:update], reason: "Superadmins edit from the admin"Makes the server refuse what must not run through the API, whoever asks and however they authenticate: the React client and anything else that dispatches through it, such as MCP. The classic admin is unaffected. api is a top-level call in an ActiveAdmin.register or register_page block, like menu, not inside reactive do. Calling it inside reactive do also works.
ActiveAdmin.register User do
api :deny, only: [:impersonate, :do_impersonate], reason: "Impersonation happens in the classic admin"
api :deny, attributes: [:superadmin]
endThe first argument is the guard:
| Guard | The API refuses |
|---|---|
false or :deny | The named actions, or everything without only: and except:. |
:read_only | Everything but GET and HEAD: writes, batch actions, and member, collection and page actions that aren't GETs, or that are GETs listed in unsafe_gets. The forms of the writes it refuses (new, edit) go too, because they can't be submitted. |
:session_only | Requests that authenticate with a token (a bearer header, as MCP does). A signed-in session, the React client, is let through. |
| a registered name | Whatever your guard says. See below. |
Options:
only:andexcept:work likebefore_action, and don't combine. Names are member, collection and page actions, standard actions (:index,:show,:new,:create,:edit,:update,:destroy),:batch_actionfor all batch actions, or the name of one batch action.:newand:creatego together, as do:editand:update, inonly:and inexcept:: a form you can't open is one you may not submit. Without either, the guard covers the whole resource or page: index, show, forms, exports,_meta,_options,_value,_labels, every write and every action.attributes:applies the guard to writes that include one of these names at any depth of their params, including inside*_attributes. Reading them is unchanged. For an association, the foreign key and_idscount too. It combines withonly:andexcept:, which scope the write actions that check it (the default is every write).:read_onlytakes no attributes.reason:is the message users read instead of the guard's default.
Guards stack: any refusal wins. On MCP requests the resource's mcp mode stacks the same way, so a guard narrows what the mode allows and never widens it. A refused request gets 403 with code api_denied, the guard that refused, a classic_url, and for attributes their names. See Security.
What the metadata says
deny, read_only and session_only are static: the manifest, _meta, form payloads, the menu, the OpenAPI document and MCP already know what they refuse, so each channel is told what is true for it.
- A denied action or attribute is marked
api_denied: truewith aclassic_url, and the client shows a link to the classic admin, opened in a new tab, instead of a button or an editable field. A resource or page denied whole leaves the manifest, and its menu entry becomes a link to the classic page. - For a session,
:session_onlyactions are offered as usual. For a bearer or MCP request they are marked like any denial. OpenAPI documents them for a session withx-reactiveadmin-session-only: true, and leaves them out for a token. - MCP never lists a denied resource, page, action, batch action or field.
- A resource or page whose every action a static
:denycovers, whether declared whole (api false) or action by action, is an accepted decision: the doctor lists it under "API guards (accepted)", and the legacy inventory never reports it asnot_exposed.
Custom guards
Register a guard once, in an initializer, and name it in api:
ReactiveAdmin.api_guard(:superadmin_session) { |user, request| user.superadmin? && !request.authorization }
# the same:
ReactiveAdmin.api_guards[:superadmin_session] = ->(user, request) { user.superadmin? }The block gets the current user and the request, and returns true to allow. It runs on every request the declaration covers, so the metadata can't know the answer: it stays, and carries api_guard: "superadmin_session" (x-reactiveadmin-guard in OpenAPI, and "may be refused (superadmin_session)" in MCP). A guard that returns false, raises or is no longer registered refuses; nothing here fails open. Registration has to happen before the admin files load: a name that isn't registered raises ArgumentError when the declaration is read, so a typo stops the boot.
rake reactiveadmin:doctor lists every declaration, and reports a name in only: or except: that matches no action as api_guard_unknown_action, because it guards nothing.
Option sources
Use an option source when several inputs share one list, or when a list needs a search that the model can't express. Register sources once, in an initializer or another file that loads with the app:
ReactiveAdmin.option_sources do
source :authors, -> { Author.all }, label: :name, search: [:name, :email]
source :posts, -> { Post.all }, label: :title, search: [:title]
endEach source takes a name, a relation, and these options:
| Option | Default | Purpose |
|---|---|---|
label | The record's display label | A method name or a proc that returns the option label. |
value | :id | A method name or proc that returns the submitted value. |
search | Resolved from the model | The columns the typeahead searches. |
hint | nil | Secondary text shown under each option. |
policy | scope_options_by_policy | Whether to limit the list to rows the user may read. |
The relation can also be a lambda. The lambda runs in the view context, so it can read the current user. A plain array works too. Array entries are [label, value], [label, value, hint], or {label:, value:, hint:}; the hint is optional, searched with the label, and shown muted next to it. The classic admin ignores hints.
Use a source in a filter or form
Pass as: :typeahead and source: to a filter or an input:
filter :author_id_eq, label: "Author", as: :typeahead, source: :authors
form do |f|
f.inputs do
f.input :author, as: :typeahead, source: :authors
end
endThe classic admin renders the same source as a datalist. The API renders it as a searchable typeahead. The API inlines the list when it has at most inline_options_limit entries. Larger lists load through the _options endpoint as the user types.
Scope a source to a parent
Use scope: to narrow a source. A lambda with one argument receives the relation. A lambda with two arguments also receives the form object:
f.input :post, as: :typeahead, source: :posts,
scope: ->(posts, form) { posts.where(author_id: form.object.author_id) }Inside a has_many, the form object is the parent record's form.
Menu overlay
Use ReactiveAdmin.menu to place resources, pages, and links in one file. The overlay sits on top of ActiveAdmin's own menu:
# app/admin/menu.rb
ReactiveAdmin.menu do
group "Setup", priority: 90, icon: "settings" do
group "Billing" do
resources :billing_plans, :invoices
page :batch_operations
link "Sidekiq", url: "/sidekiq", if: -> { current_active_admin_user.superadmin? }
end
end
hide :legacy_reports, :batch_operations
endKeep the file under app/admin so it reloads with ActiveAdmin.
Rules
- Precedence. The overlay wins over
reactive { menu path: }, which wins over AA'smenu parent:. Anything the overlay doesn't place keeps ActiveAdmin's placement. - Depth. Use at most two levels of groups. Put items inside the second level. Deeper nesting raises
MenuOverlay::DepthErrorin development and test. In production, it logs a warning and records a diagnostic. - Visibility. Items the user may not see stay out of the menu. Groups left empty are removed.
- Hidden in AA. Placing a resource or page that AA hides with
menu falseshows it in the React menu. The classic AA menu doesn't change. Thecommentsresource works the same way whenconfig.comments = false(its key iscomments_registration_nameunderscored and pluralized, such asadmin_comments). Placement doesn't skip authorization: the user still needs read access. A resource without anindexaction, or one that exists only under a requiredbelongs_toparent, can't be placed. - Links.
linktakesurl:as a string or a proc, andif:as a lambda. Both run in the view context, so helpers such asauthorized?are available. Alinkis an explicit decision: the legacy inventory doesn't list it as a classic menu link, and the doctor lists it under "Menu links (accepted)". Only links the menu inherited from ActiveAdmin that point at classic URLs stay in the inventory. - Hiding.
hide :key, ...marks resources and pages as intentionally absent from the React menu. They are removed from the menu even where AA places them, and the audit no longer reports them as unplaced. It works at the top level and inside groups. Hiding doesn't make a resource exposed underexpose = :listed. - Audit. The overlay records mismatches as diagnostics when the menu builds. It flags duplicate placements, keys that don't match a registered resource or page (including keys passed to
hide), placed keys that can't appear (menu_hidden: noindexaction, nested under a required parent, or denied underexpose = :listed), and resources that the overlay doesn't place and doesn'thide.
Limit the fields sent
Control the fields in the classic declarations, and use mask for values that must never leave the server:
- With an
index,show, orformblock, the API sends only the fields that block declares. - Without a block, index and show summarize json columns, truncate text columns (both expandable through the audited
_valueendpoint), and omit binary, encrypted, filtered, and masked columns under the defaultimplicit_defaults = :secure. The default form shows ActiveAdmin's default inputs. - If a block raises, the gem logs a warning and falls back to the defaults. It doesn't stop the request.
For resources that hold sensitive data, declare an explicit block for each section. Read Security for the full guidance.