Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(notification): add notification code docs #1217

Merged
merged 16 commits into from
Jun 17, 2020
Merged

docs(notification): add notification code docs #1217

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
ce86ad9
docs(notification): add notification code docs
dakahn May 22, 2020
4dcb3fb
Merge branch 'master' into notification-usage-updates
dakahn May 22, 2020
ab6a7b4
docs(notification): remove skeleton anchor link
dakahn May 22, 2020
2b1a949
Merge branch 'notification-usage-updates' of github.com:dakahn/carbon…
dakahn May 22, 2020
d7547db
Merge branch 'master' of github.com:carbon-design-system/carbon-websi…
dakahn May 27, 2020
3b07773
docs(Notification): several suggested PR changes
dakahn May 27, 2020
2a4c317
Merge branch 'master' into notification-usage-updates
dakahn May 27, 2020
37f7873
fix(docs): update notification code docs
dakahn Jun 5, 2020
c6aa1a2
docs(notification): sync up the anchor links
dakahn Jun 5, 2020
07d25e3
docs(notification): fix missing anchor
dakahn Jun 9, 2020
e5e05d3
Merge branch 'master' into notification-usage-updates
joshblack Jun 10, 2020
6ec21aa
docs(notification): add overview anchor and reorder h2
dakahn Jun 10, 2020
f5ffd37
Merge branch 'notification-usage-updates' of github.com:dakahn/carbon…
dakahn Jun 10, 2020
66cf6be
Merge branch 'master' into notification-usage-updates
dakahn Jun 10, 2020
7edffa3
Merge branch 'master' into notification-usage-updates
janchild Jun 12, 2020
425a2b4
Merge branch 'master' into notification-usage-updates
joshblack Jun 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 126 additions & 59 deletions src/pages/components/notification/code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,66 +4,133 @@ description: Notifications are messages that communicate information to the user
tabs: ["Usage", "Style", "Code", "Accessibility"]
---

<ComponentDemo
components={[
{
id: "toast",
label: "Toast notification",
},
{
id: "inline",
label: "Inline notification",
},
]}
>
<ComponentVariant
id="toast"
knobs={{
ToastNotification: ["hideCloseButton", "kind", "lowContrast"],
}}
links={{
React:
"https://react.carbondesignsystem.com/?path=/story/notifications--toast",
Angular:
"https://angular.carbondesignsystem.com/?path=/story/components-notification--toast",
Vue:
"http://vue.carbondesignsystem.com/?path=/story/components-cvtoastnotification--default",
Vanilla: "https://the-carbon-components.netlify.com/?nav=notification",
}}
>{`
<div>
<ToastNotification
caption="00:00:00 AM"
iconDescription="describes the close button"
subtitle={<span>Subtitle text goes here. <a href="#example">Example link</a></span>}
timeout={0}
title="Notification title"
/>
</div>
`}</ComponentVariant>
<ComponentVariant
id="inline"
knobs={{
InlineNotification: ["hideCloseButton", "lowContrast"],
}}
links={{
React:
"https://react.carbondesignsystem.com/?path=/story/notifications--inline",
Angular:
"https://angular.carbondesignsystem.com/?path=/story/components-notification--basic",
Vue:
"http://vue.carbondesignsystem.com/?path=/story/components-cvinlinenotification--default",
Vanilla: "https://the-carbon-components.netlify.com/?nav=notification",
}}
>{`
<div>
<PageDescription>

How to build a notification using React. For code usage with other frameworks, please follow the links in the live demo on the usage tab.

</PageDescription>

<AnchorLinks>

<AnchorLink>Overview</AnchorLink>
dakahn marked this conversation as resolved.
Show resolved Hide resolved
<AnchorLink>Toast notification</AnchorLink>
<AnchorLink>Inline notification</AnchorLink>
<AnchorLink>Inline notifications with action button</AnchorLink>
<AnchorLink>Component API</AnchorLink>
<AnchorLink>Feedback</AnchorLink>

</AnchorLinks>

## Overview

Carbon Notifications come in two variants: toast, and inline. They are created by using the `ToastNotification` or `InlineNotification` components.

## Toast notification

You can use the `ToastNotification` component to display a non–modal, time–based short message that appears at the bottom or the top of the screen.

```jsx
import { ToastNotification } from "carbon-components-react";

function MyComponent() {
return (
<ToastNotification
dakahn marked this conversation as resolved.
Show resolved Hide resolved
caption="00:00:00 AM"
iconDescription="Dismiss notification"
subtitle="Notification subtitle"
timeout={0}
title="Notification title"
/>
);
}
```

## Inline notification

You can use the `InlineNotification` to notify users of the status of an action. Unlike `ToastNotification` these appear at the top of the primary content area.

```jsx
import { InlineNotification } from "carbon-components-react";

function MyComponent() {
return (
<InlineNotification
kind="info"
actions={<NotificationActionButton>Action</NotificationActionButton>}
iconDescription="describes the close button"
subtitle={<span>Subtitle text goes here. <a href="#example">Example link</a></span>}
iconDescription="Dismiss notification"
subtitle="Notification subtitle"
title="Notification title"
/>
</div>
`}</ComponentVariant>
</ComponentDemo>
);
}
```

## Inline notifications with action button

An inline notification optionally can have a ghost button that allows the user to take further action.

```jsx
dakahn marked this conversation as resolved.
Show resolved Hide resolved
import { InlineNotification } from "carbon-components-react";

function Mycomponent() {
return (
<InlineNotification
kind="info"
actions={<NotificationActionButton>Action</NotificationActionButton>}
icondescription="Dismiss notification"
subtitle="Notification subtitle"
title="notification title"
/>
);
}
```

## Component API

### Inline Notification props

| Prop | Type | Required | Default | Description |
| --------------------- | ---------- | -------- | --------------------- | ---------------------------------------------------------------------------------------- |
| actions | `node` | – | – | Pass in the action nodes that will be rendered inside the notification |
| children | `node` | – | – | Pass in the children that will be rendered inside the notification |
| className | `string` | `true` | `error` | Optional class names to be applied to the notification |
| kind | `string` | `true` | `error` | Specify what state the notification represents: `error`, `success`, `warning`, or `info` |
| lowContrast | `bool` | – | – | Specify whether you are using the low contrast variant styles |
| title | `string` | `true` | `provide a caption` | Specify notification title |
| subtitle | `node` | – | | Specify notification subtitle |
| role | `string` | – | `alert` | Provide an alternative role for the notification |
| onCloseButtonClick | `function` | – | `() => {}` | Function that is called when notification closes |
| iconDescription | `string` | `true` | `closes notification` | Provide screen reader accessible description for close icon |
| statusIconDescription | `string` | – | – | Provide screen reader accessible description for status icon |
| notificationType | `string` | – | `inline` | Specify the type of the button |
| hideCloseButton | `bool` | – | `false` | Optional prop to disable the close button |

### Notification action button props

| Prop | Type | Required | Default | Description |
| --------- | ---------- | -------- | ------- | --------------------------------------------- |
| classname | `string` | – | – | class name to be applied to the action button |
| children | `node` | – | – | the content of the notification button |
| onclick | `function` | – | – | click handler for the notification button |

### Toast notification props

| prop | type | required | default | description |
| --------------------- | ---------- | -------- | --------------------- | ------------------------------------------------------------------------------------- |
| children | `node` | – | – | Pass in the children that will be rendered inside the notification |
| className | `string` | `true` | – | Optional class names to be applied to the notification |
| kind | `string` | `true` | `error` | Specify what state the notification represents: 'error', 'info', 'success', 'warning' |
| lowContrast | `bool` | – | – | Specify whether you are using the low contrast variant styles |
| title | `string` | `true` | `provide a title` | Specify notification title |
| subtitle | `node` | – | | Specify notification subtitle |
| role | `string` | – | `alert` | Provide an alternative role for the notification |
| caption | `node` | – | `provide a caption` | The caption for the notification |
| onCloseButtonClick | `function` | – | `() => {}` | The function called when the close button is clicked |
| iconDescription | `string` | `true` | `closes notification` | Provide screen reader accessible description for close icon |
| statusIconDescription | `string` | – | – | Provide screen reader accessible description for status icon |
| notificationType | `string` | – | `toast` | The type of notification |
| hideCloseButton | `bool` | – | `false` | Optional prop to disable the close button |
| timeout | `number` | – | `0` | Time until the notification is closed |

## Feedback

Help us improve this component by providing feedback, asking questions, and leaving any other comments on [GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).