Skip to content
Primer Design System

Primer Design System

Overlay

Overlay components codify design patterns related to floating surfaces such as dialogs and menus.

On this page

v0.35.0AlphaNot reviewed for accessibility

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

NameTypeDefaultDescription
id
String

self.class.generate_id

The id of the Overlay.

title
String

N/A

Describes the content of the Overlay.

subtitle
String

nil

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

popover
Symbol

:auto

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

size
Symbol

:auto

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

padding
Symbol

:normal

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

anchor
String

nil

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

anchor_align
Symbol

:start

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

anchor_side
Symbol

:outside_bottom

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

:normal

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

allow_out_of_bounds
Boolean

false

Allow the Overlay to overflow its container.

visually_hide_title
Boolean

false

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

role
String

nil

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

system_arguments
Hash

N/A

System arguments

Examples

Slots

show_button

Optional button to open the Overlay.

NameTypeDefaultDescription
icon
String

N/A

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

controls
String

N/A

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

button_arguments
Hash

N/A

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

header

Header content.

NameTypeDefaultDescription
divider
Boolean

N/A

Show a divider between the header and body.

size
Symbol

N/A

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

visually_hide_title
Boolean

N/A

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

system_arguments
Hash

N/A

System arguments

body

Required body content.

NameTypeDefaultDescription
padding
Symbol

N/A

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

system_arguments
Hash

N/A

System arguments

footer

Footer content.

NameTypeDefaultDescription
show_divider
Boolean

N/A

Show a divider between the footer and body.

system_arguments
Hash

N/A

System arguments

Overlay::Header

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

Arguments

NameTypeDefaultDescription
title
String

N/A

Describes the content of the Overlay.

subtitle
String

nil

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

overlay_id
String

nil

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

size
Symbol

:medium

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

divider
Boolean

false

Show a divider between the header and body.

visually_hide_title
Boolean

false

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

system_arguments
Hash

N/A

System arguments

Slots

filter

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

NameTypeDefaultDescription
system_arguments
Hash

N/A

System arguments

subtitle

Optional subtitle slot for adding a subtitle to the header.

NameTypeDefaultDescription
system_arguments
Hash

N/A

System arguments

Overlay::Footer

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

Arguments

NameTypeDefaultDescription
show_divider
Boolean

false

Show a divider between the footer and body.

align_content
Symbol

DEFAULT_ALIGN_CONTENT

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

system_arguments
Hash

N/A

System arguments

Overlay::Body

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

Arguments

NameTypeDefaultDescription
system_arguments
Hash

N/A

System arguments