Embeddable Forms & Buttons for Nonprofits

In this article:
1. Types of Embeds
2. Creating an Embeddable Form or Button
3. Customizing Embeddable Forms and Buttons
4. Including Embeddable Forms and Buttons in Your Site
5. Backup Form Settings
6. Evaluating Embeds
7. Advanced


Please Note: These tools are only available for admins of 501(c)(3) and 501(c)(4) nonprofit organizations. If you are an admin for a 501(c)(3) or (c)(4) and also a political campaign, you will only see the embed option on your 501(c)(3)’s or (c)(4)’s Dashboard.

Embeddable forms and buttons are donation features you can add directly to your webpage so donors never have to leave your site. Our embeddable forms and buttons take advantage of our ActBlue Express universe of donors, meaning that if a supporter has previously donated on our platform and saved their contact and payment information with us, their information will be prefilled in the embed in your webpage!

All three steps of the donation flow — contribution amount, donor details, and payment information — will occur within your embeddable form or buttons! Donors will also be able to give with PayPal in an embed, just like with regular contribution forms, but at this point in time, embeds cannot accept Apple Pay. Because embeddable forms and buttons live in your website, most of the customization options for a regular contribution form do not apply, including titles and donation asks, pop-up recurring asks, smart recurring, thanks page content, goal thermometers, or brandings.

We designed our embeddable forms and buttons to be as easy to use as possible – the only technical knowledge you need to use them is a way to edit your webpage’s source code!


Types of Embeds

Embeddable forms:

Embeddable forms are contribution forms that are inserted directly into your webpage. The entire donation process, whether it be multistep for new donors or single-click for donors with saved payment accounts, takes place within the embeddable form in your site. This is what an embeddable form would look like in your webpage to an ActBlue Express donor:

Embeddable buttons:

Embeddable buttons are donate buttons you can insert into your webpage that launch a pop-up modal where the remainder of the contribution takes place. Embeddable buttons are a great option when your webpage has limited space, like in a navigation bar, menu, or hero area. This is what embeddable buttons would look like in your webpage:

And this is what the pop-up will look like when a donor clicks on a button. If a donor has an ActBlue Express account, their payment and contact information will already be filled in!


Creating an Embeddable Form or Button

On your Dashboard, click the “Create form” dropdown and select “Embed form.” Embeddable forms and buttons must be attached to a backup contribution form.

This will bring up the “Create a new form” pop-up, where you can fill in the “Form title” and “Web address” fields.

When you click “Create and continue” in the “Create a new form” pop-up, you will be brought to your form with the form editor open! The “Embed Generator” tab is where you can create your embeddable form or embeddable buttons, as well as copy the code you will need to put in your website.

Once you’ve clicked on the “Embed Generator” tab, enter any URLs where you want to embed a form or buttons in the “Allowed URLs” field, with each URL separated with a comma. You will only be able to host embeds in the URLs listed here, and the URLs must be secure (start with https)!

Any valid domain name you include will be allowed to host your embeddable forms and buttons. If you add "https://www.example.com," you’ll be able to include an embeddable form or button anywhere on example.com.

Once all of your URLs are entered, click “Publish” to save your work and continue creating your embeddable form or button!

Once you click “Publish,” the rest of your options will appear under “Step 2:”. Under “Type of Embed”, you can select either form or button!


Customizing Embeddable Forms and Buttons

When you select the type of embeddable object you would like to include in your site, you will have different options for customization!

Embeddable forms:

If you choose “Form,” you can customize the height of your embeddable form.

You can also create refcodes for your embeddable form, which we recommend to help you collect useful data about where your donations are coming from! Once you enter your custom refcode, we will include it in the code which you will use to embed the form in your webpage.

To pick the donation amounts on your embeddable form, go back to the main menu of the form editor and select the “Preset donation amounts” tab.

Embeddable forms will always include an “Other amount” option. Publish your changes when you’re done setting your amounts to save them!

Embeddable buttons:

If you choose “Button,” you can change the amounts and look of your embeddable buttons in the “Embed Generator” tab!

First, set specific amounts for your embeddable buttons in the “Preset amounts” field by separating each amount with a comma. If you’d like to include an “Other amount” option, check the box below the “Preset amounts” field!

You can either leave the buttons with just the amounts, or you can add a verb like “donate” to your embeddable buttons! If you’d like to include a verb, enter it in the “Button verb” field.

You can customize the color of your buttons and font by clicking the dropdown menus under “Color” and “Font Color.”

A hex color code is a series of numbers and letters (#XXXXXX) that specifies an exact color. We recommend using your brand’s specific hex colors for your button colors. This will make sure your embeddable buttons match the rest of your online presence and look professional! If you don’t know your hex color codes, you can use the color picker available in both dropdowns to select a shade that looks like one of your commonly used colors.

You can also change your font size and font weight – click on the dropdown beneath “Font Weight” to select between “Bold” and “Normal”!

You also have the option to change the border radius of your embeddable buttons in the “Border Radius” field. The border radius is the amount of rounding applied to the corners of the button. A border radius of 0 will result in sharp, 90 degree corners.

By clicking “Advanced,” you can use custom CSS to change how your buttons look. You can find more about this option in the "Advanced" section at the end of this article!

Finally, you can create custom refcodes for your embeddable buttons just like you can for embeddable forms!

Other embed settings:

Once you’re happy with how your embeddable buttons or embeddable form look, you have a few other options that will apply to your embed. Exit the “Embed Generator” tab to go back to your embed’s form editor.

In the “Form customization” tab, you can change all of the standard ActBlue- or AB Charities-provided text on your embeddable form or your embeddable button’s pop-up modal to Spanish! This includes an embeddable form’s buttons, donation block helper text, donor information fields, standard contribution rules, and ActBlue or AB Charities disclaimer. If you add verbs to your embeddable buttons, these will not be translated, because they are user-generated text.

In the “Recurring settings” tab, you can change the type of recurring ask that appears to donors on an embeddable form or in the embeddable button’s pop-up modal. You have the option to ask for an unlimited monthly contribution or a monthly contribution for a specific duration. You can also disable the recurring ask all together in this tab.

In the “Thanks and receipt” tab, you can write the text that will appear at the top of donors’ email receipts.

Remember to always publish changes you make in the form editor!


Including Embeddable Forms and Buttons in Your Site

Return to the “Embed Generator” tab to generate the code you need to embed a form or buttons in your webpage!

At the bottom of the tab, click “Generate Embed.”

The resulting pop-up will have the code you need to paste into the source code (HTML) of your webpage – you can insert it wherever you would like your embeddable buttons or form to appear! Our engineers have included some helpful info in this pop-up if you’re new to editing HTML.

Note: You can include multiple embeddable buttons and forms in a single webpage. The <script> tag only has to be included in the <head> once per page, and then you can copy and paste the different <div> tags where you would like your embeddable buttons and forms to display in your webpage.


Backup Form Settings

The rest of the form editor, which you can find under “Backup Form Settings,” does not apply to your embeddable form or embeddable buttons. These settings will apply to your backup form, a regular contribution form which your donors will be sent to if something prevents your embed from working.

There are limited customizations available for backup forms. It is most important to customize the title and donation ask on your backup form so donors know they are still giving to you even if the embed does not work and they leave your site. You can write these in the “Title, ask, and URL” tab.

To learn more about the rest of the settings for your backup form, check out our article on the basics of customizing forms. Backup forms do not support multiple recipients (Tandem Fundraising), tracking, or Entry Mode.


Evaluating Embeds

To see how your embed is doing, go to the “Contribution Forms” tab of your Dashboard toolbar like normal. The backup form for your embeddable form or buttons will be here with the rest of your forms, and you can even filter the list by “Embed” to find your form more quickly:

Select the Contributions or Amount total for your backup form to be taken to its Statistics page. You can also quickly get to the Statistics page when you’re previewing your backup form by selecting the “Stats” button in the form navigation bar:

You can also set up email alerts for contributions or refunds for both embeddable forms & buttons like normal in the “More” dropdown of the navigation bar! Data from both embeddable buttons and forms will also show up in the rest of your Dashboard data, like normal (including your Overview and all of the tabs in the Tools and Insights sections of the Dashboard toolbar).

More questions? You can schedule a call with one of our nonprofit experts here.


Advanced

Styling Embeddable Buttons and Forms

Custom styles can be applied to embeddable buttons using inline CSS via the data-ab-style property. Add this to the containing <div> just as you would other customization properties.

These instructions apply not only to the embeddable form, but also to the form that displays in the modal when an embeddable button is clicked. Since there are many more elements to style within the forms vs. a single <button> element, inline CSS is no longer practical. Instead, users who wish to style forms can link to a hosted custom stylesheet.

To style a form, follow these instructions: 

  1. Create your custom stylesheet and host it somewhere. We recommend uploading the stylesheet wherever the rest of your site is hosted. Alternatively, you can use a file hosting service. 
  2. On the same webpage where the embeds you wish to style are, find where you added the <script> tag to the source code (from the “Including Embeddable Forms & Buttons in Your Webpage” instructions). It is most likely in the <head> tag if you followed those instructions.
  3. Add the following <script> tag directly before the existing script tag: <script>window.actBlueConfig = {styleSheetHref: "https://[YOUR-URL-HERE].css"};</script>
  4. Be sure to replace the URL in the above script with the URL of your hosted stylesheet. 

Note: You can only add one custom stylesheet to each webpage. This means that if you have multiple embeds in a single webpage — whether they’re forms, buttons, or some combination — all of the forms will take the same custom styles.

Styling Shortcuts

All styles for the forms have been written in a way that is meant to be as easy to overwrite as possible. Class names are clear to read (inspired by BEM naming conventions), and there is little nesting, which means you won’t have to fight with specificity.

The stylesheet utilizes CSS Custom Properties (often called CSS variables), which provide a handy shortcut for customization. What makes CSS Custom Properties so handy is that they are dynamic: Their values can be changed later (for example, via a hosted custom CSS file), and this change will apply to all instances of the variable — even before the change was declared. 

This means that if in the default stylesheet it is declared that all buttons have a background color of var(--button-color), and the default value of var(--button-color) is cerulean blue, you can link to a custom stylesheet that declares var(--button-color) should be green, and all buttons that use that variable will now be green instead of cerulean blue.

CSS Custom Properties were used wherever we thought customization would be most desired. A list of all Custom Properties and their default values is shown below. To quickly customize forms, simply copy and paste the properties below into your custom hosted CSS file. (Be sure to wrap them in a :root { } selector.) Change the values as you desire to match your branding.

If the Custom Properties don’t quite get the job done, you can include additional CSS in the same file, targeting class names as you normally would. (These additional styles should be outside the :root { } selector.)

/* Colors */

--color-primary-brand: #00A8DF;

--color-text: #1F2A44;

--color-secondaryText: #657287;

--color-error: #DB0A5B;

--color-background: #FFF;

--color-subtle-background: #F7F8FA;

--color-success: #00AB4C;

--color-link: #0078AB;

/* Form options */

--form-padding: 1.5rem;

--border-radius: 4px;

/* Border around entire form */

--form-border: 1px solid #E6E9ED;

/* Form header and footer areas */

--form-header-footer-background: #FFF;

--form-header-footer-border-color: #E6E9ED;

/* Advance button: continue, donate, etc. */

--advance-button-background-color: var(--color-primary-brand);

--advance-button-color: #FFF;

--advance-button-border: 0;

--advance-button-font-weight: bold;

--advance-button-text-transform: none;

--advance-button-font-size: 1rem;

/* Selectable buttons: amounts, recurring, etc. */

--select-button-color-text: #4D5666;

--select-button-color-background: #CCD3DE;

--select-button-border: 0;

--select-button-font-weight: bold;

--select-button-text-transform: none;

--select-button-font-size: 1rem;

--select-button-selected-color-text: #FFF;

--select-button-selected-color-background: var(--color-primary-brand);

--select-button-selected-border: 0;

/* Input fields */

--input-background-color: #FFF;

--input-border-size: 1px;

--input-border-color: #CCD3DE;

--input-border-focus-color: var(--color-primary-brand);

--input-color: var(--color-text);

--input-label-color: var(--color-primary-brand);

--input-color-placeholders: #657287;

Note: CSS Custom Properties are supported in all modern browsers except for IE11. This means that if you choose to style your forms with Custom Properties, your custom styles will be visible in all modern browsers except IE11. IE11 forms will still be fully functional, they will simply use the default styles.

Tracking Embeds

Embed statistics can be found on the Statistics page for the associated contribution form. We can track visits and contributions.

Visits are tracked a little differently from standard ActBlue contribution form reporting. A visit to an embeddable form will be tracked by ActBlue if a potential donor interacts with an embeddable object. This interaction can either occur by clicking on an embeddable button and loading the modal or clicking anywhere on the embed form iframe. This data can be paired with your own website traffic data to get a full idea of your end-to-end conversion. 

You can pass a refcode into the embed, either through an attribute on the embed div or through a URL param.

Refcode inheritance:

  1. data-ab-refcode
  2. URL params:
    1. ab_refcode
    2. refcode
    3. ref

Refcode2 inheritance:

  1. data-ab-refcode2
  2. URL params:
    1. ab_refcode2
    2. refcode2

In order to track events, just add a function to your actBlueConfig object:

<script>
window.actBlueConfig = {onContribute: function(contribution) {
	   // tracking code goes here
}};
</script>

onContribute:

Called with contribution that includes:

  • amount: the amount, in cents, that was donated
  • email: the email of the donor
  • name: the name of the form (the slug that appears in the URL)
  • order_number: the ActBlue contribution order number
  • recurring: whether the donor chose recurring
  • refcode: the refcode of the contribution

actblue

actblue is a new global object on window that allows you to interact with ActBlue’s embeddable form functions from a host website. Provided by the actblue.js script tag.

actblue.requestContribution: new JavaScript function that accepts an object with amount and token and will open a modal to ask the user for a contribution. It returns a promise that resolves with a contribution if the user completes the contribution. The promise will reject if the user closes the modal without making a contribution.

actblueConfig:

Now accepts token as a way to set a default token for both the new API and for embeddable forms/buttons.

Paid for by ActBlue (actblue.com) and not authorized by any candidate or candidate's committee.
Contributions or gifts to ActBlue are not deductible as charitable contributions for Federal income tax purposes.