Skip to main contentPrimer

Overlay

readyNot reviewed for a11y
Lookbook|Source
This page may be removed. Primer plans to move all Rails component documentation to Lookbook.

Description

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

NameRequiredDescription
id
String

The id of the Overlay.

title
String

Describes the content of the Overlay.

subtitle
String

Provides dditional context for the Overlay, also setting the aria-describedby attribute.

popover
Symbol

The popover behaviour. One of :auto or :manual.

size
Symbol

The size of the Overlay. One of :auto, :large, :medium, :medium_portrait, :small, or :xlarge.

padding
Symbol

The padding given to the Overlay body. One of :condensed, :none, or :normal.

anchor
String

An ID of the element to anchor onto. Defaults to the show_button.

anchor_align
Symbol

The anchor alignment of the Overlay. One of :center, :end, or :start.

anchor_side
Symbol

The 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_offset
Symbol

The anchor offset to give the Overlay. One of :normal or :spacious.

allow_out_of_bounds
Boolean

Allow the Overlay to overflow its container.

visually_hide_title
Boolean

If true will hide the heading title, while still making it available to Screen Readers.

role
String

The ARIA role. One of nil, :dialog, or :menu.

system_arguments
Hash

Slots

show_button

Optional button to open the Overlay.

NameRequiredDescription
icon
String

Name of Octicons to use instead of text. If provided, a Primer::Beta::IconButton will be rendered. Otherwise a Primer::Beta::Button will be rendered.

controls
String

The ID of the menu this button controls. Used internally.

button_arguments
Hash

The arguments accepted by Primer::Beta::Button or Primer::Beta::IconButton depending on the presence of the icon: argument.

header

Header content.

NameRequiredDescription
divider
Boolean

Show a divider between the header and body.

size
Symbol

One of One of :auto, :large, :medium, :medium_portrait, :small, or :xlarge..

visually_hide_title
Boolean

Visually hide the title while maintaining a label for assistive technologies.

system_arguments
Hash

body

Required body content.

NameRequiredDescription
padding
Symbol

The padding. One of :condensed, :none, or :normal.

system_arguments
Hash

footer

Footer content.

NameRequiredDescription
show_divider
Boolean

Show a divider between the footer and body.

system_arguments
Hash

Overlay::Header

A Overlay::Header is a compositional component, used to render the Header of an overlay. See Primer::Alpha::Overlay.

Arguments

NameRequiredDescription
title
String

Describes the content of the Overlay.

subtitle
String

Provides additional context for the Overlay, also setting the aria-describedby attribute.

overlay_id
String

Provides the id of the overlay element so the close button can close it

size
Symbol

The size of the Header. One of :large or :medium.

divider
Boolean

Show a divider between the header and body.

visually_hide_title
Boolean

Visually hide the title while maintaining a label for assistive technologies.

system_arguments
Hash

Slots

filter

Optional filter slot for adding a filter input to the header.

NameRequiredDescription
system_arguments
Hash

subtitle

Optional subtitle slot for adding a subtitle to the header.

NameRequiredDescription
system_arguments
Hash

Overlay::Footer

A Overlay::Footer is a compositional component, used to render the Footer of an overlay. See Primer::Alpha::Overlay.

Arguments

NameRequiredDescription
show_divider
Boolean

Show a divider between the footer and body.

align_content
Symbol

The alginment of contents. One of :center, :end, or :start.

system_arguments
Hash

Overlay::Body

A Overlay::Body is a compositional component, used to render the Body of an overlay. See Primer::Alpha::Overlay.

Arguments

NameRequiredDescription
system_arguments
Hash