Avo 4.0 documentation map

A map of every Avo 4.0 documentation page and its headings, designed for easy navigation by LLMs.

For the concise index, see llms.txt. For the full text of every page in one file (large — high token count), see llms-full.txt. For this map as raw markdown, see docs-map.md.

Auto-generated from the VitePress sidebar by scripts/generate-docs-map.js. Do not edit manually.

Document structure

• ## marks documentation groups (e.g. 'Resources')
• ### marks individual documentation pages
• Nested bullets show the headings within each page
• Each page title links to the full documentation

Avo 4

Getting Started

• The core
• Add-ons
• Your code
• Security
• Build it with AI agents
• Seamless upgrades
• Start here
• Where to go next

Upgrade Guide

• Upgrade to avo-dashboards 4.3.4
  • Breaking Change
  • Action Required
  • Steps to Update
• Upgrade to avo-advancedsearch 4.3.3
  • Breaking Change
  • Action Required
• Upgrade to avo 4.3.11
  • Breaking Change
  • Action Required
  • Maintaining Previous Behavior
• Upgrade to avo-api 4.4.0
  • Breaking Change
  • Action Required
• Upgrade to avo 4.3.9
  • Breaking Change
  • Action Required
  • Breaking Change
  • Action Required
• Upgrade to avo-authorization 4.3.3
  • Breaking Change
  • Action Required
• Upgrade to avo-ai 4.3.0.beta.8
  • Breaking Change
  • Action Required
• Upgrade to avo-api 4.3.1
  • Breaking Change
  • Action Required
• Upgrade to avo-auditlogging 4.3.1
  • Breaking Change
  • Action Required
• Upgrade to avo-collaboration 4.3.2
  • Breaking Change
  • Action Required
• Upgrade to avo-dashboards 4.3.2
  • Breaking Change
  • Action Required
• Upgrade to avo-dynamicfilters 4.3.1
  • Breaking Change
  • Action Required
• Upgrade to avo-httpresource 4.3.1
  • Breaking Change
  • Action Required
• Upgrade to avo-kanban 4.3.2
  • Breaking Change
  • Action Required
• Upgrade to avo-mcpserver 4.3.0.beta.2
  • Breaking Change
  • Action Required
• Upgrade to avo-menu 4.3.1
  • Breaking Change
  • Action Required
  • Breaking Change
  • Action Required
• Upgrade to avo-nested 4.3.2
  • Breaking Change
  • Action Required
• Upgrade to avo-notifications 4.3.1
  • Breaking Change
  • Steps to Update
• Upgrade to avo-recordreordering 4.3.1
  • Breaking Change
  • Action Required
• Upgrade to avo-scopes 4.3.1
  • Breaking Change
  • Action Required
• Upgrade to avo 4.3.6
  • What changed
  • Action Required
• avo-ai, avo-mcpserver, avo-menu: an action's visible block applies everywhere
  • What changed
  • Action Required
• avo: bulk actions find the selected records through findrecords
  • What changed
  • Action Required
• avo-mcpserver: records are named by toparam
  • What changed
  • Action Required
• avo: attaching a hasmany, hasone or HABTM record follows attachscope
  • What changed
  • Action Required
• avo: a belongsto value that matches no record is a form error
  • What changed
  • Action Required
• avo: a field declared once per view saves through the form's declaration
  • What changed
  • Action Required
• avo-ai and avo-mcpserver: writes go through the resource's fields
  • What changed
  • Action Required
• Upgrade to avo 4.3.2
  • Breaking Change
  • Action Required
  • Maintaining Previous Behavior
• Upgrade to avo 4.3.1
  • Breaking Change
  • Action Required
  • Breaking Change
  • Action Required
  • Maintaining Previous Behavior
  • Breaking Change
  • Action Required
  • Breaking Change
  • Action Required
  • Steps to Update
• avo-mcpserver: a shipped countrecords tool
  • What changed
  • Action Required
• avo: forms ask before you leave with unsaved changes
  • What changed
  • Action Required
  • Maintaining Previous Behavior
• Built-in neutral themes now share one lightness curve
  • What Changed
  • Action Required
• Field authorization: avo-authorization 4.2.1
  • What changed
  • Action Required
• avo-api 4.2.7: visible: hides a field from the API too
  • What changed
  • Action Required
• avo-ai 4.2.0.beta.6: the chat reads through the resource's fields
  • What changed
  • Action Required
• avo-mcpserver 4.2.0.beta.9: sorting and errors follow the resource's fields
  • What changed
  • Action Required
• avo-ai: the composer limits what it uploads
  • What changed
  • Action Required
  • What changed
  • Action Required
• avo-ai: records are named by toparam
  • What changed
  • Action Required
• Upgrade to avo-ai 4.2.0.beta.4
  • What changed
  • Action Required
  • What changed
  • Action Required
  • What changed
  • Action Required
• Upgrade to avo-auditlogging 4.3.0
  • What changed
  • Action Required
  • What changed
  • Action Required
• Upgrade to 4.3.0
  • Breaking Change
  • Action Required
• Upgrade to 4.2.0
  • Breaking Change
  • Action Required
  • Breaking Change
  • Action Required
  • Breaking Change
  • Breaking Change
• Upgrade to 4.1.15
  • Deprecation
  • Action Required
• Upgrade to 4.1.11
  • Breaking Change
  • Action Required
• Upgrade to avo-calendar 4.0.3
• Upgrade to 4.1.10
• Upgrade to 4.1.7
  • Breaking Change
  • Action Required
• Upgrade to avo-dashboards and avo-scopes 4.1.2
  • Breaking Change
  • Action Required
  • Steps to Update
• Upgrade to 4.1.4
  • Breaking Change
  • Maintaining Previous Behavior
  • Breaking Change
  • Maintaining Previous Behavior
• Upgrade to avo-dashboards 4.0.9
  • Breaking Change
  • Maintaining Previous Behavior
• Upgrade to 4.0.20
  • Breaking Change
  • Breaking Change
• Upgrade to 4.0.18
  • Breaking Change
  • Action Required
  • Steps to Update
• Upgrade to 4.0.17
  • Breaking Change
  • Action Required
  • Steps to Update

Avo 3 to Avo 4 upgrade

• Upgrading using a coding agent
• Get started with Avo 4
  • Upgrade your Ruby version
  • Upgrade your gems
  • Icons
  • Avatars and initials
• Allow the license check host in your test suite
• Search
  • Resource search
  • Global search
    • Fully owned component
    • Enhanced navigation and keyboard shortcuts
    • New "Show all results" functionality
    • Breaking changes and migration notes
• Actions
  • Confirmation option renamed
    • Static configuration
    • Dynamic configuration (lambda)
    • If you customized the actions modal/view
• Layout
  • mainpanel is obsolete
    • mainpanel is the first panel and has no sidebar
    • mainpanel is the first panel and has a sidebar
    • Content above mainpanel
    • Renamed Avo::PanelComponent to Avo::UI::PanelComponent
    • Removed the fieldcontainer view helper
    • Renamed withtools slot to withcontrols
  • panel title in keyword arguments
  • tab title in keyword arguments
• Branding renamed to Appearance
  • Rename the configuration key
  • colors: hash removed
    • Bringing your exact colors back
  • CSS custom properties renamed
• Components
  • Renamed view type components
• avo-pro and avo-advanced split into feature gems
  • Pro features
    • Policy helpers
  • Advanced features
    • Resource scopes
• Nested association forms
• Searchable association picker rewritten without Algolia
• Pagination
  • Replace size with slots
• Breadcrumbs
• Renamed profilephoto to avatar
• Renamed coverphoto to cover
• Grid Item Badge DSL tweaks
  • Migration steps
• Discreet information updates
  • API tweaks
• Removed cluster (and its alias row) in favor of width
  • Replace cluster / row with width
  • Supported width values
  • Removed field wrapper options
  • New usestackedfields configuration
• Map view tweaks
• Added labelhelp option
• Cards description option renamed to discreetdescription
• Removed config.fullwidthindexview configuration for config.containerwidth
• Added sidebartogglevisible configuration option
• Added self.description option to actions
• Added self.icon option to resources
• Added loading: :manual for on-demand associations and tabs
  • Remembering an opened frame with autoloadfor
• Added config.associations for global association defaults
  • config.associationslookuplistlimit moved into the namespace
  • Association frames now default to lazy loading
• Added view.single? method
• Dynamic Filters alwaysexpanded default changed to true
• explicitauthorization default changed to true

Technical Support

• (No headings found)

🤖 Agentic engineering

• Code editors and LLM setup
  • Pick your tool
• Skills
  • Keeping them current
  • Core
  • Config & ops
  • Customization
  • Add-ons
  • Cross-cutting
  • One loader for every project
• MCP server
• Suggested workflow

AI

Overview

• Two ways in
• What holds on both
• Where to go next

Chat

• Requirements
• Installation
  • 1. Install the gem
  • 2. Run the installer
  • 3. Set your provider API key
  • 4. Add the admin resources to the menu
  • 5. Verify
  • 6. Teach the assistant your app
• Configuration
  • Thinking
  • Timestamps
• How the assistant works
  • Record chips
• Answering the assistant's questions
• Your actions, from the chat
  • Finding an action without naming its resource
  • What it's allowed to run
  • Undoing a run
  • Tracing what it changed
• Files and attachments
  • Getting new files in
  • Reading files and importing from them
• Teach the assistant your app
  • Let your coding agent write it
  • The inventory
  • Writing it by hand
• Customize the assistant's instructions
  • Add your own instructions
  • Rename the assistant
  • Replace the shipped prompts
• Choose which tools the assistant gets
  • Take a tool away
  • Bring your own tool
  • Serve the same tool over MCP
  • Replace a shipped tool with your own copy
  • See what a conversation will get
• Replace the assistant's icon
• What you start the chat from
  • Starting from a Media Library file
  • Starting from a conversation
  • The rows you checked
  • The page you were on
  • Change how it reads
• Open the chat
  • Use only full-page chats
  • Closing idle tabs automatically
• Full-page chats
• The conversation menu
• Write a message
• Send files with a message
  • What the composer accepts
  • Protect the direct-upload endpoint
• Attach a skill with a message
  • Import a skill
• Connect other tools with MCP
  • Connect a server
  • Share a connection
  • Approve a call
  • Manage a connection
  • When a connection stops working
• Dictate a message
  • Browser support, and where the audio goes
• While the assistant is replying
• When a reply fails
  • When the worker dies mid-reply
  • Where the failure is reported
  • Who sees what went wrong
• When each message was sent
• Copy a message
• Rate a reply
  • Review feedback
  • Choose who can review feedback
  • Turn feedback off
  • Notify reviewers of new feedback
• Choose which models people can use
  • Pinning the provider
  • Switching model mid-conversation
• Choose who can manage skills
• Turn on MCP connections
  • Set it up
  • Choose who can connect and share
  • Record remote calls in the audit log
  • Before you open it up
• Who can see a chat
• Who can delete a chat
• Debug levels

What you can ask

• Add a reusable skill
• Find records
• Count and break down
• Look around your admin
• Create records
• Change and delete records
• Undo something
• Run your actions
• Work with files
• Ask about the page you're on
• Ask about the rows you checked
• Ask about a file you sent
• Reach your other systems
• Manage the conversation
• What it won't do

Agents and tools

• The agents
  • The chat agent
  • The conversation renamer
• The tools
  • Tools from connected MCP servers
  • The shapes an ask can take
  • Where tools get their context
  • Schema comes back with the answer
• Renaming conversations
• Seeing a conversation's roster

MCP server

• Requirements
• Install
  • 1. Add the gem
  • 2. Run the installer
  • 3. Mount the endpoints
  • 4. Turn it on
• Connect a client
  • What the admin sees on the authorize page
• Choose what a connection can do
• Every call stays inside the admin's own permissions
  • Keep a field out of a client's reach
• Add tools of your own
  • Share a tool with Avo AI
• Review and revoke connections
  • What the status means
  • Tell connections apart
  • See and change what a connection may reach
  • Read a connection's access at a glance
  • Watch what a connection is doing
  • Decide who sees and revokes what
• Run it in production
  • Pin the server address
  • Behind a proxy or load balancer
  • Rate limits
  • Turn it off without losing the connections resource
  • Keep credentials out of your logs
• Trace changes back to a connection
• Triage errors a client reports
• Full example
• Options reference

MCP Server reference

• Configuration
• Routing
• Generators
• Tools
  • Arguments
• Capabilities
• Error codes
• Connection log
• Panel classes
  • Policy methods
  • Translations
• Rate limits
• Protocol

CLI

• Requirements
• Installation
  • 1. Install the gem
  • 2. Connect to your app
  • 3. Check what the token reaches
• Connect without logging in
• Look up what you can send
• Export an OpenAPI document
• List records
• Read one record
• Create a record
• Update a record
• Delete a record
• Send the right value for a field
  • Key-value and code fields
  • Files
  • Long or awkward values
• Get JSON for a script
• Sign out
• When a command fails
  • Exit 1: the app refused or did not answer
  • Exit 2: the CLI refused before sending
• Command reference

Configuration

Installation

• Requirements
• Installing Avo
  • 1. One-command install
  • 2. Manual, step by step.
  • 3. In popular Rails starter kits
    • Bullet Train
    • Jumpstart Pro
• Install from GitHub
• Mount Avo to a subdomain
• Next steps

Routing

• Default mounting behavior
• Mount Avo under a scope
• Mount Avo under a nested path
• Serve Avo from a custom map in config.ru
• Namespaced resource routes
• Add your own routes

Customization API

• Application
• Index view
• Layout
• Behavior
• Development and generators
• Status and metadata
• Routing
• Licensing
• Authentication
• Authorization
• Localization
• Appearance
• Cache
• Keyboard shortcuts
• Menus
• Breadcrumbs
• Search
• Resources
• Field discovery
• Fields layout
• TailwindCSS

Gem server authentication

• On the server and CI systems
  • Heroku
  • Hatchbox
  • GitHub Actions
    • 1. Add BUNDLEPACKAGERDEV to your repository's secrets
    • 2. Expose BUNDLEPACKAGERDEV as an environment variable
  • Docker and Docker Compose
  • Kamal
• On your local development environment
• Add Avo to your Gemfile
• Rotate the gem server token
• Bundle without the paid gems
• FAQ
  • Forbidden 403
  • Forbidden 403 in a sandboxed or cloud environment (Cursor Cloud)

License troubleshooting

• Check the license status page
• Frequent issues

Authentication

• Customize the currentuser method
• Customize the profile widget
• Customize the sign-out link
  • Customize the current user resource name
  • Customize the entire sign-out path
• Filter out requests
• authenticatewith method
• User roles
  • Check if a user is an admin
  • When does Avo check if the use is an admin (isadmin?)
  • Check if a user is an developer
  • When does Avo check if the use is an developer (isdeveloper?)
  • Customize the methods that check for roles
• Authorization

Authorization

• Set up authorization
• Write a policy
• Authorize association controls
  • Reuse another policy for an association
• Authorize file attachments
• Limit which records a user sees
• Hide fields from a user
  • Allow or deny fields
  • What a withheld field is withheld from
  • Trust each interface differently
  • Combine with visible:
  • Limits
• Let a user see a field but not change it
• Use a different policy for a resource
• Rename the policy methods Avo calls
• Handle missing policies
• When the license lapses
• Debug a denied action
• Use a different authorization library
• Manage roles with Rolify

Authorization API

• Configuration
• Resource options
• Resource policy methods
• Association policy methods
• Attachment policy methods
• Policy scope
• Field lists
  • Field list errors
• Client contract

Performance

• Cache store selection
  • Custom selection
• Row caching
  • What invalidates a cached row
  • What a key cannot fix
• Caching caveats
  • Rows may not be automatically updated when certain associations change
    • Option 1: Use touch: true on association
    • Option 2: override cachehash method on resource to take associations in consideration
  • rootpath change won't break the cache keys
• Solid Cache
• Log ViewComponent loading times and allocations
  • 1. Enable ViewComponent Instrumentation
  • 2. Add Logging

Resources

Overview

• Overview
• Generate resources
  • Alongside a model
  • With the resource generator
  • For all your models
• Fields
• Routing
• Name and describe records
• Avoid n+1 queries
• Control sorting
• Customize how records are fetched
• Customize pagination
• Control the saving flow
• Warn before deleting dependent records
• Tweak the Index view
• Record previews
• Manage sidebar presence and shortcuts
• Link to the record's public page
• Swap the view components
• Use multiple resources for the same model
• Namespaced resources
• Views
• Extending Avo::ResourcesController
  • --parent-controller option on the generators
  • resourceparentcontroller configuration option
  • Attach concerns to Avo::BaseController
• Manually registering resources
• Extending Avo::BaseResource
• Modify controls placement and appearance
• Cards

Resources API

• Identity
• Index view
  • Examples
• Forms and saving
  • What counts as a change
  • How the user is asked
  • Not covered
• Navigation
• Performance
• Customization
• Options documented on their own pages

Array Resource

• Paginate at the source
• Create, edit and delete
• Render it inside another resource

HTTP Resource

• Install the gem
• Generate a resource
• Parse the API response
• Send authentication headers
• Map sorting and filtering to query params
• Customize the backing model
• Handle API errors
• Customize create, update, and destroy
• Debug console
  • Add it to the sidebar
  • JSON API
• Full example

HTTP Resource API

• Request options
• Response parsing
• Model customization

Scopes

• Generate a scope
• Register the scope on a resource
  • Set a default scope
  • Remove the "All" scope
• Show record counts
• Control who sees a scope
• Dynamic values
• Localization
  • Or assign a callable
  • Translating a label cannot break scope selection
  • The cost of a callable
  • Translating the gem's own chrome
• Limit index columns per scope
• Describe the selected scope in the header
• Full example

Scopes API

• Execution context
• Scope class options
• Registration options

Record reordering

• Set up reordering with actsaslist
• Always show the order buttons
• Choose where the buttons appear
• Sort the Index view by position
• Reorder using drag and drop
  • Custom position attribute
• Authorization

Record reordering API

• Ordering actions
• Visibility
• Drag and drop

Discreet information

• Show the record's ID
• Show timestamps without using a field
• Add a custom item
• Turn an item into a link
• Show an item conditionally
• Full example

Discreet Information API

• Preconfigured items
• Custom item options

Custom controls

• Add controls to dashboard headers
• Customize the show controls
• Customize the edit controls
• Customize the index controls
• Customize the row controls
• Keep the default controls
• What you can put in a control
  • Links
  • Built-in controls
  • Actions
  • Turbo triggers
  • JavaScript triggers
• Group links and actions in a dropdown
• Conditionally show controls

Custom controls API

• Control areas
• Controls
  • exclude
  • include
  • target
  • data
  • class
• Control options

Actions

• What happens when an action runs
• Generate an action
• Register the action on a resource
• Collect input with fields
  • Choose an associated record in a collection action
• Write the handle method
• Give feedback to the user
• Control what happens after execution
  • Build a multi-step flow
• Customize the modal
• Run an action without records
• Work with every record on the Index
• Control visibility and authorization
• Trigger an action from a link
• Read params from the page that triggered the action
• StimulusJS

Actions API

• Registration
• Modal and appearance
• Behavior
• The handle method
• Feedback methods
• Response methods
• Class methods

Select All

• How does it work?
• Coming back to the index
• Serializing the query
• Serialization known issues

Cover and Avatar

• Add an avatar
• Add a cover photo
• Options

Record chips

• Choose what the chip shows
• Give the chip a background
• Add fields that fit the answer
• Customize the hover text
• Keep links and authorization consistent
• Support streaming and reloads

Record chips API

• Chip declaration
• Background
• Tooltip
• Dynamic fields
• Record resolution and layout

Views

• Index
  • Add content to the index
• Show
• Edit
• New
• View groups
  • Display
  • Form
  • Single
• Preview
• Checking the current view
• Multiple ways to check
• Common visibleon configuration values
• View types
  • Restrict the available view types

Slots

• Choose the view and region
• Add content to the index
• Customize a single record page
• Share additions across Edit and New
  • Keep custom inputs inside the form
  • Choose a shared or view-specific replacement
  • Support creation modals and repeated controls
• Add the same content to every resource
• Wrap or replace default content
• Use loaded records in slot content
• Keep slot rendering inexpensive
• Keep slots when customizing the index
• Troubleshoot missing or unexpected content

Resources API

• Identity
• Index view
  • Examples
• Forms and saving
  • What counts as a change
  • How the user is asked
  • Not covered
• Navigation
• Performance
• Customization
• Options documented on their own pages

Table view

• Row controls
  • Global configuration
  • Resource configuration
• Style rows with rowoptions
  • Configuration shape
  • Examples
    • Highlight by record state
    • Dim soft-deleted rows
    • Branch on render context
    • Conditional return values
  • Hover and selection co-existence
  • Dark mode
  • Tailwind class discovery
  • Performance
  • Migration from row component overrides
  • Limitations

Table view API

• Row controls
• Row styling
  • Supported keys
    • Other HTML attributes
  • Reserved data keys
  • Denied attributes

Grid view

• Enable grid view
• Options
• Make grid the default view
• Custom style
• Grid Item Badge
  • Complete Example
  • Options

Map view

• Enable map view
• Make it the default view

Custom view types

• 1. Create the view type component
• 2. Register the view type
• 3. Configure a resource to use it
• Full example: avo-notifications
• Add styles and interactivity

Fields

Fields

• Declaring fields
  • Specific methods for each view
• Field conventions
  • A more complex example
• Field types
• WYSIWYG & Markdown editors
  • Which one should I pick?
  • Shared Show view behavior
  • Resizable editors

Field options

• Change the field label
• Show and hide fields on different views
• Show fields conditionally
• Hide fields that have no value
• Compute the value with a block
• Format displayed values
  • On every view
  • On specific views
  • With Rails helpers
• Parse the value before saving
• Make columns sortable
  • Sort computed fields and associations
• Mark fields as required
• Prevent users from editing a field
• Set a default value
• Add help text
• Add a tooltip
• Add a placeholder
• Focus a field when the form opens
• Place fields on the same row
  • Stack the label above the value
    • inline layout (default)
    • stacked layout
  • Global stacked layout
• Store empty values as NULL
• Link the table cell to the record
• Summarize a column
• Let users copy the value
• Align text on the Index view
• Customize the field components
  • Eject the field components
  • Point the field at your components
• Target a different database attribute
• Pass arbitrary data to the field
• React to changes in other fields
  • Dependent select
  • Derived value (slug from name)

Field options API

• Naming and description
• Visibility on views
• Formatting values
• Form behavior
• Index view
• Layout and rendering
• Advanced

HTML attributes

• Declare the fields from the outside in
• The object notation
• The block notation
• Where are the attributes added?

Field discovery

• Scope which fields are discovered
• Pass options to every discovered field
• Combine manual and discovered fields
• Override how columns map to fields

Field Discovery API

• Method options
• Discovery behavior
  • Mapping precedence
  • Ignored columns
  • Association defaults
• Global configuration
• Default mappings
  • Column names
  • Column types
  • Associations

Layout

• Layout building blocks
• Header
• Group fields into panels
  • How Avo computes panels
  • Index view fields
• Move compact fields to a sidebar
• Organize fields under tabs
  • Loading behavior on Show and Edit
  • Durable and bookmarkable selection
• Position labels: inline vs. stacked
• Multi-column rows with width

Fields layout API

• Header
• Panels
• Sidebar
• Tabs

Area

• Description
• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
• Full example

Array

• Example 1: Array field with a block
• Example 2: Array field fetching data from the model's method
• Example 3: Fallback to the records method
• Paginate at the source
• Summary of Data Fetching Hierarchy

Avatar

• (No headings found)

Badge

• Description
• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
• Editing the value
  • Custom labels with a Select field
• Examples
  • Using semantic colors
  • Using base colors
  • Showing the moment behind a status

Boolean

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values

Boolean group

• DB payload example
• Field declaration example
• Options
  • Default value
  • Computed options
• Updates

Checkbox list

• Options

Code

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values

Country

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values

Date

• Options

Date time

• Options

Easy MDE

• Options
  • Default value
  • Possible values

External image

• Options
  • Default value
  • Possible values
  • Example with proc
  • Default value
  • Possible values
  • Example with proc
  • Default value
  • Possible values
  • Example with proc
• Conditional sizing based on view
• Use computed values
• Use in the Grid cover position

File

• Variants
  • Example:
• Options

Files

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values

Gravatar

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
• Using computed values

Heading

• Options
  • Default value
  • Possible values

Hidden

• Example usage:

Id

• Options

Key value

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
• Customizing the labels
• Suggest common keys and values
• Enforce restrictions

Lexxy

• Requirements
• Options
  • Default value
• Action Text
• Media Library
• Editor configuration

Location

• Description
• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values

Markdown

• Supported features
• Customize the renderer
• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values

Money

• Money Field Example
  • Example on new
  • Example on show
  • Example on index
• Installation
• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values

Number

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
• Formatting numbers
• Examples

Password

• Options
  • Default value
  • Possible values
• Related

Preview

• Define the fields
• Authorization

Progress bar

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
• Examples

Radio

• Field declaration example
• Options
  • Default value
  • Possible values
  • Default value
  • Possible values

Record link

• Options
  • Default value
  • Possible values
  • Example
  • Default value
  • Possible values
  • Example
  • Default value
  • Possible values
  • Example
• Using computed values
  • Example

Rhino

• Options

Select

• Options
  • Default value
  • Possible values
  • Computed options
    • Default value
    • Possible values
  • Computed grouped options
    • Default value
    • Possible values
    • Default value
    • Possible values
    • Default value
    • Possible values

Stars

• Options
  • Default value
  • Possible values
• Examples

Status

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values

Tags

• Options
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values
• PostgreSQL array fields
• Acts as taggable on
• Array fields

Text

• Options
  • Default value
  • Possible values
• Customization

Textarea

• Options
  • Default value
  • Possible values

Time

• Options

Tip Tap

• Options

Trix

• Options
  • Default value
  • Default value
  • Possible values
• File attachments
  • Attachments without an attachmentkey
• Disable attachments
• Remove attachment attributes
• Active Storage
• Action Text
• Demo app
• Javascript Alert Messages

Overview

• The model association has to exist first
• Common options
• Show or hide the association buttons
• Single Table Inheritance (STI)
• Link to child resource when using STI
• Add custom labels to the associations' pages

Searchable

• Requirements
• Boolean form
• Hash form
  • query:
  • enabled:
  • item:
• Default options
• Polymorphic belongsto
  • With boolean form
  • With hash form

Searchable associations API

• Boolean form
• Hash form
• Options
  • Polymorphic fields

Belongs to

• Overview
• Polymorphic belongsto
• Polymorphic help
• Belongs to attach scope
• Allow detaching via the association
• Options
  • Default value
  • Possible values
  • Example
  • Default value
  • Possible values
  • Example
  • Default value
  • Possible values
  • Default value
  • Possible values
  • Default value
  • Possible values

Has one

• Options
• Has One Through

Has many

• Options
• Has Many Through

Has and belongs to many

• Options

Filters

Overview

• Basic filters
• Dynamic filters
• Which one should you use?
• Common behavior
• Dive deeper

Basic Filters

• Generate a filter
• Register the filter on a resource
• Pick a filter type
  • Boolean filter
  • Select filter
  • Multiple select filter
  • Text filter
  • Date time filter
• Set a default value
• Populate options dynamically
  • Compose filters that depend on each other
• React to other filters
• Show a message when there are no options
• Show or hide a filter conditionally
• Pass arguments to a filter
• Keep the filters panel open
• Link to a pre-filtered view
• Open a filter in your editor

Basic filters API

• Class options
• Instance methods
• Runtime objects
• Date time filter options
• Registration
• URL encoding helpers

Dynamic Filters

• Authorize the attributes for Ransack
• How conditions combine
• Filter types
• Customize a filter
  • Restrict or rename the conditions
  • Write a custom query
  • Filter across multiple columns or associations
  • Offer suggestions or fetch values from an API
  • Apply instantly, without the Apply button
  • Humanize the filter pills
• Configure the filters bar
• Localization
  • How the keys resolve
• Caveats
• Guides & Tutorials
  • belongsto example
  • hasmany example
  • The problem: repetitive filter code
  • Method 1: helper method with field configuration
  • Method 2: separate fields and filters with helper
  • Method 3: programmatic filter generation
  • Method 4: custom DSL with method override
  • Choosing the right approach

Dynamic filters API

• Filter options
• Global configuration
• Filter types and their conditions
  • Boolean
  • Date
  • Number
  • Select
  • Text
  • Tags
• Field-to-filter mapping

Customize Avo

Customization

• Change the app name
• Timezone and currency
• Resource Index view
  • Per-page pagination
  • Default view type
  • Map styles
  • Sorting direction
  • Row density
  • Click a row to view the record
  • Cache resources on the Index view
  • Search debounce
  • Modify controls placement and appearance
• ID links to resource
• Container width
  • Upgrading from fullwidthcontainer / fullwidthindexview
• Toggle the sidebar button visibility
• Resizable sidebar
  • Change the starting width
  • Turn resizing off
• Body classes
• Hide the layout when printing
• Send the user back to the top
• Home path
• Skip show view
• Open a record in your editor
  • Resources
  • Actions
  • Filters
  • Dashboards
  • Cards
  • Forms
• Context
• Alerts
• Persist UI state
• Associations
  • Lookup list limit
  • Association frames
• Turbo
• Default URL options
• Logger
• Status page
• Usage metadata
• Generators
  • Custom viewcomponent path
  • Generate Avo resources alongside models
• Page titles
• Mount Avo under a nested path
• Custom query scopes
• Customize profile name, photo, and title
• Eject
• Breadcrumbs

Customization API

• Application
• Index view
• Layout
• Behavior
• Development and generators
• Status and metadata
• Routing
• Licensing
• Authentication
• Authorization
• Localization
• Appearance
• Cache
• Keyboard shortcuts
• Menus
• Breadcrumbs
• Search
• Resources
• Field discovery
• Fields layout
• TailwindCSS

Eject views

• Eject a partial
  • Prepared templates
• Eject a component
• Eject field components
• Scope ejected components
• Eject a controller
• Options reference

Menu editor

• Menu item types
• Add everything at once
• Sub-items
• Trigger actions from the menu
• Item visibility
• Authorization
• Add data attributes to items
• Icons
• Icon colors
• Keyboard shortcuts on menu items
• Collapsable sections and groups
  • Default collapsed state
• Profile menu
  • Forms in the profile menu
  • Custom content in the profile menu
• Header menu

Menu editor API

• Structure items
• Item types
• Bulk helpers
• Shared options

Search

• Enable search for a resource
• Run a different query per surface
• Search within associations
• Authorize search
• Limit the number of results
• Global search
  • Direct record lookup
  • Navigation section
  • Configure the global search
  • Hide a resource from the global search
  • Customize how results render
• Custom search providers

Search API

• Resource configuration
• searchtype
• Global search configuration
• Limiting results
• Custom search providers

Keyboard Shortcuts

• Configure keyboard shortcuts
• Change or disable a shortcut
• Global shortcuts
• Appearance shortcuts
• Assistant
• Index view
• Show view
• Edit view
• Modals
• Assign hotkeys to the sidebar menu
• Add your own shortcuts
• Shortcuts hidden inside association panels

Keyboard Shortcuts API

• Switches
• Bindings
• Hotkey syntax
• Shortcut IDs
  • Core
  • Add-ons
  • Fixed keys
• Plugin shortcuts

Localization (I18n)

• How Avo resolves a label
• The key map
  • How the paths are derived
• Localizing resources
• Localizing actions
• Localizing scopes, cards, and dashboards
• Localizing fields
• Localizing tabs and panels
• Localizing the delete confirmation
• Localizing buttons label
• Setting the locale
• Locale selector
• Right-to-left locales
• Dates and the date picker
• Customize the locale
• What you can safely put under avo.
  • Pluralization hashes accept extra keys
  • Where your own keys go
  • See which keys are taken
  • What a collision looks like
• Add-on gems
• FAQ
  • The I18n.t method defaults to the name of that field/resource
  • Using a Route Scope for Localization

Appearance

• Customize the logo
  • Desktop logo
  • Dark mode logo
  • Mobile logomark
  • Favicon
  • Placeholder image
• Set the default color scheme
• Choose a neutral palette
  • Preset
  • Custom neutral palette
• Choose an accent palette
  • Preset
  • Custom accent palette
• Restricting picker options
• Locking choices
• Persist picks across devices
  • Cookie (default)
  • Database
    • How the blocks receive data
    • Required schema
• Change the switcher layout
• Sound feedback
• Customize chart colors
• CSS customization
  • Applying overrides
• Full example
• Options reference

Appearance API

• Theme selection
• Custom palettes
• Picker control
• Persistence
• Assets
• Charts
• CSS variables
  • Layout
  • Fonts
  • Top navbar
  • Sidebar
  • Table
  • Focus ring
  • Motion speed

Theming

• Do it by hand
• Recolor with the appearance config
• Re-skin with CSS variables
  • Let an AI agent do it
• Change the font
  • Load a hosted font
  • Self-host the font files
• Fine-tune specific components
  • Set a background image
• Style your custom UI
• Eject a view for full control

Multitenancy

• Breakdown
• Route-based tenancy
  • 1. Set the proper routing pattern
  • 2. Keep the tenant in every generated URL
  • 3. Set the tenant for each request
• Session-based tenancy
  • 1. Set the tenant for each request
  • 2. Add an account switcher
• See also

Custom tools

• Generate tools
  • Controller
  • Route
  • Sidebar item
  • Customize the sidebar
• What's available in your tool
• Set the page title
• Add assets
• Using helpers from your app
  • Using path helpers
    • For Avo paths
    • For the main app paths

Resource tools

• Generate a resource tool
• Partial context
• Tool visibility
  • Using path helpers
    • For Avo paths
    • For the main app paths
• Add custom fields on forms
• Where to add logic

Custom fields

• Generate a new field
• Start from an existing field
• Field options
• Field Visibility
• What's available in your components
  • How the field wrapper ties it together
• Customize the views
• Field assets
• Collapse long content on Show
• Make an editor field resizable
• Use pre-built Stimulus controllers
  • Hidden input controller
  • Non existing model field
• Field methods

Custom errors

• Add a custom error
  • Errors on a join record
• Where errors appear

Asset handling

• Supported asset pipelines
• How Avo ships its own assets
• Add your own CSS and JavaScript
  • With Importmap
  • With jsbundling and esbuild
  • With rollup or webpack
  • Manually (Sprockets or Propshaft)
• Load order and overriding Avo's styles
• Add custom styles or Tailwind classes
• Exclude Avo's assets from a CDN
• Add assets from a plugin

JavaScript & Stimulus

• Assign Stimulus controllers to resource views
  • Field wrappers as targets
  • Field inputs as targets
  • All controllers receive the view value
• Assign Stimulus controllers to actions
• Attach HTML attributes
• Composing the attributes together
• Pre-made stimulus methods
  • resource-edit#toggle
  • resource-edit#disable
  • resource-edit#debugOnInput
• Custom Stimulus controllers
• Use Stimulus JS in a tool
  • Set up a controller
  • Register that controller with the current Stimulus app
  • Use the controller in the Avo tool

TailwindCSS integration

• Auto-enable behavior
• Add your custom Avo styles
• Override styles and scripts (avo-overrides.css / avo-overrides.js)
  • Add behavior with Stimulus
• Disable integration (opt-out)
• Host content scan paths (tailwindcsscontentsources)
• Debugging

Plugins

• Overview
  • Light layer
• Register the plugin
• Hook into Avo
• Hooks
• Registration API
• Let apps configure your plugin
• Add asset files
• Using a middleware to surface asset files
• Create your own plugin

Avo.asset_manager

• Add a stylesheet file
• Add a javascript file
• Register a Stimulus controller

Concepts

Overview

• What's here
• What belongs here

Breadcrumbs

• Change the starting breadcrumb
• Add a breadcrumb
  • addbreadcrumb options
• Breadcrumbs for custom pages

Tooltips

• Add a tooltip to any element
• Use it with Avo's buttons and links
• Show rich, HTML tooltips
• Re-initialize after injecting markup
• Built-in tooltips

Icons

• How to use
• Libraries
  • 1. The Avo icons
  • 2. Tabler
    • Example:
  • 3. Heroicons
    • Examples:
• Use your own icons

Resource controllers

• Change where the user is redirected
• Customize the flash messages
• Return a custom response
• Change how records are saved or destroyed
• Use the parent record

Resource controllers API

• Create methods
• Update methods
• Destroy methods
• Persistence methods
• Parent record methods

How pages are rendered

• The request lifecycle
• 1. The beforeaction chain
• 2. The action method
• 3. Choosing the view component
• 4. The layout
• 5. The ERB template
• Turbo Stream responses
• Where to hook in

Rails engines and path helpers

• The rule
• Inside the Avo engine
  • Linking to Avo pages
  • Linking to your main application
  • Linking to Avo add-ons
  • Inside view components
• Why this matters
• Quick reference
• Learn more

Add-ons

Notifications

• Requirements
• Installation
  • 1. Install the gem
  • 2. Run the installer
  • 3. Run migrations
  • 4. Include the concern in your User model
• Configuration
• Sending notifications
  • Who receives a notification
  • Choosing a level
  • Tagging with a type
  • Adding action buttons
  • From Avo actions
  • From model callbacks
  • From background jobs
• Notification states
• Reading notifications
• Bell component
• Real-time delivery
  • How it works
  • ActionCable setup
• Notification resource
  • Scopes
  • Bulk actions
• Customize the notification index
• Cleanup

Notifications API

• Configuration
• Send parameters
• Query and state API
• User model methods

Media Library

• How to enable it
• Control who can use it
• Add it to the menu editor
• File previews
• Use it with the rich text editors
  • Disable it on a single markdown field

Audit Logging

• Requirements
• Installation
  • 1. Install the gem
  • 2. Run the installer
  • 3. Migrate
• Enable and configure audit logging
  • Enable it globally
  • Configure author models
  • Enable specific resources and actions
• Display logged activities
  • Show activities on a specific record
  • View and navigate activity logs
  • Keep secrets out of the payload
  • Enable change logs and revert changes
  • Show all activity by an author
  • Show an overview of all activities
• Where an activity came from
  • Mark your own origins
  • Record activity from your own code
  • Record changes no person made
  • Log changes made outside Avo
  • Pause logging for a block of code
• Read an activity in code
  • When an activity has several records
  • Always read the first record
• Control who sees which activities
  • Show each user only their own activity
  • Show the history of the records a user can see
• Disable specific actions logging
• Conclusion

Dashboards

• Generate a dashboard
• Settings
• Global ranges
• Localization
  • Or assign a callable
• Refresh every card at once
• Add header controls
• Run actions from the header
• Cards
  • Override card arguments from the dashboard
    • Control the base settings from the parent
• Dashboards visibility
• Dashboards authorization

Dashboards API

• Identity and layout
• Ranges
• Header controls
• Visibility and authorization

Cards

• Base settings
  • description
  • discreetdescription
• Ranges
  • Control the aggregation using ranges
• Keep the data fresh
  • Refresh a card on demand
• Cache an expensive query
• Localization
  • Or assign a callable
  • It holds on the refresh path too
  • The cost of a callable
  • Translating the gem's own chrome
• Hide the header
• Format
• Metric card
  • Calculate results
  • Decorate the data using prefix and suffix
• Chartkick card
  • Chart types
  • Customize chart
• Partial card
• HTML card
  • Inline ERB string
  • Tag builder
  • Renderables
• Table card
  • Headers
  • Row links
  • Density
  • Empty state
  • Ranges and refreshing
• List card
• Cards visibility
• Dividers

Cards API

• Base settings
• Ranges
• Metric card
• Chartkick card
• Partial card
• HTML card
• Data cards (table & list)
• Registration overrides
• Dividers
• Standalone card components

Kanban board

• Overview
• Requirements
• Installation
• DB schema
• Create a kanban board
• Create columns
• Configure the board
• Adding items to the board
• How does it work?
  • Board and Columns
  • Resources and Items
  • Add items to the board
  • Move items between columns
  • Items without that property
• Customize the card
• Authorization
  • Authorization Methods
• Customizing kanban models for your business logic

Calendar view

• Requirements
• Installation
  • 1. Install the gem
  • 2. Enable the view on a resource
• Configuration
• All-day and hour-based events
• Month and week views
  • Read a crowded day
• Event previews
• Navigation and filtering
  • Pressing Today on today's own range
• Customize the calendar index

Forms and pages

• Install the add-on
• Quick start
• How it works
• Generate forms and pages
• Build a form's fields
  • Group fields with cards and panels
  • Place fields side by side
  • Prefill from a record
• Handle a form's submission
  • Flash messages
• Restrict who can use a form
• Reusable vs. inline forms
• Render a form anywhere
• Organize pages
• Build a page's navigation
• Put forms on a page
• Set the container width
• Name the menu entry
• Add pages to the main menu
• Full example
• Best practices

Forms & Pages API

• Shared attributes
• Form attributes
• Form methods
• Page attributes
• Page navigation and content

REST API

• Installation
  • Install the API tokens table
• Mount the API
  • Mount options
• Endpoints
• Discovery
  • The resource listing
  • One resource's fields
  • OpenAPI document
    • 1. Download the document
    • 2. Import it into your tool
    • What is inside
• Authentication
  • Create a token
  • Send the token
  • Token lifecycle
  • A token acts as its owner
  • Your app's own authentication still runs
  • Keep the credential safe
  • How the secret is stored
• Reading data
  • Index
  • Show
  • Field serialization
• Writing data
  • Create
  • Update
  • Delete
  • Field value formats
• Entitle a token
  • Grant a resource
  • Read a token's access at a glance
  • Take a token back to unrestricted
  • Entitlements sit in front of your policies, never instead of them
  • Tell the three refusals apart
  • Who may change entitlements
  • What entitlements don't cover
• Bring your own authentication
  • Set the current user
  • Authentication examples
• Authorization
• Custom controllers
  • Your admin panel controllers are not inherited
• Array resources
  • Accept writes
  • What decides access
  • Sorting
• HTTP resources
• Manage tokens in the panel
  • Put it in the menu
  • Who may manage tokens
  • What each policy method controls
  • Everyone manages their own tokens
    • Freezing a revoked token
  • Who sees the owner
  • See what a token changed
• Works better with
• Localization
• Command line client

REST API reference

• Mounting
• Generators
• Controller hooks
  • Overridable methods
• Public API
• Status codes

Collaboration

• Installation
• Enable collaboration on a resource
  • Set the author name
  • Watch property changes
  • Customize reactions
• Place the timeline
• Authorization
• Extend the collaboration models

Collaboration API

• Resource configuration
• Timeline
• Authorization

MCP Server

• Requirements
• Install
  • 1. Add the gem
  • 2. Run the installer
  • 3. Mount the endpoints
  • 4. Turn it on
• Connect a client
  • What the admin sees on the authorize page
• Choose what a connection can do
• Every call stays inside the admin's own permissions
  • Keep a field out of a client's reach
• Add tools of your own
  • Share a tool with Avo AI
• Review and revoke connections
  • What the status means
  • Tell connections apart
  • See and change what a connection may reach
  • Read a connection's access at a glance
  • Watch what a connection is doing
  • Decide who sees and revokes what
• Run it in production
  • Pin the server address
  • Behind a proxy or load balancer
  • Rate limits
  • Turn it off without losing the connections resource
  • Keep credentials out of your logs
• Trace changes back to a connection
• Triage errors a client reports
• Full example
• Options reference

MCP Server reference

• Configuration
• Routing
• Generators
• Tools
  • Arguments
• Capabilities
• Error codes
• Connection log
• Panel classes
  • Policy methods
  • Translations
• Rate limits
• Protocol

AI assistant

• Requirements
• Installation
  • 1. Install the gem
  • 2. Run the installer
  • 3. Set your provider API key
  • 4. Add the admin resources to the menu
  • 5. Verify
  • 6. Teach the assistant your app
• Configuration
  • Thinking
  • Timestamps
• How the assistant works
  • Record chips
• Answering the assistant's questions
• Your actions, from the chat
  • Finding an action without naming its resource
  • What it's allowed to run
  • Undoing a run
  • Tracing what it changed
• Files and attachments
  • Getting new files in
  • Reading files and importing from them
• Teach the assistant your app
  • Let your coding agent write it
  • The inventory
  • Writing it by hand
• Customize the assistant's instructions
  • Add your own instructions
  • Rename the assistant
  • Replace the shipped prompts
• Choose which tools the assistant gets
  • Take a tool away
  • Bring your own tool
  • Serve the same tool over MCP
  • Replace a shipped tool with your own copy
  • See what a conversation will get
• Replace the assistant's icon
• What you start the chat from
  • Starting from a Media Library file
  • Starting from a conversation
  • The rows you checked
  • The page you were on
  • Change how it reads
• Open the chat
  • Use only full-page chats
  • Closing idle tabs automatically
• Full-page chats
• The conversation menu
• Write a message
• Send files with a message
  • What the composer accepts
  • Protect the direct-upload endpoint
• Attach a skill with a message
  • Import a skill
• Connect other tools with MCP
  • Connect a server
  • Share a connection
  • Approve a call
  • Manage a connection
  • When a connection stops working
• Dictate a message
  • Browser support, and where the audio goes
• While the assistant is replying
• When a reply fails
  • When the worker dies mid-reply
  • Where the failure is reported
  • Who sees what went wrong
• When each message was sent
• Copy a message
• Rate a reply
  • Review feedback
  • Choose who can review feedback
  • Turn feedback off
  • Notify reviewers of new feedback
• Choose which models people can use
  • Pinning the provider
  • Switching model mid-conversation
• Choose who can manage skills
• Turn on MCP connections
  • Set it up
  • Choose who can connect and share
  • Record remote calls in the audit log
  • Before you open it up
• Who can see a chat
• Who can delete a chat
• Debug levels

What you can ask

• Add a reusable skill
• Find records
• Count and break down
• Look around your admin
• Create records
• Change and delete records
• Undo something
• Run your actions
• Work with files
• Ask about the page you're on
• Ask about the rows you checked
• Ask about a file you sent
• Reach your other systems
• Manage the conversation
• What it won't do

Agents and tools

• The agents
  • The chat agent
  • The conversation renamer
• The tools
  • Tools from connected MCP servers
  • The shapes an ask can take
  • Where tools get their context
  • Schema comes back with the answer
• Renaming conversations
• Seeing a conversation's roster

Internals

Overview

• In this section
  • Public Methods and Internal Usage

Testing

• Allow the license check host in your test suite
• Testing helpers
• Testing Actions

Avo::Current

• (No headings found)

Avo::ExecutionContext

• How does the ExecutionContext work?
• Common objects

Avo::Services::EncryptionService

• How does the Avo::Services::EncryptionService work?
  • Public methods
  • Mandatory arguments:
  • Optional arguments
• Usage example
  • Basic text:
  • Objects with custom serializer:
• Secret key base

Reserved model names and routes

• Model names to avoid
• Why these names are reserved
• Alternative approaches
  • Using Avo with existing models
• Route Conflicts with resources :resources
  • How to Fix It

Avo::ApplicationController

• On extending the ApplicationController
• Responsibly extending the ApplicationController
• Override ApplicationController methods