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

NameDefaultDescription
id

self.class.generate_id

String

The id of the Overlay.

title

N/A

String

Describes the content of the Overlay.

subtitle

nil

String

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

popover

:auto

Symbol

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

size

:auto

Symbol

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

padding

:normal

Symbol

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

anchor

nil

String

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

anchor_align

:start

Symbol

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

anchor_side

:outside_bottom

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

:normal

Symbol

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

allow_out_of_bounds

false

Boolean

Allow the Overlay to overflow its container.

visually_hide_title

false

Boolean

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

role

nil

String

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

system_arguments

N/A

Hash

System arguments

Examples

Slots

show_button

Optional button to open the Overlay.

NameDefaultDescription
icon

N/A

String

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

controls

N/A

String

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

button_arguments

N/A

Hash

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

header

Header content.

NameDefaultDescription
divider

N/A

Boolean

Show a divider between the header and body.

size

N/A

Symbol

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

visually_hide_title

N/A

Boolean

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

system_arguments

N/A

Hash

System arguments

body

Required body content.

NameDefaultDescription
padding

N/A

Symbol

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

system_arguments

N/A

Hash

System arguments

footer

Footer content.

NameDefaultDescription
show_divider

N/A

Boolean

Show a divider between the footer and body.

system_arguments

N/A

Hash

System arguments

Overlay::Header

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

Arguments

NameDefaultDescription
title

N/A

String

Describes the content of the Overlay.

subtitle

nil

String

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

overlay_id

nil

String

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

size

:medium

Symbol

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

divider

false

Boolean

Show a divider between the header and body.

visually_hide_title

false

Boolean

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

system_arguments

N/A

Hash

System arguments

Slots

filter

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

NameDefaultDescription
system_arguments

N/A

Hash

System arguments

Overlay::Footer

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

Arguments

NameDefaultDescription
show_divider

false

Boolean

Show a divider between the footer and body.

align_content

DEFAULT_ALIGN_CONTENT

Symbol

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

system_arguments

N/A

Hash

System arguments

Overlay::Body

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

Arguments

NameDefaultDescription
system_arguments

N/A

Hash

System arguments