Introduction to Custom Blocks

Overview

Custom Blocks in Superfans let developers create fully customizable app blocks using HTML, CSS, and JavaScript. These blocks are powered by our SDK, which provides access to app data, actions, and events — allowing your blocks to be dynamic, interactive, and seamlessly integrated with the app experience.

They’re designed to give you full control over styling and logic — so you can build the exact app experiences you want.

With Custom Blocks, you can design anything from a dynamic banner to an interactive product section — all directly within the Superfans builder.

Why Custom Blocks Matter

While pre-built blocks cover most use cases, they have design and functional limitations.

Custom Blocks give you the freedom to implement your own code, connect APIs, and render dynamic data exactly how you want.

Here’s what you can achieve:

• Create custom designs that align with your brand.
• Add advanced interactions using JavaScript.
• Integrate external data sources or APIs directly into your app section.

Types of Custom Blocks

Superfans supports two types of Custom Blocks:

1. HTML/CSS/JS Blocks

• Fully customizable using HTML, CSS, and JavaScript.
• Ideal for developers who want complete control over layout, styling, and interactivity.
• Can connect to the Superfans SDK or external APIs for dynamic content.
• Recommended method for most customizations as it is flexible, stable, and fully supported.

There are 3 types of HTML blocks:

Full Screen Block

• Appears as a complete screen on the app.
• Example: Launching a Holiday Promotion screen.

Embedded Block

• Placed directly within the app layout and scrolls naturally with the page.
• Can be embedded in:
  • Homepage / Landing Pages
  • Product Listing Page
  • Product Page
  • Cart Page
  • Account Page

Popup Block

• Appears as an overlay on top of the current screen.
• Trigger types:
  • Center popup
  • Bottom popup

2. URL-Based Blocks

• Built by creating a template in Shopify and appending it in the URL using a template name parameter.
• Superfans loads the content of the URL as a block inside the app.

Limitations:

• Less flexible for styling/interactions
• Harder to debug
• Performance depends on Shopify + network latency
• Not recommended unless reusing a Shopify template is necessary

Recommendation:
Use HTML/CSS/JS Custom Blocks whenever possible. URL-based blocks are primarily for very specific legacy use cases.

How It Works

A Custom Block is a self-contained component that includes:

• HTML for structure
• CSS for styling
• JavaScript for interactivity and SDK integration

The SDK allows your block to:

• Access app data
• Trigger actions (e.g., navigation, add to cart)
• Listen to app events (e.g., login, cart updates)

Development Workflow:

You can:

1. Create a new Custom Block in the Low Code Builder.
2. Add your HTML, CSS, and JS directly in the editor.
3. Use Superfans SDK methods to fetch or manipulate app data.
4. Preview changes in real-time.
5. Save and publish to push it live.

---

Who Can Use Custom Blocks

If you're comfortable with front-end web development, the workflow is intuitive and flexible.

---

Use Cases

Examples of what developers commonly build:

• Dynamic product grids fetching live Shopify data
• Custom banners or sliders with JS-powered transitions
• Personalized recommendation sections using APIs
• Interactive elements like countdown timers or user points progress bars

Each block can be customized to align with the app’s UX while keeping code modular.

---

Best Practices

• Keep your code modular and reusable
• Avoid heavy scripts to maintain fast load times
• Test thoroughly across multiple devices
• Use descriptive class/function names
• Prefer Superfans APIs over raw network calls

Following these ensures your blocks remain scalable and maintainable.

---

Next Steps

Now that you understand how Custom Blocks work, continue to:

👉 Building Your First Custom Block →
Learn how to create your first block and add your HTML, CSS, and JS.[Build your first block]