Skip to content
Primer/ViewComponents
Design
Interface guidelinesOcticonsDesktopMobileCLI
Build
CSSReactReact BrandViewComponents
ContributeAbout

On this page

Overlay

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
On this page
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.

Accessibility

  • 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.

Arguments

NameTypeDefaultDescription
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

Slots

show_button

Optional button to open the Overlay.

NameTypeDefaultDescription
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

Header content.

NameTypeDefaultDescription
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

body

Required body content.

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

footer

Footer content.

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

Examples

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 %>