Banner

Anchor to PropertiesProperties

'info' | 'success' | 'warning' | 'critical'

Anchor to ExamplesExamples

Anchor to Warn about API sync failureWarn about API sync failure

Show a product sync failure with a retry action. This example renders a dismissible Banner with a critical tone, a primary action Button that retries the sync, and a message explaining the issue.

Warn about API sync failure

Warn about API sync failure

ReactTS

Copy

99

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

import {useState} from 'react';

import {reactExtension, useApi, Banner, Button, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {

const {data} = useApi('admin.product-details.block.render');

const productId = data.selected[0]?.id;

const [visible, setVisible] = useState(true);

if (!visible) return null;

return (

<BlockStack>

<Banner

title="Product sync failed"

tone="critical"

dismissible

onDismiss={() => setVisible(false)}

primaryAction={

<Button

onPress={async () => {

await fetch('/api/products/sync', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({productId}),

});

}}

>

Retry sync

</Button>

}

>

The last sync attempt could not reach your warehouse system. Check your

API credentials and try again.

</Banner>

</BlockStack>

);

}

export default reactExtension(

'admin.product-details.block.render',

() => <App />,

);

99

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

import {extension, Banner, Button, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(

'admin.product-details.block.render',

(root, api) => {

const {data} = api;

const productId = data.selected[0]?.id;

const stack = root.createComponent(BlockStack);

const retryButton = root.createComponent(

Button,

{

onPress: async () => {

await fetch('/api/products/sync', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({productId}),

});

},

},

'Retry sync',

);

const banner = root.createComponent(

Banner,

{

title: 'Product sync failed',

tone: 'critical',

dismissible: true,

onDismiss: () => {

stack.removeChild(banner);

},

primaryAction: retryButton,

},

'The last sync attempt could not reach your warehouse system. Check your API credentials and try again.',

);

stack.appendChild(banner);

root.appendChild(stack);

},

);

React

import {useState} from 'react';
import {reactExtension, useApi, Banner, Button, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {
  const {data} = useApi('admin.product-details.block.render');
  const productId = data.selected[0]?.id;
  const [visible, setVisible] = useState(true);

  if (!visible) return null;

  return (
    <BlockStack>
      <Banner
        title="Product sync failed"
        tone="critical"
        dismissible
        onDismiss={() => setVisible(false)}
        primaryAction={
          <Button
            onPress={async () => {
              await fetch('/api/products/sync', {
                method: 'POST',
                headers: {'Content-Type': 'application/json'},
                body: JSON.stringify({productId}),
              });
            }}
          >
            Retry sync
          </Button>
        }
      >
        The last sync attempt could not reach your warehouse system. Check your
        API credentials and try again.
      </Banner>
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.block.render',
  () => <App />,
);

TS

import {extension, Banner, Button, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root, api) => {
    const {data} = api;
    const productId = data.selected[0]?.id;

    const stack = root.createComponent(BlockStack);

    const retryButton = root.createComponent(
      Button,
      {
        onPress: async () => {
          await fetch('/api/products/sync', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({productId}),
          });
        },
      },
      'Retry sync',
    );

    const banner = root.createComponent(
      Banner,
      {
        title: 'Product sync failed',
        tone: 'critical',
        dismissible: true,
        onDismiss: () => {
          stack.removeChild(banner);
        },
        primaryAction: retryButton,
      },
      'The last sync attempt could not reach your warehouse system. Check your API credentials and try again.',
    );

    stack.appendChild(banner);
    root.appendChild(stack);
  },
);

import {useState} from 'react';
import {reactExtension, useApi, Banner, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {
  const {data} = useApi('admin.product-details.block.render');
  const productId = data.selected[0]?.id;
  const [visible, setVisible] = useState(true);

  if (!visible) return null;

  return (
    <BlockStack>
      <Banner
        title="Product updated successfully"
        tone="success"
        dismissible
        onDismiss={() => setVisible(false)}
      >
        Tags and metafields for product {productId} have been synced to your
        external catalog.
      </Banner>
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.block.render',
  () => <App />,
);

import {extension, Banner, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root, api) => {
    const {data} = api;
    const productId = data.selected[0]?.id;

    const stack = root.createComponent(BlockStack);

    const banner = root.createComponent(
      Banner,
      {
        title: 'Product updated successfully',
        tone: 'success',
        dismissible: true,
        onDismiss: () => {
          stack.removeChild(banner);
        },
      },
      `Tags and metafields for product ${productId} have been synced to your external catalog.`,
    );

    stack.appendChild(banner);
    root.appendChild(stack);
  },
);

import {reactExtension, useApi, Banner, Button, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {
  const {close} = useApi('admin.product-details.action.render');

  return (
    <BlockStack>
      <Banner
        title="Missing required fields"
        tone="warning"
        secondaryAction={
          <Button onPress={() => close()}>Dismiss</Button>
        }
      >
        The product is missing a weight and shipping dimensions. These fields
        are required by your fulfillment provider before orders can be
        processed.
      </Banner>
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.action.render',
  () => <App />,
);

import {extension, Banner, Button, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.action.render',
  (root, api) => {
    const {close} = api;

    const stack = root.createComponent(BlockStack);

    const dismissButton = root.createComponent(
      Button,
      {onPress: () => close()},
      'Dismiss',
    );

    const banner = root.createComponent(
      Banner,
      {
        title: 'Missing required fields',
        tone: 'warning',
        secondaryAction: dismissButton,
      },
      'The product is missing a weight and shipping dimensions. These fields are required by your fulfillment provider before orders can be processed.',
    );

    stack.appendChild(banner);
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

• Focus on a single message: Present one piece of information or required action per banner to maintain clarity. If you have multiple messages, stack separate banners.
• Keep messages concise: Write content that merchants can quickly scan and understand without spending time deciphering the meaning or next steps.
• Provide clear actions: For warning and critical banners, include a primaryAction or secondaryAction with specific next steps so merchants know how to proceed.
• Use tones consistently: Use one tone consistently for the same status across your extension, such as info for general information. Don't mix warning and critical for the same severity level — merchants will lose trust in the signal if tones are inconsistent.

Anchor to LimitationsLimitations

• The dismissed state doesn't persist across page loads or sessions. You must implement your own persistence logic using app storage or server-side state if you want a banner to stay dismissed.
• Multiple banners stack vertically without built-in prioritization or queueing. If you show several banners at once, they all appear simultaneously. Implement your own queueing logic if you need to show one at a time.
• Banner supports only plain text strings, Text components, and Link components as content. For complex layouts with multiple elements, use a Section component instead.