@element-public/react-bottom-sheet v1.0.0
BottomSheet
Description
Bottom sheets are surfaces containing supplementary content that are anchored to the bottom of the screen.
See live demos on storybook
Install bundle from npm-e
npm i @element-public/react-components @element-public/themesOptional: install the component individually
npm i @element-public/react-bottom-sheet @element-public/themesOpen ~/.npmrc in an editor and add the following line to enable the @element-public
scope:
@element-public:registry=https://npm.platforms.engineeringTroubleshooting
See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:
npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR! npm loginSetup an access token
See the
devtools npm-e guide
to learn how to create an access token if this is the first time you are using a
npm-e package at Bayer or you do not have a line that starts with the following
in your ~/.npmrc file:
//npm.platforms.engineering/:_authToken=
this file was copied over from sideSheet, change before merging
Variants
All variants of BottomSheet behave and look like the modal variant at smaller
screen sizes.
The elevated and coplanar variants requires a parent wrapper context for
layout.
All BottomSheet require a container context, which can typically be <body> in
most instances.
Accessibility Concerns
To keep the user-experience for BottomSheet as accessible as possible, it
strives to do the following when BottomSheet is at small-screen size and
always during the modal variant:
- On Bottom Sheet open, set focus on the Bottom Sheet Dismiss button
- On Bottom Sheet close, return focus to the last focused element
- While open, prevent mouse clicks outbottom the bottom sheet
- While open, prevent tabbing to outbottom the Bottom Sheet
- Allow the ESC Key to close the Bottom Sheet
It is important that upon closing the BottomSheetReturnFocus event be
listened for and return focus managed appropriately in the surrounding
application context.
Props
BottomSheet
The BottomSheetWrapper component is necessary for the elevated or
coplanar variants.
Example pseudo-code:
<body>
<header></header>
<BottomSheetWrapper variant='elevated'>
<main></main>
<BottomSheet variant='elevated'></BottomSheet>
</BottomSheetWrapper>
<footer></footer>
</body>The BottomSheetWrapper component can be omitted entirely for modal and
floating variants.
Example pseudo-code:
<body>
<header></header>
<main></main>
<BottomSheet></BottomSheet>
<footer></footer>
</body>BottomSheetContainer
The BottomSheetContainer component is used as a substitute for a typical
<body> context. It is required when attachContainerClassesToBody is set
to false on BottomSheet.
The main responsibility of BottomSheetContainer is to control scrolling when the
background content is obscured by modal content. This happens at all
small-screen sizes for all variants and for the modal variant at all screen
sizes.
<body>
<BottomSheetContainer>
<header></header>
<BottomSheetWrapper variant='coplanar'>
<main></main>
<BottomSheet variant='coplanar'></BottomSheet>
</BottomSheetWrapper>
<footer></footer>
</BottomSheetContainer>
</body>Further Reading
Bottom Sheet behaves like a typical modal component at small-screen sizes, and
always when in the modal variant.
- https://material.io/components/sheets-bottom
- https://bitsofco.de/accessible-modal-dialog/
- http://web-accessibility.carnegiemuseums.org/code/dialogs/
- https://www.smashingmagazine.com/2014/09/making-modal-windows-better-for-everyone/
- https://hiddedevries.nl/en/blog/2017-01-29-using-javascript-to-trap-focus-in-an-element
Bottom Sheet Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| allowOutsideClick | boolean | true | false | Set to false to stop Bottom Sheet from closing when scrim is clicked when the variant is modal. |
| attachContainerClassesToBody | boolean | true | false | Add classes to body for when bottom-sheet-container is not present in DOM. |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| detent | string | 'full-height' | false | The detent in which the sheet should be in when opened. Available values: 'full-height' or 'content-height', from React Modal Sheet. |
| disableDrag | boolean | false | false | Disable drag for the whole sheet, from React Modal Sheet. |
| disableScrollLocking | boolean | false | false | Disable's scroll locking for the documents body element while sheet is opened. Can be useful if you face issues with input elements and the iOS software keyboard, from React Modal Sheet. |
| headlineText | string | null | false | The text to be displayed along bottom the dismiss button in BottomSheet. |
| initialSnap | number | 0 | false | Initial snap point when sheet is opened (index from snapPoints), from React Modal Sheet. |
| mountPoint | object | undefined | false | HTML element that should be used as the mount point for the sheet, from React Modal Sheet. |
| open | boolean | undefined | false | Make the BottomSheet visible using the experience set in variant prop. |
| prefersReducedMotion | boolean | false | false | Skip sheet animations (sheet instantly snaps to desired location), from React Modal Sheet. |
| returnFocusSelector | string | '.lmnt-bottom-sheet-trigger' | false | DOM selector to provide a target to return focus. Accepts any valid query (see mdn docs for Element.querySelector). If omitted focus will return to the last focused element upon closing. |
| rootId | string | null | false | The id of the element where the main app is mounted, eg. 'root'. Enables iOS modal effect, from React Modal Sheet. |
| snapPoints | number | null | false | Eg. -50, 0.5, 100, 0 - where positive values are pixels from the bottom of the screen and negative from the top. Values between 0-1 represent percentages, eg. 0.5 means 50% of window height from the bottom of the sceen, from React Modal Sheet. |
| tweenConfig | object | { ease: 'easeOut', duration: 0.2 } | false | Overrides the config for the sheet tween transition when the sheet is opened, closed, or snapped to a point, from React Modal Sheet. |
| variant | string | 'modal' | false | The behavior styles available to bottom sheet: one of modal, floating, elevated, or coplanar.Accepted Values: modal, elevated, floating, coplanar |
Bottom Sheet Render Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| children | React.ReactNode | null | false | Primary content. Accepts any valid markup. |
Bottom Sheet Events
| Name | Default | Required | Params | Description |
|---|---|---|---|---|
| onClose | null | false | A provided function to fire when Bottom Sheet becomes hidden. | |
| onCloseEnd | null | false | Callback fn that is called when the sheet closing animation is completed, from React Modal Sheet. | |
| onCloseStart | null | false | Callback fn that is called when the sheet closing animation starts, from React Modal Sheet. | |
| onOpenEnd | null | false | Callback fn that is called when the sheet opening animation is completed, from React Modal Sheet. | |
| onOpenStart | null | false | Callback fn that is called when the sheet opening animation starts, from React Modal Sheet. | |
| onSnap | null | false | Callback fn that is called with the current snap point index when the sheet snaps to a new snap point. Requires snapPoints prop, from React Modal Sheet. |
Bottom Sheet Content Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| scrollable | boolean | false | false | If true, the content will be scrollable. |
Bottom Sheet Content Render Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| children | React.ReactNode | null | false | Primary content. Accepts any valid markup. |
Bottom Sheet Header Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| className | string | undefined | false | The css class name to be passed through to the component markup. |
Bottom Sheet Header Render Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| children | React.ReactNode | null | false | Primary content. Accepts any valid markup. |
Bottom Sheet Scroller Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| className | string | undefined | false | The css class name to be passed through to the component markup. |
Bottom Sheet Scroller Render Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| children | React.ReactNode | null | false | Primary content. Accepts any valid markup. |
1 year ago