Message β
A Message provides system feedback for users. Messages can be provided as a prominently-displayed banner with a longer explanation, or as inline validation feedback.
Guidelines β
When to use messages β
Messages must include text clearly defining the system feedback to the user. They also include an icon to help users recognize the type of message, and they can also feature an optional dismiss button to close the message.
Specifications β
The message component may contain the following items:
- Icon
Icons simplify user recognition and provide the ability to shorten message text. A specific icon is matched with each message type (e.g., βsuccessβ) to ensure recognition. - Message text
The message text should be as clear and concise as possible, offering feedback to users. If applicable, it may also suggest next steps. - Close button (optional)
To allow for the message to be dismissed, an optional icon-only quiet button can be included.
The inline message component includes both the icon and message elements, excluding the close button.
Accessibility note
The message icon adds a point of recognition for color-blind users.
Component limitations β
The message can contain an unlimited number of characters, and there is no minimum requirement. Ensure that the icon is always aligned on top with the text.
Refer to the Message component in Codex Figma.
Types β
Message layout β
There are two types of messages, each suited to specific use cases:
- Message: Utilize it to display system feedback, respond to user actions, or provide information.
- Inline message: Employ it to offer feedback on the validation of form inputs.
Message type β
Depending on the feedback conveyed to the user, the messages can be categorized as follows:
- Neutral or notice messages provide general user feedback. They are accompanied by the 'infoFilled' icon by default, but the icon may be changed to any other system icon to emphasize a specific aspect of the notice message.
- Success messages deliver feedback of a successful user interaction, like publishing an article. Accompany the message with the 'success' icon.
- Error messages have the strongest visual priority of all system messages. Use them to alert the user only in situations when their immediate attention is needed. Accompany the message with the 'error' icon.
- Warning messages provide important information about circumstances that require caution. Accompany the message with the 'alert' icon.
Inline messages follow the same categorization: notice, success, error, and warning.
Dismissability β
Messages can be categorized based on how they are removed from the interface as follows:
Dismiss button β
Messages can be dismissed by utilizing the close button within the message. Note that inline messages cannot be dismissable.
Auto-dismiss β
Messages can be also auto-dismissable. This means they will automatically disappear after 4 seconds.
This feature should only be used for very short messages to ensure that they can be read and understood before disappearing. When in doubt, do not use auto-dismiss. To prevent error messages from disappearing before users fix the error, do not use auto-dismiss with error messages. Auto-dismiss can be used with or without the manual dismiss button.
Best practices β
Consider the following recommendations when working with messages.
Icon β
- Customize the notice message with another icon if needed.
- Use the 'success', 'error', and 'alert' icons to represent their corresponding message statuses.
- Remove the icon, as it is essential for reinforcing the meaning of the message.
- Replace the status icon in the success, error, and warning messages.
Message's text β
- Incorporate various text formats and links within the message text as necessary.
- Bold all the message text.
Content β
Keeping messages clear is ideal for accessibility (reducing cognitive load) and using the right tone provides relevance.
Error message β
Error messages let a reader know that there is a problem and should include clear instructions or next steps to solve the problem.
- Keep messages short and simple, with one or two solutions, to reduce cognitive load. Concise & Accessible
- Use formatting to make the copy easy to skim and help users move through a flow more quickly and confidently. Concise
- Give multiple options for fixing the issue. Concise
- Apologize more than once, to avoid eroding the readerβs sense of trust in the experience. Trustworthy
Success message β
Success messages let a user know that the action they took was successful.
- Use clear, positive, short messages. Accessible & Relevant
- Include too much information. Concise
Warning message β
Warning messages indicate urgent information and consequences to the user (e.g., that an impending action is irreversible). Warning messages should also include a solution to the potential problem.
- Keep messages short and precise. Concise & Accessible
- Write in a way that might cause a reader to panic or worry. Trustworthy
Notice message β
Notice messages alert a reader to important, but non-urgent, information. These messages are not generally used for feedback on a userβs actions, but rather for offering neutral information or recommendations.
- Keep messages in an informative, neutral tone. Consistent & Trustworthy
- Include more than one message. Concise
- Use warning or error language. Relevant & Trustworthy
Keyboard navigation β
Key | Function |
---|---|
Enter | When the Message is closable and the focus is placed on its close button, it closes the Message. If the focus is placed on a link within the Message, it activates the link. |
Demos β
Configurable β
<cdx-message>Message text</cdx-message>
Name | Value |
---|---|
Props | |
type | |
inline | |
allowUserDismiss | |
Slots | |
default | |
View | |
Reading direction |
Fade in β
When a message is dynamically added to the UI, use the fadeIn
prop to enable a transition.
<template>
<cdx-button :disabled="showMessage" @click="showMessage = true">
Show message
</cdx-button>
<cdx-message v-if="showMessage" type="warning" :fade-in="true">
<p><strong>Warning!</strong> Here's some information you should know.</p>
</cdx-message>
</template>
<script>
import { defineComponent } from "vue";
import { CdxMessage, CdxButton } from "@wikimedia/codex";
export default defineComponent({
name: "MessageFadeIn",
components: { CdxMessage, CdxButton },
data() {
return {
showMessage: false,
};
},
});
</script>
<template>
<cdx-button :disabled="showMessage" @click="showMessage = true">
Show message
</cdx-button>
<cdx-message v-if="showMessage" type="warning" :fade-in="true">
<p><strong>Warning!</strong> Here's some information you should know.</p>
</cdx-message>
</template>
<script>
const { defineComponent } = require("vue");
const { CdxMessage, CdxButton } = require("@wikimedia/codex");
module.exports = defineComponent({
name: "MessageFadeIn",
components: { CdxMessage, CdxButton },
data() {
return {
showMessage: false,
};
},
});
</script>
Dismiss button β
Messages can be made dismissable by setting the allowUserDismiss
prop to true
.
When the dismiss button is clicked, the Message component hides itself, and a 'user-dismissed' event is emitted to the parent component in case the parent component needs to react to the message dismissal in some way.
Note that inline messages cannot be dismissable.
<cdx-message dismiss-button-label="Close">
Notice message with dismiss button
</cdx-message>
Auto-dismiss β
The autoDismiss
prop can be used to automatically remove the message after a period of time. Set this prop to true
to use the default display time of 4000 milliseconds (4 seconds). To customize the display time, set the autoDismiss
prop to a number of milliseconds.
This feature should only be used for very short messages to ensure that can be read and understood before disappearing. When in doubt, do not use auto-dismiss. Auto-dismiss cannot be used for error messages: if the type
prop is set to error
, the autoDismiss
prop will be ignored and a warning will be thrown if it's set.
Auto-dismiss can be used with or without the manual dismiss button.
<template>
<cdx-button :disabled="showMessage" @click="showMessage = true">
Show message
</cdx-button>
<cdx-message
v-if="showMessage"
type="success"
:fade-in="true"
:auto-dismiss="true"
:display-time="3000"
>
Success! This message will disappear...
</cdx-message>
</template>
<script>
import { defineComponent } from "vue";
import { CdxMessage, CdxButton } from "@wikimedia/codex";
export default defineComponent({
name: "MessageAutoDismiss",
components: { CdxMessage, CdxButton },
data() {
return {
showMessage: false,
};
},
});
</script>
<template>
<cdx-button :disabled="showMessage" @click="showMessage = true">
Show message
</cdx-button>
<cdx-message
v-if="showMessage"
type="success"
:fade-in="true"
:auto-dismiss="true"
:display-time="3000"
>
Success! This message will disappear...
</cdx-message>
</template>
<script>
const { defineComponent } = require("vue");
const { CdxMessage, CdxButton } = require("@wikimedia/codex");
module.exports = defineComponent({
name: "MessageAutoDismiss",
components: { CdxMessage, CdxButton },
data() {
return {
showMessage: false,
};
},
});
</script>
Multiline message β
Message content can contain markup like bold text and links.
<cdx-message type="error">
<p><strong>An error has occurred.</strong></p>
<p>Comprehensive explanation of the error.</p>
<p><a href="#">Link</a> to more information.</p>
</cdx-message>
With custom icon β
Only notice messages may have a custom icon.
<cdx-message :icon="cdxIconArticle">
Notice message with custom icon
</cdx-message>
Vue usage β
Message styles and icon will vary depending on the message type (notice, warning, error or success). Messages are block style by default, but can be displayed as inline messages via the inline
prop.
Block-style messages can be made dismissable in the following ways:
- By using the
allowUserDismiss
prop, which adds a dismiss button. - By using the
autoDismiss
prop. This can be set totrue
to use the default display time of 4000 milliseconds (4 seconds), or the display time can be customized by settingautoDismiss
to a number of milliseconds. Error messages cannot auto-dismiss: if thetype
prop is set toerror
, then theautoDismiss
prop will be ignored.
Props β
Prop name | Description | Type | Values | Default |
---|---|---|---|---|
type | Status type of Message. | StatusType | 'notice' , 'warning' , 'error' , 'success' | 'notice' |
inline | Whether this message follows the inline design (no padding, background color, or border). | boolean | - | false |
icon | Custom message icon. Only allowed for notice messages. | Icon | - | null |
fadeIn | Whether the message should fade in. Should be used for messages that are dynamically displayed, not present on page load. | boolean | - | false |
allowUserDismiss | Allow the message to be dismissed by the user. Adds an icon-only dismiss button. | boolean | - | false |
dismissButtonLabel | Visually-hidden label text for the dismiss button for user-dismissable messages. Omit this prop to use the default value, "Close". | string | - | '' |
autoDismiss | Enable automatic dismissal of message after a period of time. This prop can be set to true to use the default display time of 4000 milliseconds. To customize the display time, set this prop to a number of milliseconds.Error messages cannot be automatically dismissed. If the type prop is set to error , this prop will be ignored.TODO: consider adding a stricter validator to set limits on this. If the time is too short, the message may not be readable. If the time is too long, the message probably shouldn't be auto-dismissed. | boolean|number | - | false |
Events β
Event name | Properties | Description |
---|---|---|
user-dismissed | Emitted when the message is dismissed by the user via the dismiss button. | |
auto-dismissed | Emitted when the message is automatically dismissed after the display time. |
Slots β
Name | Description | Bindings |
---|---|---|
default | Message content. |
CSS-only version β
Note that some features of the Vue component require JavaScript and are therefore not supported in the CSS-only version (fade in, dismiss button, and auto-dismiss).
Markup structure β
TIP
The outer <div>
should have one of the following ARIA attributes:
- For notice, warning, and success messages:
aria-live="polite"
- For error messages:
role="alert"
<!-- Root element with layout and type classes, and additional attribute(s). -->
<div
class="cdx-message cdx-message--block cdx-message--notice"
aria-live="polite"
>
<!-- Empty span for message icon. -->
<span class="cdx-message__icon"></span>
<!-- Div for content. -->
<div class="cdx-message__content">Message content (can include markup)</div>
</div>
Message layout β
There are two layout styles for messages: block and inline. Use the following classes to apply these layouts.
- Block:
cdx-message--block
(class can be omitted since this is the default) - Inline:
cdx-message--inline
<div
class="cdx-message cdx-message--block cdx-message--notice"
aria-live="polite"
>
<span class="cdx-message__icon"></span>
<div class="cdx-message__content">This is a block-style message.</div>
</div>
<div
class="cdx-message cdx-message--inline cdx-message--notice"
aria-live="polite"
>
<span class="cdx-message__icon"></span>
<div class="cdx-message__content">This is an inline-style message.</div>
</div>
Message types β
There are 4 message types, which change the colors and icon depending on the message's purpose. Use these classes to apply the different message type styles:
- Notice:
cdx-message--notice
(class can be omitted since this is the default) - Warning:
cdx-message--warning
- Error:
cdx-message--error
- Success:
cdx-message--success
<div
class="cdx-message cdx-message--block cdx-message--notice"
aria-live="polite"
>
<span class="cdx-message__icon"></span>
<div class="cdx-message__content">This is a notice message.</div>
</div>
<div
class="cdx-message cdx-message--block cdx-message--warning"
aria-live="polite"
>
<span class="cdx-message__icon"></span>
<div class="cdx-message__content">This is a warning message.</div>
</div>
<div class="cdx-message cdx-message--block cdx-message--error" role="alert">
<span class="cdx-message__icon"></span>
<div class="cdx-message__content">This is an error message.</div>
</div>
<div
class="cdx-message cdx-message--block cdx-message--success"
aria-live="polite"
>
<span class="cdx-message__icon"></span>
<div class="cdx-message__content">This is a success message.</div>
</div>
Multiline message β
Message content can contain markup like bold text and links.
<div class="cdx-message cdx-message--block cdx-message--error" role="alert">
<span class="cdx-message__icon"></span>
<div class="cdx-message__content">
<p><strong>An error has occurred.</strong></p>
<p>Comprehensive explanation of the error.</p>
<p><a href="#">Link</a> to more information.</p>
</div>
</div>