Skip to content

Latest commit

 

History

History
65 lines (56 loc) · 6.6 KB

Modal.md

File metadata and controls

65 lines (56 loc) · 6.6 KB
Raw

Modal

The Modal component is designed to block out the screen and focus the user on the content inside the Modal.

It provides only the backdrop and a scrollable container for your content. If your content should have a background color, be sure to add it yourself.

Any time the Modal is in the DOM, it will take over the screen. You make it go away by removing it from the DOM.

Example Usage

<script>
  let showMyModal = false
</script>
<button on:click={() => showMyModal = true}>Show Modal</button>
{#if showMyModal}
  <Modal on:escape={() => showMyModal = false}>
    This is a modal dialog!
  </Modal>
{/if}
<style>
  :global(.modal-container) { background: white; }
</style>

Custom Events

  • on:escape - dispatched when the user does something that would normally dismiss a modal, such as clicking in the darkened backdrop or pressing the Escape key. You should listen for this and dismiss your modal. If you do not listen for this event, users will only be able to escape by some other means provided within your content. Be careful not to trap them!

Props

  • opaque: boolean (default false) - Make the backdrop completely opaque so that it cannot be seen through. This is a more jarring experience for users but sometimes you don't want background content to be visible at all.
  • containerClass: string (default '') - A class to be added to the scrollable container inside the backdrop. This container will always have the .modal-container class regardless of this prop.
  • escapable: boolean (default true) - Let screen readers know that they can escape the modal by pressing the Escape key. If you are not listening for on:escape then you should set this false to avoid giving screen reader users false information.
  • hidefocus: boolean (default true) - Focus must be moved to the modal when it opens, in order to maintain accessibility. This component avoids making the focus visible to users by default as it might be visually disconcerting. So on mount, focus is moved to an invisible element above your content. If you prefer focus to be visible to users, set this to false and focus will automatically be moved to the first element in your content that has a tabindex and therefore be visible to users. This prop is overridden if you provide an initialfocus.
  • hidefocuslabel: string|undefined (default focus is above modal dialog, start tabbing) - The message that will be read out to users using a screen reader when the focus is on the invisible element created by the hidefocus prop.
  • initialfocus: string|undefined (default undefined) - A selector to be used to locate and set focus on an element in your content, on mount. Use if you want focus on a specific element when the modal opens. Overrides hidefocus.
  • returnfocusto: HTMLElement|undefined (default element that had focus was when modal opened) - Use to control where focus moves when the modal closes. If not provided, component automatically saves the element that had focus on mount. Usually it's the button that triggered the modal.
  • usePortal: HTMLElement|undefined (default undefined) - An optional bind for specifying the HTMLElement to use with the portal action.
  • includeselector: string|undefined (default undefined)