@element-public/react-banner NPM

Banner

Description

A banner displays a prominent message and related optional actions.

See live demos on storybook

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-banner @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

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 login

Setup 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=

Notes

Banners should be displayed at the top of the screen, below a top app bar. They’re persistent and nonmodal, allowing the user to either ignore them or interact with them at any time. Only one banner should be shown at a time.

Component	Priority	User action
Snackbar	Low priority	Optional: Snackbars disappear automatically
Banner	Prominent, medium priority	Optional: Banners remain until dismissed by the user, or if the state that caused the banner is resolved
Dialog	Highest priority	Required: Dialogs block app usage until the user takes a dialog action or exits the dialog (if available)

Accessibility Considerations

The context and content surrounding banner will determine the type of ARIA and accessibility concerns that should be maintained. In the spirit of keeping our Banner component light, no specific accessibility concerns have been addressed outside of semantic markup.

Each product and application will be different. To decide how best to support users with Banner, consider some of the following questions:

Will Banner load into view, or will it potentially show up dynamically and need to be announced?
Will Banner be tied to another control or content piece on the page? What other content might Banner be labeling?
Will Banner's content change over time? Or will it be removed from the DOM each time as content changes?

In some ways, Banner could act as a notification, a label, an aside, error/form feedback, or as a live-region content announcement. In many instances, Banner will likely be acting as a notification.

For further reading into creating inclusive, usable, and accessible components consider the following while developing Banner solutions:

Banner CSS Custom Props

Banner comes with one CSS custom property for easy styling access.

:root {
    --lmnt-banner-max-width-content: 100%;
}

Name	Type	Default	Description
--lmnt-banner-max-width-content	`max-width`	100%	Set the Banner content `max-width` and center the contents inside of Banner. Defaults to 100%.

Banner Props

Name	Type	Default	Required	Description
airy	boolean	null	false	Indicates that the banner should have more white-space padding than default.
className	string	undefined	false	The css class name to be passed through to the component markup.
customTopAppBarHeight	string	null	false	If using a custom top app bar with banner, you will have to send in the height of the custom top app bar so the banner positions correctly, ie 55px. You will be responsible for making sure the page content aligns properly upon opening and closing the Banner. The Banner Margin Fix component allows you to wrap the content and send in the margin top or you can use a custom component.
drawer	boolean	null	false	Indicates that the banner will be used with an Element Drawer.
elevated	boolean	null	false	Indicates that the banner should have box-shadow and elevation styles. Should be used when banner is fixed. Flat style by default.
fixed	boolean	null	false	Indicates that the banner will be in a fixed position.
open	boolean	true	false	Indicates that the banner should be open. Open by default. Animates between states with transition CSS.
primaryButtonDismissive	boolean	true	false	If true clicking on the primary button will dismiss the banner. At least one button must dismiss the banner. If both primary and secondary buttons are marked as not dismissive, the primary button will default to dismissive.
primaryButtonLabel	string	'Ok'	false	Banner primary button label text.
secondaryButtonDismissive	boolean	true	false	If true clicking on the secondary button will dismiss the banner. At least one button must dismiss the banner. If both secondary and secondary buttons are marked as not dismissive, the primary button will default to dismissive.
secondaryButtonLabel	string	null	false	Banner action button label text.
surfaceVariant	boolean	null	false	Indicates that the banner background-color should use Element's 'surface variant' color. Uses 'surface' by default.
topAppBar	boolean	null	false	Indicates that the banner will be used with an Element Top App Bar.
topAppBarVariant	string	'fixed'	false	Indicates which type of Element Top App Bar Banner will be used with.Accepted Values: fixed, relative, dense, prominent, dense-prominent, dense-fixed, prominent-fixed, dense-prominent-fixed

Banner Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	true	Content to be rendered inside the banner. Accepts any valid markup.
media	React.ReactNode	null	false	Banner media slot can hold an image, icon, or other media. (40x40).

Banner Events

Name	Default	Required	Params	Description
onClosed	null	false	1. Name: reason, Type: string, Description: Reason for closing. ie. Primary Action or Secondary Action.,2. Name: event, Type: object, Description: The javascript event	Fired when the banner finishes its closing animation.
onClosing	null	false	1. Name: reason, Type: string, Description: Reason for closing. ie. Primary Action or Secondary Action.,2. Name: event, Type: object, Description: The javascript event	Fired when the banner begins its closing animation.
onOpened	null	false	1. Name: event, Type: object, Description: The javascript event	Fired when the banner finishes its opened animation.
onOpening	null	false	1. Name: event, Type: object, Description: The javascript event	Fired when the banner begins its MDCBanner:opening animation.
onPrimaryClicked	null	false	1. Name: event, Type: object, Description: The javascript event	Fired when the Primary Action Button is clicked. Runs after closing animation begins.
onSecondaryClicked	null	false	1. Name: event, Type: object, Description: The javascript event	Fired when the Secondary Action Button is clicked. Runs after closing animation begins.

Banner Margin Fix Props

Name	Type	Default	Required	Description
bannerId	string	undefined	false	If supplied, the adjusted margin will attempt to be automatically calculated.
bannerOpen	boolean	false	false	Apply the adjusted left margin.
className	string	undefined	false	The css class name to be passed through to the component markup.
extraMargin	number	24	false	The spacing between the bottom of the banner and the top of the content being adjusted.
marginTop	number	0	false	Custom margin.
style	object	null	false	Passthrough style object.

Banner Margin Fix Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Content to be vertically adjusted. Accepts any valid markup.

clsx prop-types @material/banner @babel/runtime-corejs3

@element-public/react-components

1.0.0

1 year ago