@element-public/react-banner

v1.0.0

Published

4 months ago

Banner component for Element React

Downloads

0High
0Medium
0Low

peon125

slowikowskiarkadiusz

arkadiusz.slowikowski

Banner

Description

A banner displays a prominent message and related optional actions.

See live demos on storybook

Storybook Banner Demos

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