Choose a version:

Announcement

The Announcement component provides a less disruptive alternative to auto-open modals for capturing user attention. It provides a standardized way to engage users without being too intrusive.

Support

Targets (1)

Supported targets

purchase.thank-you.announcement.render

Anchor to eventsEvents

Learn more about registering events.

Anchor to aftertoggle aftertoggle <typeof tagName, >: A callback that fires when the element state changes, after any toggle animations have finished.

If the element transitioned from hidden to showing, the oldState property will be set to closed and the newState property will be set to open.

If the element transitioned from showing to hidden, the oldState property will be set to open and the newState will be closed.

Learn more about ToggleEvent.newState and ToggleEvent.oldState.
Anchor to dismiss dismiss <typeof tagName>: A callback that fires when the announcement is dismissed by the user clicking the close button or by calling the dismiss() method programmatically.
Anchor to toggle toggle <typeof tagName, >: A callback that fires immediately when the element state changes, before any animations.

If the element is transitioning from hidden to showing, the oldState property will be set to closed and the newState property will be set to open.

If the element is transitioning from showing to hidden, then oldState property will be set to open and the newState will be closed.

Learn more about the toggle event, ToggleEvent.newState, and ToggleEvent.oldState.

CallbackEventListener

A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.

(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null

CallbackEvent

An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}

ToggleArgumentsEvent

The event data provided to toggle-related callbacks. Contains the previous and next visibility states of the element.

newState
The visibility state of the element after the toggle occurred.
```
ToggleState
```
oldState
The visibility state of the element before the toggle occurred.
```
ToggleState
```

ToggleState

The visibility state of a toggleable element. - `open`: The element is visible and showing its content. - `closed`: The element is hidden and its content is not visible.

'open' | 'closed'

Anchor to methodsMethods

Learn more about component methods.

Anchor to dismiss dismiss () => void required: Programmatically dismisses the announcement. This triggers the dismiss event callback.

Examples

<s-announcement>

<s-stack direction="inline" gap="base">

<s-text>Check our latest offers</s-text>

<s-link commandFor="modal" command="--show"> Fill out the survey </s-link>

</s-stack>

<s-modal id="modal" heading="Tell us about your shopping experience">

<s-stack gap="base">

<s-text>We'd love to hear about your shopping experience</s-text>

<s-text-area

rows="4"

label="How can we make your shopping experience better?"

></s-text-area>

<s-button>Submit</s-button>

</s-stack>

</s-modal>

</s-announcement>

Preview

Examples

Code

Default

<s-announcement>
  <s-stack direction="inline" gap="base">
    <s-text>Check our latest offers</s-text>
    <s-link commandFor="modal" command="--show"> Fill out the survey </s-link>
  </s-stack>
  <s-modal id="modal" heading="Tell us about your shopping experience">
    <s-stack gap="base">
      <s-text>We'd love to hear about your shopping experience</s-text>
      <s-text-area
        rows="4"
        label="How can we make your shopping experience better?"
      ></s-text-area>
      <s-button>Submit</s-button>
    </s-stack>
  </s-modal>
</s-announcement>

Anchor to best-practicesBest Practices

Prioritize the default state: The most effective use of the announcement bar is when content is short enough to display entirely in its default state, with no need for expansion. This provides the best user experience.
Handle content truncation: The component has a strict maximum height. Content that exceeds the expanded state’s height will be cut off with no scrolling capability. Ensure your application’s logic handles excessively long content gracefully to prevent truncation.
Provide a modal alternative: If your application needs to display more than a few lines of content, avoid cramming it into the announcement bar. Instead, use the bar as a teaser that links to a modal. This is the recommended pattern for displaying surveys, detailed offers, or other longer-form content.

Was this page helpful?