CodexMessage
System feedback in response to or to inform a user action.
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
dismissButtonLabelprop, which adds a dismiss button - By using the
autoDismissprop. This can be set totrueto use the default display time of 4000 milliseconds (4 seconds), or the display time can be customized by settingautoDismissto a number of milliseconds.
Demos
Configurable
<cdx-message dismiss-button-label="Close">Message text</cdx-message>| Name | Value |
|---|---|
| Props | |
type | |
inline | |
dismissButtonLabel | |
| 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 lang="ts">
import { defineComponent } from "vue";
import { CdxMessage, CdxButton } from "@wikimedia/codex";
export default defineComponent({
name: "MessageFadeIn",
components: { CdxMessage, CdxButton },
data() {
return {
showMessage: false
};
}
});
</script>Dismiss button
Messages can be made dismissable by supplying a semantic label for the dismiss button via the dismissButtonLabel prop. This label will be visually hidden but accessible to screen readers.
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 understand before disappearing. When in doubt, do not use auto-dismiss.
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 lang="ts">
import { defineComponent } from "vue";
import { CdxMessage, CdxButton } from "@wikimedia/codex";
export default 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>Usage
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 |
dismissButtonLabel | Label text for the dismiss button for user-dismissable messages. An icon-only button will be displayed that will hide the message on click. This prop is for the hidden button label required for screen reader accessibility and tooltip text. | 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.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>