MessagingCard | Coinbase Design System

MessagingCard

@coinbase/cds-web@9.0.2

MessagingCard displays promotional or informational content with two variants: 'upsell' for promoting features with a primary background, and 'nudge' for encouraging actions with an alternate background. It replaces the deprecated NudgeCard and UpsellCard components.

import { MessagingCard } from '@coinbase/cds-web/cards/MessagingCard'

Related components

MessagingCard provides two card types for promotional and informational content.

Basic Types

Use type to set the card variant:

upsell: Primary background, used for promoting features or products. Use variant="secondary" buttons.
nudge: Alternate background, used for encouraging user actions. Use variant="tertiary" (transparent) buttons for a less intrusive appearance.

Media Placement

Use mediaPlacement to control the position of media content.

Upsell Card Styles

MessagingCard with type="upsell" supports various background colors to match different promotional purposes. Use the background prop for semantic tokens.

For custom background colors, use the recommended approach:

Non-interactive cards (default as="article" or renderAsPressable={false}): set the background via styles.root or classNames.root (e.g. styles={{ root: { backgroundColor: 'rgb(var(--blue80))' } }}).
Interactive cards (renderAsPressable with as="a" or as="button"): set the background via blendStyles.background (e.g. blendStyles={{ background: 'rgb(var(--blue80))' }}) so press states are handled correctly.

General Upsell

Utilize the default background for general information and non-urgent promotions. Its versatile design is perfect for a broad range of content, providing a subtle yet effective approach to engage users. It's also the most suitable style for Pictogram illustrations.

Feature Upsell

Ideal for highlighting Coinbase tools, innovative features, and unique functionalities. Choose from our palette of distinct colors to make your Feature Upsell stand out. Each color is carefully selected to grab attention while aligning with the specific nature of the feature being promoted.

Community Upsell

Designed for community-focused messaging. Vibrant colors spark enthusiasm and encourage active participation, fostering a sense of community engagement.

Product Upsell

Optimal for business products, security features, and functionalities that emphasize trust and reliability, such as Coinbase One and Coinbase Card. Blue and dark backgrounds symbolize stability, trustworthiness, and professionalism.

News Upsell

Specifically tailored for company announcements and policy updates. Its design ensures that important information is conveyed clearly and prominently, ensuring users stay well-informed about the latest developments.

Nudge Card Style

Use type="nudge" for gentle reminders or secondary options. Nudge cards use the alternate background and blend more seamlessly with the page. Pair them with Pictogram illustrations and transparent buttons.

Features

Dismissible Cards

Use onDismissButtonClick to add a dismiss button.

Actions

Use the action prop to add an action button. Pass a string to render a default button with onActionButtonClick, or pass a custom React element.

Complete Example

Combine all features in a complete card.

Interactive Dismissible List

This example shows a list of cards that can be dismissed interactively. Click the dismiss button to remove cards from the list.

Live Code

function DismissibleCards() {
  const cards = [
    {
      id: '1',
      title: 'Welcome to Coinbase',
      description: 'Get started with your crypto journey',
      type: 'upsell',
    },
    {
      id: '2',
      title: 'Complete your profile',
      description: 'Add your details to unlock more features',
      type: 'nudge',
    },
    {
      id: '3',
      title: 'Enable notifications',
      description: 'Stay updated on market movements',
      type: 'upsell',
    },
    {
      id: '4',
      title: 'Invite friends',
      description: 'Earn rewards when friends join',
      type: 'nudge',
    },
  ];

  const [dismissedIds, setDismissedIds] = React.useState(new Set());

  const handleDismiss = (id) => {
    setDismissedIds((prev) => new Set(prev).add(id));
  };

  const handleReset = () => {
    setDismissedIds(new Set());
  };

  const visibleCards = cards.filter((card) => !dismissedIds.has(card.id));

  return (
    <VStack gap={2}>
      <HStack gap={2} flexWrap="wrap">
        {visibleCards.map((card) => (
          <MessagingCard
            key={card.id}
            type={card.type}
            styles={
              card.type === 'upsell'
                ? { root: { backgroundColor: 'rgb(var(--gray100))' } }
                : undefined
            }
            title={card.title}
            description={card.description}
            width={360}
            media={
              card.type === 'upsell' ? (
                <RemoteImage
                  alt="Promotional illustration"
                  height={160}
                  resizeMode="cover"
                  shape="rectangle"
                  source="/img/object.png"
                />
              ) : (
                <Pictogram dimension="48x48" name="addToWatchlist" />
              )
            }
            mediaPlacement="end"
            onDismissButtonClick={() => handleDismiss(card.id)}
            dismissButtonAccessibilityLabel={`Dismiss ${card.title}`}
          />
        ))}
        {visibleCards.length === 0 && (
          <Text color="fgNegative" font="label1">
            All cards dismissed!
          </Text>
        )}
      </HStack>
      <Button onClick={handleReset} variant="tertiary">
        Reset Cards
      </Button>
    </VStack>
  );
}

Polymorphic and Interactive

MessagingCard supports polymorphic rendering with as and can be made interactive with renderAsPressable.

Custom Content

Use React nodes for custom styled content.

Multiple Cards

Display multiple cards in a carousel.

Accessibility

Interactive Cards with Dismiss Button

When you need both onDismissButtonClick and want the entire card to be clickable, you should handle accessibility carefully to avoid nested interactive elements.

The Problem: If you use renderAsPressable with onClick and also have onDismissButtonClick, the card becomes a button containing another button (the dismiss button). This creates accessibility issues for screen reader users.

The Solution: Mark the card as non-accessible and add a separate action button inside the card with the same action. This allows:

Regular users to click anywhere on the card
Screen reader users to focus on individual interactive elements (action button + dismiss button)

Key points:

Use as="div" to avoid rendering as a semantic button
When using as="div" with renderAsPressable, the card remains keyboard focusable. Set tabIndex={-1} to remove it from the tab order if needed
Call event.stopPropagation() at the beginning of the event handler method passed into the onClick prop for action buttons. This will prevent two click events from firing if the user directly clicks the action button.
Use actionButtonAccessibilityLabel and dismissButtonAccessibilityLabel to add or override the aria-label for the action and dismiss buttons

Color Contrast

MessagingCard supports custom backgrounds via the background prop and, for custom colors, styles.root / classNames.root (non-interactive) or blendStyles.background (interactive). When using custom background colors, ensure sufficient color contrast between text and background:

Use fgInverse text color with dark backgrounds (e.g., accentBoldPurple, bgInverse)
Use fg text color with light backgrounds (e.g., bgPrimaryWash, bgAlternate)
Use the WebAIM Contrast Checker to verify your color combinations meet WCAG AA guidelines (4.5:1 for normal text)

Migration from Deprecated Components

Migrating from NudgeCard

Replace NudgeCard with MessagingCard using type="nudge".

// Before
<NudgeCard
  title="Title"
  description="Description"
  pictogram="addToWatchlist"
  action="Learn more"
  onActionPress={handleAction}
  onDismissPress={handleDismiss}
/>

// After
<MessagingCard
  type="nudge"
  title="Title"
  description="Description"
  media={<Pictogram dimension="64x64" name="addToWatchlist" />}
  action="Learn more"
  onActionButtonClick={handleAction}
  onDismissButtonClick={handleDismiss}
  mediaPlacement="end"
/>

Migrating from UpsellCard

Replace UpsellCard with MessagingCard using type="upsell".

// Before
<UpsellCard
  title="Title"
  description="Description"
  media={<RemoteImage ... />}
  action="Get Started"
  onActionPress={handleAction}
  onDismissPress={handleDismiss}
/>

// After
<MessagingCard
  type="upsell"
  title="Title"
  description="Description"
  media={<RemoteImage ... />}
  action="Get Started"
  onActionButtonClick={handleAction}
  onDismissButtonClick={handleDismiss}
  mediaPlacement="end"
/>

Basic Types

Media Placement

Upsell Card Styles

General Upsell

Feature Upsell

Community Upsell

Product Upsell

News Upsell

Nudge Card Style

Features

Dismissible Cards

Tags

Actions

Complete Example

Interactive Dismissible List

Polymorphic and Interactive

Custom Content

Multiple Cards

Accessibility

Interactive Cards with Dismiss Button

Color Contrast

Migration from Deprecated Components

Migrating from NudgeCard

Migrating from UpsellCard

Is this page useful?

Basic Types​

Media Placement​

Upsell Card Styles​

General Upsell​

Feature Upsell​

Community Upsell​

Product Upsell​

News Upsell​

Nudge Card Style​

Features​

Dismissible Cards​

Tags​

Actions​

Complete Example​

Interactive Dismissible List​

Polymorphic and Interactive​

Custom Content​

Multiple Cards​

Accessibility​

Interactive Cards with Dismiss Button​

Color Contrast​

Migration from Deprecated Components​

Migrating from NudgeCard​

Migrating from UpsellCard​

Is this page useful?

Basic Types

Media Placement

Upsell Card Styles

General Upsell

Feature Upsell

Community Upsell

Product Upsell

News Upsell

Nudge Card Style

Features

Dismissible Cards

Tags

Actions

Complete Example

Interactive Dismissible List

Polymorphic and Interactive

Custom Content

Multiple Cards

Accessibility

Interactive Cards with Dismiss Button

Color Contrast

Migration from Deprecated Components

Migrating from NudgeCard

Migrating from UpsellCard