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.
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.
This customization will apply to the pricing page, plan picker and portal embed's change plan view.
- Pricing tiers
This customization will apply to the pricing page's checkout modal and the checkout page embed.
- Checkout items
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
}
}
]
}
}
}
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.
}
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.
Displaying the custom loader instead of our standard spinning circle
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 ]
}
]
}
}
}
}
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
}
]
}
}
}
}
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
]
}
}
}
}
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
]
}
}
}
}