A modal is a window that overlays over the main window to give the user a task to complete before moving forward. There are two variants, simple modal or media modal. Modals are used for desktop interactions only. If you need to involve additional components like text fields then use a side sheet. For mobile native, use a partial bottom sheet.



The user may click the scrim for it to close the modal which will take them back to where they were before but it can be locked down if the user is required to take action.

Simple Modal

Use a simple modal when you need to do a quick confirmation task that is usually a yes or no question.

  1. Avatar - Medium (Optional)
  2. Heading - Small heading 
  3. Slot (Optional)
  4. Buttons - Medium and high emphasis (Up to 2, minimum 1 button at high emphasis)
  5. Container (Min 272px width)
  6. Scrim 

Fixed header

If the content within the body becomes too long, the body container will scroll independently from the header and footer. The header will be fixed to the top of the modal once the modal hits the max height of 600px. A divider will show for the header once the content scrolls behind it.

  1. Divider

Fixed footer

The footer will be fixed to the bottom of the modal once the modal hits the max height of 600px. The divider will go away once at the bottom of the content. 

  1. Divider

Media Modal

Use a media modal when needing to enlarge some type of media like photos or videos. Note: If there are no buttons then the X at the top right will show but if there are buttons, then the X is not showing. 

  1. Heading - Small Heading (Optional)
  2. Body paragraph - Body 1 (Optional)
  3. Slot 
  4. Close - Small No Emphasis Quick Action Button 
  5. Container (Min width 272px and max width of 700px)
  6. Scrim
  7. Buttons - Up to 2 (Optional)



Element Property Values
Avatar Icon color Defined by design
Heading Textt color ∆colorPlatformGray900
Body Text color ∆colorPlatformGray900
Scrim (Browser) Background color ∆colorPlatformGray900
Scrim (Side Sheet) Background color ∆colorPlatformGray900


Element Property Value
Surface Shadow Y offset ∆surfacePlatformRaisedShadowY
Surface Shadow opacity ∆surfacePlatformRaisedShadowOpacity
Surface Shadow spread ∆surfacePlatformRaisedShadowSpread
Surface (static) Shadow blur ∆surfacePlatformRaisedShadowBlurResting
Surface (hover) Shadow blur ∆surfacePlatformRaisedShadowBlurLifted
Surface (pressed/active) Shadow blur ∆surfacePlatformRaisedShadowBlurPressed
Surface (dragged) Shadow blur ∆surfacePlatformRaisedShadowBlurLifted



The content within the modal is center aligned. With two buttons, they will fill the container width but with one button it will be center aligned.

Content wrapping

The heading should be short and easy to read. The header text can wrap but recommend up to two lines of text. If you need to relay more information, put it in the body paragraph. The body paragraph can get long if necessary and will become scrollable once it hits a 40px margin at the bottom of the browser.


Buttons can have up to two buttons with a minimum of one button. If the action calls for only one button, use the high emphasis button. Side by side buttons will fill the width of the container in the simple modal but when down to one button, will be the regular width. If the container becomes too small depending on the size of the screen or length of the button CTA, the buttons will stack. 


No new states to consider for modal. 



Element Shape category Value
Container Large component ∆shapeBrandedLarge


Desktop placement

Modal is vertically centered within the browser window or sidesheet and the user cannot scroll the page while the modal is open. Desktop screen margin padding is 40px.

Tablet placement

The modal is vertically centered within the tablet view and the user cannot scroll the view while the modal is open. Tablet screen margin padding is 24px.

Mobile placement

The modal will open up inside of a partial bottom sheet on smaller screens. See this documentation for the breakpoints.

Vertical height 

The modal will get taller the more the content is inside of the body paragraph but will start to scroll within the body once it meets max height of 600px.

Side sheet

A modal can be used within a side sheet and be used to prompt a user when necessary. For example, when you try to exit the side sheet without saving any changes. 


Modal entrance

Interaction Steps Duration Easing Notes Haptics
Enterance 1a. Scrim fades in from 0-100% ∆motionTimeFast ∆motionTimingFunctionStandard    
  1b. Modal fades in from 0-100% ∆motionTimeFast ∆motionTimingFunctionStandard    
  1c. Slides down ∆motionTimeFast ∆motionTimingFunctionStandard Moves into designed centered position  

Modal exit

Interaction Steps Duration Easing Notes Haptics
Exit 1a. Slides up ∆motionTimeFast ∆motionTimingFunctionStandard Moves up and out of position  
  1b. Modal fades in from 0-100% ∆motionTimeFast ∆motionTimingFunctionStandard    
  1c. Scrim fades in from 0-100% ∆motionTimeFast ∆motionTimingFunctionStandard    

Developer Docs

Vue Developer Docs

Component documentation coming soon!