+ The EuiCommentList is a timeline component built on top
+ of{' '}
+
+ EuiTimeline
+
+ . It allows you to display comments or logging actions that either a
+ user or a system has performed.
+
+
+
+ For accessibility, it is highly recommended to provide a descriptive{' '}
+ aria-label, or a text node ID of an external
+ label to the aria-labelledby prop of the{' '}
+ EuiCommentList.
+
+ }
+ />
+
+ ),
sections: [
{
+ title: 'Basic comment list',
source: [
{
type: GuideSectionTypes.JS,
@@ -94,100 +122,140 @@ export const CommentListExample = {
demo: ,
},
{
- title: 'Comment',
source: [
{
type: GuideSectionTypes.JS,
- code: commentSource,
+ code: commentFlexibleSource,
},
],
+ title: 'Comment',
text: (
-
-
- Use EuiComment to display comments. Each{' '}
- EuiComment has two parts: a{' '}
- timelineIcon on the left and content on the
- right. The timelineIcon provides a visual
- indication of the type of comment it is. For
- example, it can be an icon that represents what action was performed
- or it can be a user avatar. The content has a header with all the
- relevant metadata and a body.
-
-
+ <>
+
+
+ The EuiComment is flexible and adapts the design
+ according to the props passed.
+
+
+
+
+
+
+
+
+ avatar: Shows an avatar that should indicate
+ who is the author of the comment. By default, the avatar show
+ initials that are generated from the username{' '}
+ prop. When no username is passed, you can
+ define an avatar by using the avatarName and{' '}
+ avatarIcon props.
+
+
+ eventIcon: Icon that shows before the
+ username. Use in conjunction with{' '}
+ eventIconAriaLabel to pass an aria label to
+ the event icon.
+
+
+ username: Author of the comment.
+
+
+ event: Shows inside a badge denoting what
+ type of event it is. Use in conjunction with{' '}
+ severity and badgeColor to
+ indicate the level of urgency.
+
+
+ timestamp: Time of occurrence of the event.
+
+
+ actions: Custom actions that the user can
+ perform from the comment's header. When having multiple
+ actions, consider grouping them in a nested menu system using a{' '}
+
+ EuiPopover
+ {' '}
+ with a{' '}
+
+ EuiContextMenu
+
+
+
+ children: Use this prop to pass a user
+ message or any custom component.
+
+
+
+
+
+
+ The following demo shows how you can combine different props to
+ create different types of comments events like a regular, update,
+ update with a danger background and a custom one.
+
- The default type of comment is
- regular and displays a comment that a user has
- written.
-
-
- Change the type to update to display comments
- that generally do not have a body and are logging actions that
- either the user or the system has performed (e.g. “jsmith
- edited a case” or “kibanamachine added the review
- label”).
-
- There are three ways to use timelineIcon:
+ The avatar is a very important part of the comment and you should
+ always show one:
- Use the defaults; a user icon inside a large container for
- regular comments; or a dot icon inside a small
- container for update comments.
+ By default, each EuiComment shows an avatar with
+ the initial letter of the username. It also
+ uses the username for the avatar title
+ attribute.
- Pass a string with any of the icon types that{' '}
- EuiIcon supports and it will receive the default
- styling.
+ If your EuiComment doesn't have a{' '}
+ username, or if you don't want to use it
+ for generating the title attribute and initials you can use the{' '}
+ avatarName prop instead. (e.g you want to
+ display the full name of the user instead of the{' '}
+ username).
- Pass any other element (e.g.{' '}
+ You can also show an icon by passing to the{' '}
+ avatarIcon any of the icon types that{' '}
+
+ EuiIcon
+ {' '}
+ supports. The icon will show inside a subdued{' '}
+ avatar. Consider this option when showing a system update.
+
+
+ You can further customize the timeline avatar by passing to the{' '}
+ EuiComment.avatarProps any{' '}
EuiAvatar
-
- ). It is recommended not to use an element larger than 40x40.
+ {' '}
+ prop.
There are scenarios where you might want to allow the user to
perform actions related to each comment. Some
@@ -203,27 +271,76 @@ export const CommentListExample = {
sharing and copying. To add custom actions to a
comment, use the actions
prop. These will be placed to the right of the metadata in the
- comment's header. You can use any element to display{' '}
- actions. For example, for something simple you
- can use{' '}
+ comment's header. We recommend using a{' '}
EuiButtonIcon
{' '}
- and for something more complex you can combine that with{' '}
+ to trigger an action. When having multiple actions, consider
+ grouping them in a nested menu system using a{' '}
EuiPopover
{' '}
- and{' '}
+ with a{' '}
EuiContextMenu
.
+ The below example uses a list of EuiComments, a{' '}
+
+ EuiMarkdownEditor
+
+ , and a{' '}
+
+ EuiMarkdownFormat
+ {' '}
+ to create a simple comment system.
+
+
+
+ Each comment renders in a EuiComment.
+
+
+ We use the EuiMarkdownEditor to post the{' '}
+ EuiComment.children. This means the content
+ uses Markdown.
+
+
+ When the new EuiComment is posted, we use the{' '}
+ EuiMarkdownFormat to wrap the{' '}
+ EuiComment.children and render the Markdown
+ correctly.
+
+
+
+ When dealing with asynchronous events like when adding a message we
+ recommend setting the EuiMarkdownEditor to a{' '}
+ readOnly state and the "Add comment"{' '}
+ EuiButton to a isLoading state.
+ This will ensure users understand that the content cannot be changed
+ while the comment is being submitted.
+