Use overlay to provide a flexible floating surface for displaying transient content such as menus, selection options, dialogs, and more.
  • Alpha
  • Not reviewed for accessibility
This component requires JavaScript to function. Please refer to the Installation section to set it up.

Overlay components codify design patterns related to floating surfaces such as dialogs and menus. They are private components intended to be used by specialized components, and mostly contain presentational logic and behavior.


  • Overlay Accessible Name: An overlay should have an accessible name, so screen readers are aware of the purpose of the Overlay when it opens. Give an accessible name setting :title. The accessible name will be used as the main heading inside the Overlay.
  • Overlay unique id: A Overlay should be unique. Give a unique id setting :id. If no :id is given, a default randomize hex id is generated.

The combination of both :title and :id establishes an aria-labelledby relationship between the title and the unique id of the Overlay.


idStringself.class.generate_idThe id of the Overlay.
titleStringN/ADescribes the content of the Overlay.
subtitleStringnilProvides dditional context for the Overlay, also setting the aria-describedby attribute.
popoverSymbol:autoThe popover behaviour. One of :auto or :manual.
sizeSymbol:autoThe size of the Overlay. One of :auto, :large, :medium, :medium_portrait, :small, or :xlarge.
paddingSymbol:normalThe padding given to the Overlay body. One of :condensed, :none, or :normal.
anchorStringnilAn ID of the element to anchor onto. Defaults to the show_button.
anchor_alignSymbol:startThe anchor alignment of the Overlay. One of :center, :end, or :start.
anchor_sideSymbol:outside_bottomThe side to anchor the Overlay to. One of :inside_bottom, :inside_center, :inside_left, :inside_right, :inside_top, :outside_bottom, :outside_left, :outside_right, or :outside_top.
anchor_offsetSymbol:normalThe anchor offset to give the Overlay. One of :normal or :spacious.
allow_out_of_boundsBooleanfalseAllow the Overlay to overflow its container.
visually_hide_titleBooleanfalseIf true will hide the heading title, while still making it available to Screen Readers.
roleStringnilThe ARIA role. One of nil, :dialog, or :menu.
system_argumentsHashN/ASystem arguments



Optional button to open the Overlay.

iconStringN/AName of Octicon to use instead of text. If provided, a IconButton will be rendered. Otherwise a Button will be rendered.
controlsStringN/AThe ID of the menu this button controls. Used internally.
button_argumentsHashN/AThe arguments accepted by Button or IconButton depending on the presence of the icon: argument.

Header content.

dividerBooleanN/AShow a divider between the header and body.
sizeSymbolN/AOne of One of :auto, :large, :medium, :medium_portrait, :small, or :xlarge..
visually_hide_titleBooleanN/AVisually hide the title while maintaining a label for assistive technologies.
system_argumentsHashN/ASystem arguments


Required body content.

paddingSymbolN/AThe padding. One of :condensed, :none, or :normal.
system_argumentsHashN/ASystem arguments

Footer content.

show_dividerBooleanN/AShow a divider between the footer and body.
system_argumentsHashN/ASystem arguments


Overlay with Cancel and Submit buttons

An ID is provided which enables wiring of the open and close buttons to the Overlay.

Some content

<%= render(Primer::Alpha::Overlay.new(
title: "Overlay Example",
id: "my-Overlay",
role: :dialog,
)) do |d| %>
<% d.with_show_button { "Show Overlay" } %>
<% d.with_body do %>
<p>Some content</p>
<% end %>
<% end %>