Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

PaymentIcon

The PaymentIcon component displays icons representing payment methods. Use PaymentIcon to visually communicate available or saved payment options so customers can quickly identify their payment instruments.

Payment icons render branded logos for common payment methods like Visa, Mastercard, and PayPal, maintaining consistent sizing and styling across different payment providers.

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the PaymentIcon component.

Anchor to name
name
| string
required

The name of the payment method whose icon should be displayed. Accepts any PaymentMethod value or a custom string for payment methods not yet in the predefined list.

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or contents of the payment icon. When set, it will be announced to users using assistive technologies and will provide them with more context. Use this only when the icon requires an alternative internationalized label or when the default label included with the icon is not appropriate.

Anchor to accessibilityVisibility
accessibilityVisibility
'hidden' | 'visible'
Default: 'visible'

The visibility of the icon to assistive technologies.

  • hidden: The icon is hidden from assistive technology (for example, a screen reader) but remains visually visible.
  • visible: The icon is announced by assistive technologies (the default behavior).

Anchor to ExamplesExamples

Anchor to Display payment iconsDisplay payment icons

Show available payment method icons in a row. This example displays a Shop Pay icon using the name property.

Display payment icons

A Shop Pay payment icon.

Display payment icons

import {
reactExtension,
PaymentIcon,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return <PaymentIcon name="shop-pay" />;
}
import {extension, PaymentIcon} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const paymentIcon = root.createComponent(PaymentIcon, {name: 'shop-pay'});

root.appendChild(paymentIcon);
});

Anchor to Show a saved cardShow a saved card

Pair a payment icon with card details for quick identification. This example displays a Visa icon next to the last four digits of a saved card.

Show a saved card

import {
reactExtension,
PaymentIcon,
Text,
InlineStack,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<InlineStack spacing="small" blockAlignment="center">
<PaymentIcon name="visa" />
<Text>Visa ending in 4242</Text>
</InlineStack>
);
}
import {extension, PaymentIcon, Text, InlineStack} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const icon = root.createComponent(PaymentIcon, {name: 'visa'});
const text = root.createComponent(Text, {}, 'Visa ending in 4242');

const row = root.createComponent(InlineStack, {spacing: 'small', blockAlignment: 'center'});
row.append(icon);
row.append(text);

root.append(row);
});

Anchor to List payment methodsList payment methods

Display a row of accepted payment method icons. This example renders multiple payment icons in an InlineStack so customers can see which methods are available.

List payment methods

import {
reactExtension,
PaymentIcon,
Text,
InlineStack,
BlockStack,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<BlockStack spacing="base">
<Text emphasis="bold">Accepted payment methods</Text>
<InlineStack spacing="small">
<PaymentIcon name="visa" />
<PaymentIcon name="mastercard" />
<PaymentIcon name="amex" />
<PaymentIcon name="shop-pay" />
</InlineStack>
</BlockStack>
);
}
import {extension, PaymentIcon, Text, InlineStack, BlockStack} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const heading = root.createComponent(Text, {emphasis: 'bold'}, 'Accepted payment methods');

const icons = root.createComponent(InlineStack, {spacing: 'small'});
['visa', 'mastercard', 'amex', 'shop-pay'].forEach((name) => {
icons.append(root.createComponent(PaymentIcon, {name}));
});

const stack = root.createComponent(BlockStack, {spacing: 'base'});
stack.append(heading);
stack.append(icons);

root.append(stack);
});

Anchor to Display order payment methodDisplay order payment method

Show the payment method used for an order within a Section. This example combines a payment icon with card number and expiry details.

Display order payment method

import {
reactExtension,
PaymentIcon,
Text,
InlineStack,
BlockStack,
Section,
Heading,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<Section>
<Heading>Payment method</Heading>
<InlineStack spacing="small" blockAlignment="center">
<PaymentIcon name="visa" />
<BlockStack spacing="extraTight">
<Text>Visa ending in 4242</Text>
<Text appearance="subdued">Expires 12/2027</Text>
</BlockStack>
</InlineStack>
</Section>
);
}
import {extension, PaymentIcon, Text, InlineStack, BlockStack, Section, Heading} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const icon = root.createComponent(PaymentIcon, {name: 'visa'});
const cardNumber = root.createComponent(Text, {}, 'Visa ending in 4242');
const expiry = root.createComponent(Text, {appearance: 'subdued'}, 'Expires 12/2027');
const details = root.createComponent(BlockStack, {spacing: 'extraTight'});
details.append(cardNumber);
details.append(expiry);

const row = root.createComponent(InlineStack, {spacing: 'small', blockAlignment: 'center'});
row.append(icon);
row.append(details);

const heading = root.createComponent(Heading, {}, 'Payment method');
const section = root.createComponent(Section);
section.append(heading);
section.append(row);

root.append(section);
});

Anchor to Best practicesBest practices

  • Maintain the interior appearance of the icon: The branded portion of the payment icon meets the brand guidelines of the payment provider. Don't alter or overlay the icon content.
  • Maintain the border property of the icon: The border is designed to adapt to merchant branding and ensures a consistent appearance across the customer experience.
  • Use consistent sizing: The icon size is designed to display consistently across customer account pages. Avoid overriding the default dimensions.
  • Pair with identifying text: Display the payment method name or last four digits alongside the icon so customers can distinguish between multiple saved payment methods.

Anchor to LimitationsLimitations

  • Payment icons are limited to the predefined set of supported payment methods. Custom payment provider logos or icons aren't available.
  • The icon size and aspect ratio are fixed to maintain brand compliance. Custom sizing isn't supported.
  • Icons render as static images and don't support interactive states or animations.
Was this page helpful?