# UI Components The first thing you need to know is that websites **need to obtain an opt-in** from their visitors to send them push notifications. Choosing the right format and the right moment to ask for push notification permission is key to build a successful web push strategy. There are several formats to choose from, each one adapted to different needs: * [**Alert**](#alert): a customizable popup. * [**Banner**](#banner): a simple banner. * [**Button**](#button): a button you can display in the bottom right or left corner of your website. * [**Native prompt**](#native-prompt): The native prompt, in case you don't want to use any of the above formats *(fully secure mode only)*. UI Components (except for `popup`) are automatically added to your web page once you configure them. Configuring a UI component allows you to override its behaviour, position or even translations. We'll detail what configuration options are supported for every builtin UI Component. For example, here's how a button would work in the configuration: ```js batchSDK(['setup', { ... ui: { button: { corner: 'bottom left', backgroundColor: '#FFFFFF', hover: 'Subscribe to our notifications!', } } }); ``` {% hint style="info" %} When in fully secure mode, you have the possibility of asking for the browser's notification optin directly. A UI Component is **required** for the HTTP/Multidomain mode, as a click event is required to open a popup without it being caught by browser's builtin blockers. {% endhint %} ### Alert *** ![Alert screenshot](https://38998153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCL8wF0y1T2vLnm3yR2MW%2Fuploads%2FHKOXVi2Oo0Eoyaf3kt3X%2Falert.png?alt=media\&token=5eb2f8ab-6cf7-4b00-9ef5-555f12544b56) *Requires Batch SDK 2.0.0* The alert format is similar to popups you can get using `alert()`. It is not *actually* modal: the user is still able to interact with the content around it. It can show up in any of the four corners, or can be centered on the top or the bottom of the page. To enable it, add a child object of `ui` named `alert`. Supported parameters:
IdDescription
autoShowBoolean - Optional
Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true
E.g.{"autoShow":false}
attachString - Optional
Where to attach the alert. Should be a mix of top|bottom and left|center|right.
E.g.{"attach":"bottom left"}
iconURL String - Optional
Link to a square icon representing your website, which will show up on the left of the banner. The file must be a PNG or JPG image hosted on an HTTPS server.
E.g.{"icon":"https://mydomain.com/icon.png"}
textString - Optional
Overrides the text that's displayed in the banner.
E.g.{"text":"Never miss an update !"}
backgroundColorHex Color String - Optional
Color of the banner's background.
E.g.{"backgroundColor":"#646464"}
textColorHex Color String - Optional
Color of the banner's text.
E.g.{"textColor":"#646464"}
fontSizeInteger - Optional
Font size. Unitless.
E.g.{"fontSize":"12"}
fontFamilyString - Optional
Overrides the font used in the banner. Works exactly like CSS' font-family attribute.
E.g.{"fontFamily":"helvetica"}
btnBackgroundColorHex Color String - Optional
Color of the button's background.
E.g.{"btnBackgroundColor":"#646464"}
btnTextColorHex Color String - Optional
Color of the button's text.
E.g.{"btnTextColor":"#646464"}
btnHoverColorHex Color String - Optional
Color of the button's hover state.
E.g.{"btnHoverColor":"#646464"}
btnFontSizeInteger - Optional
Font size of both buttons in px. Do not add the unit to the value.
E.g.{"btnFontSize":"12"}
positiveSubBtnLabelString - Optional
Text override for when the positive button will subscribe the user.
E.g.{"positiveSubBtnLabel":"Subscribe"}
positiveUnsubBtnLabelString - Optional
Text override for when the positive button will unsubscribe the user.
E.g.{"positiveUnsubBtnLabel":"Unsubscribe"}
negativeBtnLabelString - Optional
Text override for when the negative button, which hides for popup temporarily, until the delay in `hideFor` has been reached.
E.g.{"negativeBtnLabel":"Later"}
positiveBtnStyleButton style configuration - Optional
Style configuration for the positive ("Subscribe"/"Unsubscribe") button. See below for more info about this object. Note: When in unsubcribe mode, this button will always have a red background color.
E.g.{"positiveBtnStyle":{"textColor":"red"}}
negativeBtnStyleButton style configuration - Optional
Style configuration for the negative ("Later") button. See below for more info about this object.
E.g.{"negativeBtnStyle":{"textColor":"red"}}
extraBtn'Extra' button configuration. Requires SDK v3. - Optional
Both 'label' (Button text) and 'link' (link that will be opened in a new tab on click) attributes are required. A 'style' object can be provided in the same syntax as 'positive/negativeBtnStyle', CSS styling is also supported.
E.g.{"extraBtn":{"label":"Privacy Policy","link":"https://batch.com/privacy-policy"}}
hideForInteger - Optional
When closed, do not display the banner again until X seconds elapsed (default: 604800 or 7 days). Use a 0 value to hide the alert forever.
E.g.{"hideFor":604800}
zIndexInteger - Optional
z-index of the component
E.g.{"zIndex":999}
#### Alert button style configuration
IdDescription
backgroundColorHex Color String - Optional
Color of the button's background.
E.g.{"backgroundColor":"#646464"}
hoverBackgroundColorHex Color String - Optional
Color of the button's background when hovered. Falls back on `backgroundColor` if not specified.
E.g.{"hoverBackgroundColor":"#646464"}
textColorHex Color String - Optional
Color of the banner's text.
E.g.{"textColor":"#646464"}
fontSizeInteger - Optional
Font size in px. Do not specify an unit in this value.
E.g.{"fontSize":"12"}
shadowBoolean - Optional
Whether this button should cast a shadow, or not. Default: true for the positive button, false for the negative one.
E.g.{"shadow":false}
Example: ```javascript alert: { positiveBtnStyle: { backgroundColor: "blue", textColor: "white", fontSize: 25, shadow: true } } ``` ### Banner *** ![Banner screenshot](https://38998153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCL8wF0y1T2vLnm3yR2MW%2Fuploads%2F47Al2uYeT81m6KSsl5m3%2Fbanner.png?alt=media\&token=686cc0cb-1084-4605-98db-a201dd9e7a17) The banner shows up at the top of your webpage. It has an optional logo, a colorable button, and can be floating or fixed. To enable it, add a child object of `ui` named `banner`. Supported parameters:
IdDescription
autoShowBoolean - Optional
Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true
E.g.{"autoShow":false}
iconURL String - Optional
Link to a square icon representing your website, which will show up on the left of the banner. The file must be a PNG or JPG image hosted on an HTTPS server.
E.g.{"icon":"https://mydomain.com/icon.png"}
textString - Optional
Overrides the text that's displayed in the banner.
E.g.{"text":"Never miss an update !"}
fixedBoolean - Optional
Makes the banner push the webpage's content rather than float on top of it (default: False).
E.g.{"fixed":true}
attachBottomBoolean - Optional
Makes the banner show on the bottom of the page, rather than on top. Forces 'fixed' to true (default: False).
E.g.{"attachBottom":true}
backgroundColorHex Color String - Optional
Color of the banner's background.
E.g.{"backgroundColor":"#646464"}
textColorHex Color String - Optional
Color of the banner's text.
E.g.{"textColor":"#646464"}
fontSizeInteger - Optional
Font size. Unitless.
E.g.{"fontSize":"12"}
fontFamilyString - Optional
Overrides the font used in the banner. Works exactly like CSS' font-family attribute.
E.g.{"fontFamily":"helvetica"}
btnBackgroundColorHex Color String - Optional
Color of the button's background.
E.g.{"btnBackgroundColor":"#646464"}
btnTextColorHex Color String - Optional
Color of the button's text.
E.g.{"btnTextColor":"#646464"}
btnHoverColorHex Color String - Optional
Color of the button's hover state.
E.g.{"btnHoverColor":"#646464"}
btnFontSizeInteger - Optional
Button's font size. Unitless.
E.g.{"btnFontSize":"12"}
btnWidthInteger - Optional
Button width. Unitless.
E.g.{"btnWidth":"200"}
btnSubString - Optional
Text override for when the button will subscribe the user.
E.g.{"btnSub":"Subscribe"}
btnUnsubString - Optional
Text override for when the button will unsubscribe the user.
E.g.{"btnUnsub":"Unsubscribe"}
hideForInteger - Optional
When closed, do not display the banner again until X seconds elapsed (default: 604800 or 7 days). Use a 0 value to hide the banner forever.
E.g.{"hideFor":604800}
zIndexInteger - Optional
z-index of the component
E.g.{"zIndex":999}
### Button *** ![Button screenshot](https://38998153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCL8wF0y1T2vLnm3yR2MW%2Fuploads%2F2M8jMlksO1tT5gpt31Uu%2Fpopin_vestiaire%402x.png?alt=media\&token=8a2dd942-7303-4c27-8884-6ee20ca2ba1a) The `Button` UI Component shows a simple bell icon in the corner you want which, once clicked, show a pop-in with a customizable opt-in text, and a button to enable notifications. To enable it, add a child object of `ui` named `button`. Supported parameters: | Id | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `autoShow` |

Boolean - Optional
Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true
E.g.{"autoShow":false}

| | `corner` |

String - Optional
Corner to display the button in. Should be a mix of top

| | `hover` |

String - Optional
Override the text that appears when hovering the button.
E.g.{"hover":"Never miss an update !"}

| | `backgroundColor` |

Hex Color String - Optional
Color of the button's background.
E.g.{"backgroundColor":"#646464"}

| | `foregroundColor` |

Hex Color String - Optional
Color of the button's glyph.
E.g.{"foregroundColor":"#646464"}

| | `hoverColor` |

Hex Color String - Optional
Color of the button's background on hover.
E.g.{"hoverColor":"#646464"}

| | `hoverForegroundColor` |

Hex Color String - Optional
Color of the button's glyph on hover.
E.g.{"hoverForegroundColor":"#646464"}

| | `popin` |

Object - Optional
Overrides the popin's properties.

| | | | | `title` |

String - Optional
Override the pop-in's title.
E.g.{"title":"Subscribe to notifications"}

| | `btnSub` |

String - Optional
Overrides the pop-in subscribe button text.
E.g.{"btnSub":"Subscribe"}

| | `btnUnsub` |

String - Optional
Overrides the pop-in unsubscribe button text.
E.g.{"btnUnsub":"Unsubscribe"}

| | `example` |

Object - Optional
Example notification to display instead of the placeholder. See 'Theming' for more info.
E.g.{"example":{"body":"This is what a notification looks like"}}

| | `title` |

String - Optional
Override the pop-in's title.
E.g.{"title":"Subscribe to notifications"}

| | `btnSub` |

String - Optional
Overrides the pop-in subscribe button text.
E.g.{"btnSub":"Subscribe"}

| | `btnUnsub` |

String - Optional
Overrides the pop-in unsubscribe button text.
E.g.{"btnUnsub":"Unsubscribe"}

| | `example` |

Object - Optional
Example notification to display instead of the placeholder. See 'Theming' for more info.
E.g.{"example":{"body":"This is what a notification looks like"}}

| | `zIndex` |

Integer - Optional
z-index of the component
E.g.{"zIndex":999}

| #### Theming The button theme supports full color customization of the button itself, but not the popin. Just like any other component attribute, just override the wanted value in the configuration object. Here's what colors you can change on the button, with their property names:
You can also customize the placeholder notification in the popin, by specifying a `example` object under `popin`:
IdDescription
iconImage URL String - Optional
URL of the image to display on the left of the example notification.
E.g.{"icon":"https://path/to/your/image.jpg"}
titleString - Required
Notification title text.
E.g.{"title":"Test title"}
bodyString - Required
Notification body text.
E.g.{"body":"Test body"}
Example: ```javascript button: { corner: 'bottom left', popin: { example: { icon: 'https://path/to/your/icon.jpg', title: 'Test title', body: 'Test body' } } } ``` ### Native prompt ![Native prompt screenshot](https://38998153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCL8wF0y1T2vLnm3yR2MW%2Fuploads%2F1Y5j3Ueb58KPv22Zi8A9%2Fnativeprompt.png?alt=media\&token=3ee79222-25df-48df-a167-589dcf2bd877) In case you don't want to use Batch's formats, you can trigger the native prompt of each browser. That permission request can be shown 3 times a week (more information [here](https://www.chromestatus.com/features/6443143280984064)). Please note this will only work if you are using the **fully secure mode**. To enable it, add a child object of `ui` named `native`. Supported parameters:
IdDescription
autoShowBoolean - Optional
Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true
E.g.{"autoShow":false}
backoffDurationInteger - Optional
Time, in seconds. Allows you to set a delay between each display of the native prompt. Default: 86400
E.g.{"backoffDuration":86400}
Example: ```javascript native: { "backoffDuration": 86400 } ``` ### Toggling visibility programmatically Starting with Batch SDK 2.0.0, you can programatically control the display of builtin UI components. Two methods are available on the public API: ui.show, and ui.hide. They take as a parameter the name of a UI component that has been configured earlier, in the SDK setup: ```js batchSDK('ui.show', 'alert') batchSDK('ui.hide', 'alert') // or batchSDK((api) => { api.ui.show('alert') }) batchSDK((api) => { api.ui.hide('alert') }) ``` {% hint style="info" %} Most components will be shown as soon as possible. In order to make them wait for your `show` call, please refer to the configuration of the UI component you're trying to tweak: look for the `autoShow` key. {% endhint %} Note that some UI components might chose not to display even if you tell them to. Reasons can be: * The user is already subscribed to notifications * The user dismissed the UI element, and the minimum time between two dismissal (controlled by the `hideFor` configuration key) has not been reached. In these cases, you can use the second "force" parameter, which allows you to force the display: ```js batchSDK('ui.show', 'alert', true) ```