SectionMessage

The <SectionMessage> component is a block-level element designed to alert users about specific content in a designated section on the page. It is positioned close to the relevant content to clearly indicate its connection. Section messages provide contextual feedback within a section of the page and are persistent, non-modal elements.

Anatomy

A <SectionMessage> is a container with a severity icon, an optional title, the message content, and an optional dismiss button.

• Container: Wraps the message on a neutral surface with a muted variant-colored border.
• Icon: Variant icon that reinforces the severity.
• Title (optional): Short headline summarizing the message. Renders as a semantic heading; adjust its level with the headingLevel prop so it fits the surrounding document outline. Don't end the title with a period, and don't repeat it in the content.
• Description (optional): A short summary directly below the title.
• Content: Descriptive body text. This is the required core of the message.
• Close button (optional): Dismiss control when closeButton is set.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Every variant sits on a neutral surface, with the severity carried by a muted variant-colored border and the colored icon rather than a tinted background. This keeps standard <Button> and <Link> actions placed inside reading correctly, and body text at full contrast. The colored border, distinct icon shape and color, and title keep the variants distinguishable without relying on color alone.

Usage

Section messages are ideal for displaying important feedback related to a specific section of the page. Unlike modal dialogs, which interrupt the user's workflow, section messages remain visible without blocking interaction with other parts of the interface.

Place a section message close to the content it relates to, typically directly above, so the relationship between the message and the affected area is obvious. When the message summarizes form errors, place it at the top of the form and pair it with field-level validation on the inputs themselves, so users can locate both the overall problem and the specific fields that need attention.

Keep the message short. The body should fit within roughly two lines, and longer explanations belong on a dedicated page or in a dialog opened from an action, not in the message itself.

Description

Use <SectionMessage.Description> for a short summary that sits between the title and the content, for example the outcome of an action, while the content carries the details.

import { SectionMessage } from '@marigold/components';export default () => (  <SectionMessage variant="success">    <SectionMessage.Title>Backup completed</SectionMessage.Title>    <SectionMessage.Description>      All files were copied to the archive.    </SectionMessage.Description>    <SectionMessage.Content>      The next scheduled backup runs tonight at 2 am. You can change the      schedule in the backup settings.    </SectionMessage.Content>  </SectionMessage>);

Each slot has a distinct role:

The description earns its place when there is also body content to separate it from. Avoid these patterns:

• Don't repeat the title in the description.
• Don't put links or actions in the description. They belong in the content.
• If the message is a single sentence, use <SectionMessage.Content> alone and skip the description.

Dismissal

Make a section message dismissable when the information is useful but optional, like a confirmation or a low-urgency notice that users may want to clear once they've seen it. Keep the message persistent when users must act on it, such as for blocking errors or required steps, so guidance they still need isn't accidentally removed.

To allow dismissal, set the closeButton property on the <SectionMessage>.

import { SectionMessage } from '@marigold/components';export default () => (  <SectionMessage closeButton>    <SectionMessage.Title>      Configuration of the hardware key    </SectionMessage.Title>    <SectionMessage.Content>      Activating the function allows you to change the scanning direction. Keep      in mind to have the correct settings set to "changeable".    </SectionMessage.Content>  </SectionMessage>);

For full control over when the message is shown or hidden, use the open and onOpenChange properties.

When the user dismisses the message, make sure keyboard focus moves to a useful destination: the control that triggered the message, the preceding heading, or the next interactive element. Losing focus leaves keyboard and screen reader users disoriented.

Actions

Add actions to a section message when the user has a clear next step they can take from the message itself, such as retrying a failed save, opening the relevant settings, or jumping to a detail page. Skip them when the user can act through the surrounding UI without needing a shortcut inside the message.

Place actions near the content so the next step is easy to find, and keep the set focused:

• Label actions with a verb plus a noun, like "Retry payment" or "Open settings", so the outcome is clear before the user clicks.
• For text links, make the link text describe the destination, not "Click here" or "Learn more".

import {  Button,  Inline,  Link,  SectionMessage,  Stack,} from '@marigold/components';export default () => (  <SectionMessage closeButton>    <SectionMessage.Title>This page is read-only.</SectionMessage.Title>    <SectionMessage.Content>      <Stack space={3} alignX="left">        You don't have permission to edit this page. If you think you should        have editing rights, contact your group administrator.        <Inline space={4} alignY="center">          <Button variant="primary" size="small">            Request access          </Button>          <Link href="#">View team roles</Link>        </Inline>      </Stack>    </SectionMessage.Content>  </SectionMessage>);

Announcements

A section message often appears in response to a user action, such as a saved setting, a submitted form, or a failed payment. Screen reader users won't notice the new content unless the message is also announced through an ARIA live region.

Set the announce prop and <SectionMessage> will fire the announcement for you. You don't need to wrap the message in your own live region. Only apply it to messages that appear in response to a user action. A message rendered on initial page load will fire during hydration and interrupt the user's first scan of the page.

For confirmations and informational updates (info, success, warning), use announce to opt in. Screen readers will announce the content politely, during the next break in speech, without interrupting the user.

import { useState } from 'react';import {  Button,  Checkbox,  Form,  SectionMessage,  Stack,} from '@marigold/components';const drafts = [  'Q4 launch announcement',  'Updated pricing page copy',  'Welcome new team members',  'Public roadmap update',];export default () => {  const [selected, setSelected] = useState<string[]>([]);  const [count, setCount] = useState(0);  const [attempt, setAttempt] = useState(0);  return (    <Form      unstyled      onSubmit={event => {        event.preventDefault();        setCount(selected.length);        setAttempt(a => a + 1);        setSelected([]);      }}    >      <Stack space={4} alignX="left">        <Checkbox.Group          label="Drafts"          value={selected}          onChange={setSelected}          validate={value =>            value.length === 0 ? 'Select at least one draft to archive.' : null          }        >          {drafts.map(d => (            <Checkbox key={d} value={d} label={d} />          ))}        </Checkbox.Group>        <Button type="submit" variant="primary">          Archive selected        </Button>        {attempt > 0 && (          <SectionMessage key={attempt} variant="success" announce>            <SectionMessage.Title>              {count === 1 ? 'Draft archived' : 'Drafts archived'}            </SectionMessage.Title>            <SectionMessage.Content>              Moved {count} {count === 1 ? 'draft' : 'drafts'} to the archive.              They can be restored from the trash for the next 30 days.            </SectionMessage.Content>          </SectionMessage>        )}      </Stack>    </Form>  );};

The error variant announces automatically. <SectionMessage variant="error"> defaults to announce={true} with assertive priority, so urgent issues are read out the moment they appear without any extra setup.

import { useState } from 'react';import { Button, SectionMessage, Stack, TextArea } from '@marigold/components';export default () => {  const [attempt, setAttempt] = useState(0);  return (    <Stack space={4} alignX="left">      <TextArea        label="Team bio"        defaultValue="We help local creators run unforgettable events."      />      <Button variant="primary" onPress={() => setAttempt(n => n + 1)}>        Save changes      </Button>      {attempt > 0 && (        <SectionMessage key={attempt} variant="error">          <SectionMessage.Title>Couldn't save changes</SectionMessage.Title>          <SectionMessage.Content>            The server is temporarily unavailable. Your team bio has not been            updated yet. We've kept your draft here so you can try again in a            moment.          </SectionMessage.Content>        </SectionMessage>      )}    </Stack>  );};

To re-announce the same message (for example, the user clicks "Retry" a second time), give the <SectionMessage> a changing key. The component remounts and the announcement fires again. Without it, screen readers only hear the announcement the first time.

Don't move keyboard focus to a section message that appears in response to a background change. The live-region announcement is enough, and pulling focus is disorienting. The exception is a blocking form-level error after submit, where moving focus to the message helps the user locate what went wrong.

Reserve assertive announcements for messages that genuinely need to interrupt. Most updates should be polite.

Props

SectionMessage

SectionMessage.Title

SectionMessage.Description

SectionMessage.Content

Alternative components

• Dialog: If you need to interact with messages to proceed with a task or a flow you should use a dialog.

• Form components: When you need to inform the users of a status from a form field, you can use the help text/ validation message which comes with our form components.

Related