shadcn-rails

Popover

Displays rich content in a portal, triggered by a button.

Stimulus: shadcn--popover

Installation

Add the component to your project:

rails generate shadcn:component popover

Usage

<%= render Shadcn::PopoverComponent.new do |popover| %>
  <% popover.with_trigger do %>
    <%= render Shadcn::ButtonComponent.new(variant: :outline) { "Open popover" } %>
  <% end %>
  <% popover.with_body do %>
    <div class="grid gap-4">
      <div class="space-y-2">
        <h4 class="font-medium leading-none">Dimensions</h4>
        <p class="text-sm text-muted-foreground">
          Set the dimensions for the layer.
        </p>
      </div>
      <div class="grid gap-2">
        <div class="grid grid-cols-3 items-center gap-4">
          <label for="width" class="text-sm">Width</label>
          <input id="width" value="100%" class="col-span-2 h-8 rounded-md border px-3" />
        </div>
        <div class="grid grid-cols-3 items-center gap-4">
          <label for="height" class="text-sm">Height</label>
          <input id="height" value="25px" class="col-span-2 h-8 rounded-md border px-3" />
        </div>
      </div>
    </div>
  <% end %>
<% end %>

Examples

Basic

Positions

Use the side prop to control the popover position.

Alignment

Use the align prop to control the alignment relative to the trigger.

With Form Content

Popovers can contain interactive form elements.

Modal Mode

When modal is true, interaction with the rest of the page is blocked.

Initially Open

Set open: true to show the popover by default.

API Reference

PopoverComponent

API Reference

Prop Type Default Description
open Boolean false Whether the popover is open by default
side Symbol :bottom Side to position the popover (:top, :right, :bottom, :left)
align Symbol :center Alignment relative to trigger (:start, :center, :end)
modal Boolean false Whether to trap focus and block interaction with the rest of the page
class_name String nil Additional CSS classes to apply to the popover wrapper

Slots

API Reference

Prop Type Default Description
trigger Block nil The button or element that triggers the popover
body Block nil The content to display in the popover

Stimulus Controller

This component requires JavaScript. The Stimulus controller docs provides interactivity.

Handles popover open/close state, positioning, and click-outside behavior.

Installation

Add to your config/importmap.rb:

pin "shadcn-rails", to: "shadcn/index.js"

Then in your app/javascript/controllers/index.js:

import { Application } from "@hotwired/stimulus"
import { registerShadcnControllers } from "shadcn-rails"

const application = Application.start()
registerShadcnControllers(application)

Or import just this controller:

import DocsController from "shadcn-rails/controllers/docs_controller"

application.register("docs", DocsController)

Targets

Name Description
trigger The element that triggers the popover
content The popover content element

Values

Name Type Default Description
open Boolean Whether the popover is currently open
side String Side to position the popover (top/right/bottom/left)
align String Alignment relative to trigger (start/center/end)
modal Boolean Whether to block interaction with the rest of the page

Actions

Action Description
toggle Toggles the popover open/closed
show Opens the popover
hide Closes the popover
close Alias for hide

TypeScript

Type definitions are included. Import types as needed: 

import type { DocsController } from "shadcn-rails"

Accessibility

  • Press Escape to close the popover
  • Click outside the popover to close it
  • When modal: true, focus is trapped within the popover
  • Ensure trigger elements are keyboard accessible (buttons, not divs)
  • Keep popover content concise and focused
  • Avoid nesting popovers within popovers