Using custom extensions in the Affinity Home Page Builder

Custom extensions let you build and register your own UI components when using the Affinity Home Page Builder.

This guide explains how to render your custom extension on your Affinity Home Page.

Before you start

• You must build your custom extension before registering it. You can either upload the file directly in the Page Builder or host it externally.
• This guide applies only to the Affinity Home Page Builder . See Customizing the Affinity customer portal if you use the original next order page version of Affinity.
• You must contact the Recharge Support team to request access to this feature.

Overview

Custom extensions are Web Components that you:

• Register in the Affinity Page Builder
• Add as sections to portal pages
• Render in the customer portal

Step 1 - Build a custom extension

Build your custom extension as a Web Component. You can use any framework or library (React, Vue, Svelte, or vanilla JavaScript), as long as the final output is a Web Component.

Requirements

• HTTPS only: The customer portal runs in a secure context. The browser blocks non-HTTPS resources.

• Default export: Export the Web Component class as the default export. Do not use named exports.

• Load time: Ensure the extension loads within 5 seconds. The portal removes extensions that exceed this limit.

• Valid tag name: Use a tag name that matches the custom element defined in your component.

Example

class MyWidget extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<p>Hello from my custom extension!</p>`;
  }
}

export default MyWidget;

See custom extension example for a reference example.

Step 2 - Access the Affinity Home Page Builder

Access the page builder from your customer portal settings:

1. In the merchant portal, click Storefront, then select Customer portal.
2. Under Themes, click your theme’s Home page to expand the options.
3. From the expanded list, choose Recommended: Design your own custom home page under the Affinity customer portal theme.
4. Click Customize.

Step 3 - Register a custom extension

You can register a custom extension in one of the following ways:

• Upload the compiled JavaScript file directly (recommended)
• Provide a hosted file URL (alternative)

Upload a custom extension file (recommended)

You can upload your compiled extension file directly in the Page Builder instead of hosting it externally.

When you upload a file:

• Recharge stores the file in Shopify Admin → Content → Files
• The file is available across all Shopify themes in your store
• You do not need to host the file on a CDN or external service

To upload a file:

1. In your Recharge merchant portal, select Storefront and click Customer portal.
2. Click Customize under Affinity.
3. Depending on where you want the custom extension to render, select Header, Main column, or Right column, then click Add a section.
4. Select the Custom extensions tab.
5. Click Create a custom extension.
6. Upload your compiled JavaScript file.
7. Complete the remaining fields, then click Save.

Use a hosted file URL (alternative)

If you host your extension externally (for example, using a CDN or cloud storage), you can register it using a file URL.

To register using a file URL:

1. In your Recharge merchant portal, select Storefront and click Customer portal.
2. Click Customize under Affinity.
3. Depending on where you want the custom extension to render, select Header, Main column, or Right column, then click Add a section.
4. Select the Custom extensions tab.
5. Click Create a custom extension.
6. In the File URL field, provide an HTTPS URL to your compiled JavaScript file.
7. Complete the remaining fields, then click Save.

Custom extension fields

Use the table below to complete the custom extension fields.

Event behavior

When a configured event fires:

• The portal calls the component’s refresh() method
• The portal does not pass any data to refresh()
• The component fetches its own data

Step 4 - Add the extension to your page

After you register the extension, the Page Builder adds the extension as a section:

1. Click Add a section in the Page Builder.
2. Open the Custom extensions tab. You should now see your custom extension on this tab.
3. Select your extension to add it to the home page.
4. Click and drag the custom extension section to reposition it on the home page.

Step 5 - Test and publish

New extensions start in test mode:

• The portal shows them only in preview
• Customers cannot see them

Once you've verified the extension works as expected, make the extension visible:

1. Click on the custom extension section.
2. Enable Make this extension visible to customers.
3. Click Done to publish your changes.