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. Embedding Forms and Buttons in Your Website’s Code
  5. Using the WordPress Plugin for Embeddable Forms and Buttons
  6. Backup Form Settings
  7. Evaluating Embeds
  8. 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, payment information, and donor details — 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, some of the customization options for a regular contribution form do not apply, including titles and donation asks, goal thermometers, or brandings. You can preset your donation amounts, change the AB Charities-provided text to Spanish, add a custom field or radio button, ask for recurring contributions, customize the recurring upsell or the Smart Boost upsell, or write a custom recurring pitch for your embeddable forms and buttons! 

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! And if your website is on WordPress, we have a plugin that enables you to embed a form or button on your site in only a few clicks. Read on to learn more.

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!

At any point, you will be able to see a preview of your embeddable form or buttons on the right side of your screen. Make sure to click “Publish” to preview the most up-to-date version of your form or buttons!

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 will see a “fixed height” box that is unchecked. By default, the embeddable form height is dynamic, which means donors will see the entire form on your website (the form will not have an internal scroll). If you prefer to set your own form height (which may create internal scrolling), check the “Fixed height” box and change the number in the “Height” field.” 

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, if you would like to ask your supporters for recurring donations, choose the type of recurring ask you would like to present to your donors in the “Recurring” dropdown menu. The default recurring setting for embeddable buttons is “Donor Decides,” which gives donors the option to make their contribution one-time or recurring: 

If you select “Recurring,” your embeddable buttons will only accept recurring donations, so there will be no one-time donation option in the pop-up modal. Since the donor will have already chosen to give a recurring contribution by clicking on one of your embeddable buttons, there will also be no recurring upsell after the donation. Your embeddable buttons will look something like this, so it is clear to your donors that they will be making a recurring contribution: 

If you select “One-Time” from the “Recurring” dropdown menu, your embeddable buttons will only accept one-time contributions. Your donors will not see a recurring donation option in the pop-up modal, and they will not see an additional recurring upsell after they donate, even if you enable the upsell in the “Recurring settings” tab of the form editor.

Then, 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, the recurring option on your embeddable form or button pop-up modal, all ActBlue- or AB Charities-provided text in the recurring or Smart Boost upsell, standard contribution rules, and the 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 “Form customization” tab, you can also add a custom input —a text field for donors to fill out, or radio buttons for donors to select — so you can collect additional information from your supporters on either your embeddable form or your embeddable button’s pop-up modal. You can learn more about this tool
here. Please note: For the most part, organizations will not need to gather more information and add steps to the giving process.

In the “Recurring settings” tab, you can customize your recurring settings. Please note: Some recurring settings for embeddable buttons live in the “Embed Generator” tab. If you selected “One-Time” or “Recurring” in the menu in that tab, the following list of recurring customizations will not apply to your buttons, and your supporters will not see any recurring upsell after they donate. 

If you are creating an embeddable form, or embeddable buttons with the “Donor Decides” option selected in the “Embed Generator” tab, read on to learn about your customization options in the “Recurring settings” tab of the editor. 

In the “Recurring” tab’s “Monthly recurring donations” dropdown menu, you can change the type of recurring ask and recurring upsell your donors see:

  • If you select “Disabled,” there will be no recurring option in the embeddable object or recurring upsell. 
  • If you select “Specified duration,” your donors will see a recurring option on your embeddable object, and if they choose to make a one-time contribution, they will see a recurring upsell after they donate. In both cases, they will be prompted to customize the number of months their contribution will recur for.
  • If you select “Unlimited,” your donors will see a recurring option in the embeddable object, and if they choose to make a one-time contribution, they will see a recurring upsell after they donate. They will not be prompted to specify a number of months, and their contribution will recur until they cancel it or change the recurring schedule in their ActBlue Express account.  
  • If you select “Unlimited + Smart Options,” your donors will see a recurring option in the embeddable object, and if they choose to make a one-time contribution, they will see a recurring upsell after they donate suggesting multiple smaller recurring amounts. They will also have the option to set their own amount! To learn more about Smart Recurring and see examples, read this article. Please note: Smart Options is the only Smart Recurring option for embeddable forms and buttons. 

Please note: If you select “Smart Boost” in the “Post-donation upsells” tab, your donors will not see any recurring upsell, even if you have one of the above options enabled.

In the “Pop-up recurring ask threshold” box in the “Recurring settings” tab, you can create a donation threshold for who should get a recurring upsell if you are using the “Specified duration” or “Unlimited” setting described above. Supporters who give a one-time donation smaller than the amount you enter in this field will see a recurring upsell asking them to make a monthly donation of the same amount that they just gave as a one-time donation. If you want any of your donors to see a recurring upsell, you must enter an amount in the “Pop-up recurring ask threshold” box. 

Quick tip: click “Publish” to preview what the recurring ask will look like on your embeddable form or embeddable button’s pop-up modal! 

You can also manage other recurring settings in this tab. If you select “Recurring pitch” in the “Promote recurring donations” dropdown menu, you can write a custom recurring pitch to highlight the recurring option on your embeddable forms and embeddable button pop-up modals. 

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

In the “Post-donation upsells” tab, you can select the type of upsell you would like your donors to see after they give an initial contribution. If you select “Recurring,” customize these settings in the “Recurring settings” tab (and if you’re creating embeddable buttons, in the “Embed Generator” tab). 

If you select “Smart Boost,” an upsell will present donors with multiple options to increase their initial donation, giving your supporters the choice to double their contribution or increase it by a smaller amount than the amount they just gave. You can customize the Smart Boost upsell title and ask to let donors know why you would like them to increase their impact in the “Post-donation upsells” tab.

Donors will still see the Smart Boost upsell if they make a recurring donation through one of your embeddable buttons or your embeddable form. However, Smart Boost will not add on to the recurring contribution amount, only the initial contribution. So if they donate a recurring amount of $5, and then choose to increase their donation by $1 in the Smart Boost upsell, their first charge will be for $6. But their future recurrences will be $5! 

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

Embedding Forms and Buttons in Your Website’s Code

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.

Using the WordPress Plugin for Embeddable Forms and Buttons

If your website is hosted on WordPress, you can embed your contribution form or donation buttons in a matter of clicks. Just download our “ActBlue Contributions” plugin in the WordPress plugin directory and search for the “ActBlue Embed” or “ActBlue Buttons” blocks in the WordPress editor. Full instructions can be found in this support article!

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.


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: If you copy and paste these properties, watch out for line breaks. Additionally, 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:

window.actBlueConfig = {onContribute: function(contribution) {
	   // tracking code goes here


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 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.


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

© 2009 PayPal, Inc. All rights reserved. PayPal and the PayPal logo are trademarks of PayPal, Inc. Other names, trademarks and brands are the property of their respective owners.

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.