Customize Elements

Billflow Configuration API for customizing Billflow UI elements

Custom elements are possible starting in Billflow v4 beta. This page describes what is available for customization and how it works with examples.

Customizable UI elements

If the out of the box UI elements or text does not fully fit what you need, we've got you covered. This is the list of customizable UIs within the Billflow embeds.

Embed Elements

• Loader

Pricing Table

This customization will apply to the pricing page, plan picker and portal embed's change plan view.

• Pricing tiers

  • Pricing items

  • Select plan button

Checkout

This customization will apply to the pricing page's checkout modal and the checkout page embed.

• Checkout items

  • Price description

  • Price

The API

Configuration Structure

This is how you would create the structure and pass it into the Billflow configuration in the embed code. For each customElement mentioned, refer to the Custom element API section.

/**
* You would pass this custom elements object into billflowSettings
* with your embed code like the code fragment below.
*
* windows.billflowSettings = {
*    billing_page_id: 'xxxxxxxxxxxxxx',
*    options: {
*        customElements,
*    }
*/

const customElements = {
    elements: {
        pricing: { // define all customizable elements within the pricing table view here
            tiers: [
                {
                    name: "Basic", // your tier name to be customized
                    highlighted: {
                        element: customHighlightedBasic // your custom element for this tier's highlight
                    },
                    select: {
                        element: customSelectBasic // your custom element for select button for this tier.
                    },
                    prices: [
                        {
                            id: "price_1jw91203djejd23", // your Stripe price id displayed in this tier.
                            element: customPrice // your custom element for price item in the table.
                        }
                    ]
                }
            ]
        },
        checkout: { // define all customizable elements within the checkout view here
            prices: [
                {
                    id: "price_1jw91203djejd23", // your Stripe price id displayed in this checkout form.
                    description: {
                        element: customDescription, // your custom element for this price description
                    },
                    price: {
                        element: customPriceDisplay, // your custom element for this price display
                    }
                }
            ]
        }
    }
}

Custom element API

The interface to this custom element api is the same for each element level as follows:

{
    type: "div", // Required, the element wrapping element type.
    props: {}, // Optional, the props you'd like to pass to the wrapping element, such as className.
    render: (props) => { // Optional instead of children, allows you to return HTML with dynamic values.
        // prop are based on the current element being customized, 
        // data properties would be for example, the Stripe price
        // object if customzing a price item.
        console.log("Log the props to see what's available to you", props)
        const { unit_amount } = props 
        return `<div>${unit_amount} per month</div>`
    },
    children: "Static Text" // Optional instead of render, if you simply want to customize it with static text.
}

Examples

There are times when you want to customize the pricing information in the pricing table or even add extra elements to it. We will show you how to do it with the following examples.

Embed: Loader

Displaying the custom loader instead of our standard spinning circle

Pricing: Pricing Items

This section describes how you can customize the Pricing Items like the following example.

Customized Basic Tier (Left) Price Item Example

To customize a pricing item, you will first create a custom pricing item element like this.

/** Create the custom pricing item */
const CustomBasicPrice = {
  id: "price_HDa0zWHKXsY2sb", // replace with your own Stripe price id
  element: {
    type: "div",
    render: (props) => {
      // props is the price object in this case
      const { currency, unit_amount, priceRenderer } = props;
      const price = priceRenderer({amount: unit_amount ,currency})
      return `<div>
          ${price} <span>/ mo.</span>
          <i>Send up to 100,000 emails/mo before overages apply.</i>
        </div>`;
    }
  }
}

The id specifies the Stripe price item to customize within the tier.

The element is the custom element you will create.

Element properties
type	Required	string	a valid html type
props	Optional	object	any valid props for the html element, such as class, id, etc.
render	Required	function	a render function that will return the custom content as a string, basic html tags are will work. Stripe price object is passed to this function from Billflow, you can use the values to create the custom element.

Then you can pass the CustomBasicPrice to the config options.

/** Add the custom pricing item element
 to Billflow Config options like this. */
{
  billing_page_id: "5GNX3vmderQxoquHKUPe",
  options: {
    elements: {
      pricing: {
        tiers: [
          {
            name: "Basic",
            prices: [ CustomBasicPrice ]
          }
        ]
      }
    }
  }
}

Checkout the full example code here.

Pricing: Select Plan Button

This section describes how you can customize the Select Plan Button like the following example.

Customize the custom tier's Select Plan Button to open your Intercom chat

To customize a Select Plan Button, you will first create a custom element like this.

/** Create the custom Enterprise tier button */
const CustomEnterpriseButton = {
    element: {
      type: "button", // element type
      props: { // any valid props that Reactjs accepts
        onClick: (e) => {
          e.preventDefault();
          alert("Trigger a custom action, such as open intercom.")
        },
        id: "custom-button",
        className:
          "custom-button sc-csTbgd kglWtV bf-button __full _3NM6Cu2g7QjO6j4WSEYBGp _1RTkeWIbayZ7rSk_0XZ-hN",
        href: "#"
      },
      children: "Contact Us" // the child element to be rendered in the custom element.
    }
  }

Then you can pass the CustomEnterpriseTier to the config options.

/** Add the custom Enterprise tier button element
 to Billflow Config options like this. */
{
  billing_page_id: "5GNX3vmderQxoquHKUPe",
  options: {
    elements: {
      pricing: {
        tiers: [
          {
            name: "Enterprise", // the sb_tier name you want to customize
            select: CustomEnterpriseButton // customizing the select button for the Custom tier
          }
        ]
      }
    }
  }
}

Checkout the full example code here.

Checkout: Price Item description

This section describes how you can customize the Price Description within the checkout view like the following example.

Customized checkout price description highlighted in red

To customize a price description, you will first create a custom element like this.

const CustomPriceDescription = {
  "id": "price_HDa0zWHKXsY2sb",
  "description": {
    "element": {
      "type": "div",
      "props": {
        "className": "__custom-description"
      },
      "render": (props) => {
        return `<div>
              <div>Workflow: First 5 images</div>
              <div>Explanation of Isolation</div>
            </div>`
      }
    }
  }
}

Then you can pass the CustomPriceDescription to the config options.

/** Add the CustomPriceDescription element
 to Billflow Config options like this. */
{
  billing_page_id: "TMXnsJS2S7odVGyIW5Qc",
  options: {
    elements: {
      checkout: {
        prices: [
          CustomPriceDescription, // the custom price description element created above
        ]
      }
    }
  }
}

Checkout the full example code here.

Checkout: Price Item Price

This section describes how you can customize the Price within the checkout view like the following example.

Customized checkout price highlighted in red

To customize a checkout price, you will first create a custom element like this.

const CustomCheckoutPrice = {
  id: "price_HDa0zWHKXsY2sb", // replace with your own Stripe price id
  price: {
    element: {
      type: "div",
      props: {
        className: "__custom-amount"
      },
      render: (props) => {
        const { unit_amount, currency, formatters } = props;
        const amount = formatters.price({
          amount: unit_amount,
          currency
        });
        return `<div>
            <div>${amount} / mo.</div>
            <div>additional images</div> 
          </div>`;
      }
    }
  }
};

Then you can pass the CustomCheckoutPrice to the config options.

/** Add the CustomCheckoutPrice element
 to Billflow Config options like this. */
{
  billing_page_id: "TMXnsJS2S7odVGyIW5Qc", // replace with your own billing page id
  options: {
    elements: {
      checkout: {
        prices: [
          CustomCheckoutPrice, // the custom checout price
        ] 
      }
    }
  }
}

Checkout the full example code here.