Requires:
- Charitable Pro 1.8.17+
DonationExpress opens your donation forms in a full-screen, theme-independent sheet when someone visits on a phone. Instead of rendering the form inside your theme (where a stray theme style can push a field off the edge, shrink a button, or break the payment area on a small screen), DonationExpress renders the campaign’s real donation form in its own clean layout that your theme cannot reach. The result is a form that looks the same on every phone, loads fast, and avoids theme conflicts.
The key idea is not “make the form responsive.” Charitable’s forms are already responsive. The problem DonationExpress solves is theme CSS interfering with the form and modal on mobile. DonationExpress fixes that by rendering the real form (real fields, real amounts, real gateways) in a separate document the theme physically cannot style.
DonationExpress is currently a Beta feature and is turned off by default. You turn it on per site in your donation form settings.
When you’d use it
- Your theme or page builder styles the donation form or modal in a way that looks broken on phones.
- You want a consistent donation experience across every device, regardless of the visitor’s phone or your active theme.
- You want the mobile form to load fast, without your theme’s scripts and styles loading alongside it.
- You accept donations from social media, email, or ads where most traffic is on mobile and first impressions matter.
Finding it
WordPress Admin > Charitable > Settings > General > Donation Form
Scroll to the DonationExpress settings. There are three:
- DonationExpress – turns the feature on and picks which donate triggers use it.
- DonationExpress Corner Style – the corner shape for buttons and inputs in the sheet.
- DonationExpress Receipt – what the sheet shows after a successful donation.
The Corner Style and Receipt settings are hidden until DonationExpress is set to something other than Off, since only the sheet uses them.
Turning it on
The DonationExpress setting has three options:
| Option | What it does |
|---|---|
| Off | DonationExpress is disabled. Donation forms display the normal way on mobile. This is the default. |
| Modal Donate Buttons Only | Only donate buttons that open a popup or modal use the sheet. Inline forms embedded directly on a page are left alone. |
| All Donation Forms | Every donate button, link, and inline form on a phone uses the sheet. |
Choose Modal Donate Buttons Only if you already like how your inline forms look on mobile and only want to fix the popup experience. Choose All Donation Forms if you want every mobile donation, however it is triggered, to go through the clean sheet.
DonationExpress only activates on mobile-width screens. On tablets and desktops your forms display exactly as they do today. The width cutoff is 768 pixels by default and is adjustable by a developer (see the developer reference below).
Styling the sheet
DonationExpress does not read anything from your theme, so it builds its look from your existing Charitable settings instead:
- Accent color comes from your donation form highlight color (Charitable > Settings > General > Donation Form). Buttons and selected states in the sheet use it.
- Logo comes from your email logo (Charitable > Settings > Emails). If one is set, it appears at the top of the sheet.
- Corner style comes from the DonationExpress Corner Style setting.
The Corner Style setting controls how rounded the buttons and inputs are:
| Corner style | Look |
|---|---|
| Sharp | Square corners (0 radius). |
| Rounded | Lightly rounded corners. This is the default. |
| Pill | Fully rounded, pill-shaped buttons and inputs. |
The receipt
After a donation goes through, DonationExpress can show one of three things. Set this with the DonationExpress Receipt option (added in Charitable Pro 1.8.17.1):
| Receipt style | What the donor sees |
|---|---|
| Celebration (clean, minimal) | A clean thank-you screen with a checkmark and a confetti animation, plus a Share button, an optional Make it monthly button, an optional Download PDF Receipt button, and a Close button. This is the default. |
| Detailed (clean, itemized breakdown) | The same clean celebration screen plus an itemized breakdown table (each campaign line and the total), for donors who want to see exactly what they gave. |
| Standard Receipt Page | The sheet closes and the donor lands on your normal, themed receipt page, exactly as they would without DonationExpress. |
The Celebration and Detailed receipts stay inside the sheet, so the donor never leaves the clean experience. A few buttons on those receipts only appear when the matching feature is available:
- Share uses the phone’s native share sheet, so donors can post to social or send a message with one tap.
- Make it monthly appears only when the Recurring Donations addon is active and the gift was a one-time donation. It reopens the sheet set to a monthly gift.
- Download PDF Receipt appears only when the PDF Receipts addon is active.
Previewing it without a phone
You do not need to grab a phone to see the sheet. As an administrator, open this URL in your browser (replace NN with a campaign ID):
https://yoursite.com/wp-admin/?charitable_action=preview-mobile-form&campaign_id=NNIt renders the same theme-free donation document DonationExpress shows on a phone, so you can check your colors, logo, and corner style on a full-size screen.
Tips
- DonationExpress renders the campaign’s real form, so any fields, suggested amounts, and gateways you have configured show up automatically. There is nothing to rebuild.
- If you use a caching or optimization plugin, make sure the
/charitable-give/path is excluded from caching. The sheet needs fresh security tokens on every load, the same as your normal donation and receipt pages. - Apple Pay and Google Pay work inside the sheet. Apple Pay still requires your domain to be verified with your payment gateway, the same as it does for the normal form.
- The feature is in Beta and off by default, so existing sites are never changed until you opt in.
Developer reference
DonationExpress renders the campaign’s real donation form inside a bare, theme-free document served from a dedicated endpoint, loaded in an iframe by a full-screen overlay on the parent page. A small postMessage bridge keeps the parent and the frame in sync through the donation and receipt flow.
Where it lives
| Piece | Location |
|---|---|
| Bootstrap | Charitable_Mobile (includes/mobile/class-charitable-mobile.php), started on init priority 9 |
| Helper functions | includes/mobile/charitable-mobile-functions.php |
| Settings and asset isolation | includes/mobile/charitable-mobile-hooks.php |
| Theme-free endpoint | Charitable_Mobile_Form_Endpoint(includes/endpoints/class-charitable-mobile-form-endpoint.php) |
| Templates | templates/mobile/form-mobile.php, templates/mobile/receipt-mobile.php |
| Assets | assets/css/charitable-mobile.css, assets/js/charitable-mobile-{sheet,bridge,receipt}.js |
Endpoints and URLs
The endpoint registers two rewrite rules and two query vars, and renders on template_redirect (priority 0).
| Purpose | Pretty permalinks | Plain permalinks |
|---|---|---|
| Donation form | /charitable-give/{campaign_id}/ | ?charitable_mobile_form={campaign_id} |
| In-sheet receipt | /charitable-give/receipt/{donation_id}/ | ?charitable_mobile_receipt={donation_id} |
The receipt document is access-controlled with charitable_user_can_access_donation(); a request for a donation the current visitor cannot access returns a 403.
Helper functions
| Function | Returns |
|---|---|
charitable_mobile_get_mode() | The resolved mode: off, modal, or always. |
charitable_mobile_is_enabled() | Whether the sheet is enabled at all (false when mode is off). |
charitable_mobile_get_breakpoint() | The mobile breakpoint in pixels (768 by default). |
charitable_mobile_get_form_url( $campaign_id, $args ) | The theme-free form URL. $args accepts amount and period. |
charitable_mobile_get_receipt_url( $donation_id ) | The theme-free in-sheet receipt URL. |
charitable_mobile_get_brand_tokens( $campaign_id ) | array{ accent, logo, radius } resolved from Charitable settings. |
charitable_mobile_get_receipt_style( $campaign_id ) | The resolved receipt style: confetti, detailed, or redirect. |
Filters
| Filter | Default | Purpose |
|---|---|---|
charitable_mobile_mode | Saved setting | Force the mode in code, for example per page or per campaign. Return off, modal, or always. |
charitable_mobile_is_enabled | Derived from mode | Final on/off gate. Return false to disable the sheet regardless of the mode. |
charitable_mobile_form_breakpoint | 768 | The max-width breakpoint, in pixels, that counts as mobile. |
charitable_mobile_brand_tokens | Resolved tokens | Override the accent, logo, and radiusused to style the sheet. |
charitable_mobile_asset_is_allowed | true for Charitable and gateway assets | Whitelist or exclude a specific style or script handle in the bare document. |
charitable_mobile_receipt_style | Saved setting | Vary the receipt style per campaign. Return confetti, detailed, or redirect. |
charitable_mobile_receipt_pdf_url | PDF Receipts URL or '' | Override the PDF button URL, or return '' to hide it. |
charitable_mobile_receipt_monthly_url | Monthly form URL or '' | Override the Make it monthly URL, or return ''to hide it. |
charitable_mobile_receipt_check_icon | Default checkmark markup | Swap the success icon shown on the receipt. |
Actions
| Action | Fires |
|---|---|
charitable_mobile_form_head | In the bare document’s <head>, where Charitable and gateway head assets are printed. |
charitable_mobile_form_footer | Before the bare document’s closing </body>, where footer scripts are printed. |
Admin preview
?charitable_action=preview-mobile-form&campaign_id=NN redirects an administrator (manage_options) to the theme-free form URL for a campaign, so the sheet can be reviewed on any screen size.
Customization examples
Force DonationExpress on for a single landing page:
add_filter(
'charitable_mobile_mode',
function ( $mode ) {
if ( is_page( 'give-now' ) ) {
return 'always';
}
return $mode;
}
);Raise the breakpoint so small tablets use the sheet too:
add_filter( 'charitable_mobile_form_breakpoint', fn() => 900 );Override the sheet’s accent color and corner radius:
add_filter(
'charitable_mobile_brand_tokens',
function ( $tokens, $campaign_id ) {
$tokens['accent'] = '#1e88e5';
$tokens['radius'] = '4px';
return $tokens;
},
10,
2
);Show the detailed receipt for one campaign, celebration everywhere else:
add_filter(
'charitable_mobile_receipt_style',
function ( $style, $campaign_id ) {
return 1234 === (int) $campaign_id ? 'detailed' : $style;
},
10,
2
);Allow an extra script handle into the theme-free document (for example a custom font loader):
add_filter(
'charitable_mobile_asset_is_allowed',
function ( $allowed, $handle ) {
if ( 'my-font-loader' === $handle ) {
return true;
}
return $allowed;
},
10,
2
);Related
- Customizing the donation form CSS – style the standard, in-theme donation form
- PDF Receipts – powers the Download PDF Receipt button on the sheet
- Recurring Donations – powers the Make it monthly button on the sheet
