PricingAPI DocsLoginGet Started

Widgets Guide

Learn everything about creating, customizing, and embedding referral signup widgets on your website.

What are Widgets?

Think of widgets like a sign-up form that you can place anywhere on your website. When someone visits your site and sees your widget, they can enter their email address to join your referral program. Once they sign up, they get their own special referral link that they can share with friends.

What widgets do: They collect email addresses from visitors who want to participate in your referral program. Each person who signs up becomes a "referrer" and can earn rewards when their friends make purchases.

What widgets don't do: Widgets don't automatically track purchases or send rewards. You still need to integrate tracking on your website (using our tracking code) to record when someone makes a purchase after clicking a referral link.

Widget Types

Mouthfully offers four different widget styles. Each one is designed for different use cases and website layouts. You can create multiple widgets and use different ones on different pages of your website.

Compact Form

This is the smallest and simplest widget. It's perfect for sidebars, footers, or anywhere you have limited space. It shows just an email input field and a submit button, with optional heading and paragraph text above it.

Best for:

  • Sidebars on blog posts or articles
  • Footer sections
  • Pop-ups or modals
  • When you want a minimal, unobtrusive signup form

Form with USPs

This widget includes custom "Unique Selling Points" (USPs) that you can write yourself. USPs are short bullet points that explain why someone should join your referral program. For example: "Earn $10 for every friend you refer" or "No credit card required".

This widget is larger than the compact form and includes space for a heading, paragraph, your custom USPs (displayed with icons), the email form, and a submit button.

Best for:

  • Dedicated referral program pages
  • Landing pages where you want to explain benefits
  • When you want to highlight specific rewards or features
  • Homepage sections with more space

Form with CTA

This widget includes an additional call-to-action (CTA) link that you can customize. It's similar to the Form with USPs, but includes an extra button or link that you can point to any URL you want. For example, you could link to your full referral program terms, a detailed rewards page, or your main website.

You can customize both the text and the URL of this CTA link. The link appears below the main form, separate from the submit button.

Best for:

  • When you want to provide additional information or links
  • Linking to terms and conditions or detailed program info
  • Directing users to related pages on your website

Email Form Only

This is the most minimal widget - it shows only an email input field and submit button, with no heading, paragraph, or other text. It's perfect when you want the absolute smallest footprint possible.

Best for:

  • Very tight spaces where every pixel counts
  • When you already have explanatory text elsewhere on the page
  • Minimalist design preferences

Creating a Widget

1

Navigate to Widgets Tab

In your dashboard, click on the "Widgets" tab in the left sidebar. This is where you'll see all your existing widgets and create new ones.

2

Click "Create Widget"

You'll see a button labeled "Create Widget" or a plus icon. Click it to start creating a new widget.

3

Choose Widget Type

You'll see previews of all four widget types. Hover over each one to see a larger preview, then click on the widget type you want to use. Remember, you can create multiple widgets later, so don't worry about choosing the "perfect" one right away.

Tip: You can always create another widget later if you want to try a different style. Your plan determines how many widgets you can create (free plans typically allow 1-2 widgets, paid plans allow more).

4

Widget is Created

Once you select a widget type, your widget is automatically created! You'll now see it in your widgets list, and you can start customizing it right away. The widget starts with default colors, fonts, and settings, which you can change to match your brand.

Widget Customization Options

After creating a widget, you can customize almost every aspect of its appearance. All customization options are organized into collapsible sections. Click on any section to expand it and see the options.

Colors

Colors control the visual appearance of different parts of your widget. You can set colors using hex codes (like #6366f1) or use a color picker if your browser supports it.

Primary Color

The main brand color used for buttons and accents. This is typically your company's primary brand color.

Secondary Color

A complementary color used for secondary elements. Often a lighter or darker shade of your primary color.

Background Color

The background color of the entire widget. Usually white or a very light color for readability.

Text Color

The default text color for body text. Typically dark gray or black for good contrast.

Button Color

The background color of the submit button. Often matches your primary color.

Button Text Color

The color of text on the button. Usually white or a light color for contrast against the button background.

Heading Color

The color of heading text. Can be the same as text color or a different shade for emphasis.

Paragraph Color

The color of paragraph/body text. Often a medium gray for softer appearance than heading text.

Fonts

Fonts control the typeface (the style of letters) used in your widget. You can choose different fonts for headings and body text.

Heading Font

The font family used for headings (like "Join Our Referral Program"). Common choices include serif fonts (like Georgia) for a classic look, or sans-serif fonts (like Inter) for a modern look.

Body Font

The font family used for paragraph text and form inputs. Usually a clean, readable sans-serif font like Inter or Arial.

Note: Fonts must be available on the visitor's device or loaded from a web font service. If you use a custom font, make sure it's loaded on your website where the widget is embedded.

Sizing

Sizing controls the dimensions and spacing of elements in your widget. All sizes can be specified in pixels (px) or other CSS units.

Heading Font Size

How large the heading text appears. Typically between 16-32 pixels. Larger sizes create more emphasis.

Paragraph Font Size

How large the paragraph text appears. Typically 14-16 pixels for good readability.

CTA Font Size

How large the call-to-action button text appears. Usually 14-18 pixels.

CTA Padding

The space inside the button around the text. Format: "12px 24px" means 12px top/bottom, 24px left/right. More padding makes the button larger and easier to click.

Input Padding

The space inside the email input field. Format: "12px 16px" means 12px top/bottom, 16px left/right.

Container Padding

The space around the entire widget content. This creates breathing room between the widget edges and its content.

Border Radius

How rounded the corners are. 0px = sharp corners, 8px = slightly rounded, 16px+ = very rounded. Affects buttons, inputs, and the widget container.

Spacing

The space between major elements (like between heading and paragraph, or between form fields).

Layout

Layout options control the visual style of buttons and input fields.

Button Style

Three options:

  • Solid: A filled button with your button color as the background (most common)
  • Outline: A button with just a border, no fill (more subtle)
  • Gradient: A button with a gradient effect from one color to another (more eye-catching)

Input Style

Three options:

  • Standard: A traditional input field with a visible border
  • Minimal: A cleaner look with a subtle bottom border only
  • Bordered: A more prominent border for emphasis

Text Content

Text content is the actual words that appear in your widget. You can customize all the text to match your brand voice.

Heading

The main title that appears at the top of your widget. Examples: "Join Our Referral Program" or "Earn Rewards Today".

Paragraph

A short description that appears below the heading. Explains what the referral program is or why someone should join.

CTA Text

The text on the submit button. Examples: "Get Started", "Sign Up", "Join Now". Keep it short and action-oriented.

Tip: For "Email Form Only" widget type, these text fields are hidden because that widget type doesn't display headings or paragraphs - just the form itself.

Logo

You can upload your company logo to display at the top of your widget. This helps with brand recognition.

How to add a logo:

  1. Click the "Upload" button in the Logo section
  2. Select an image file from your computer (PNG, JPG, or SVG formats work best)
  3. The logo will appear in the preview immediately
  4. Make sure your logo is clear and not too large (recommended: under 200KB file size)

What this does: Displays your logo at the top of the widget for brand consistency.

What this doesn't do: The logo doesn't link anywhere or have any functionality - it's just for display.

Custom USPs (Unique Selling Points)

USPs are short bullet points that highlight the benefits of joining your referral program. They only appear in the "Form with USPs" widget type.

How to add USPs:

  1. Click the "Add USP" button or the plus icon
  2. Type your USP text (e.g., "Earn $10 per referral")
  3. Press Enter or click "Add" to save it
  4. Repeat to add more USPs (you can add multiple)
  5. Click the X icon next to any USP to remove it

Best practices: Keep USPs short (one line), focus on benefits, and use clear, simple language. Examples: "No credit card required", "Track your referrals in real-time", "Get paid within 24 hours".

CTA Link (Form with CTA only)

This option is only available for the "Form with CTA" widget type. It adds an additional link below the main form.

CTA Link Text

The text that appears on the link. Examples: "Learn more", "View terms", "See full program details".

CTA Link URL

The web address the link points to. Must be a full URL starting with "http://" or "https://". Example: https://yoursite.com/referral-terms

Note: This link is separate from the main submit button. Users can click it to visit another page without submitting the form.

Live Preview

How Preview Works

The preview window shows you exactly how your widget will look to visitors on your website. It updates instantly and automatically as you make changes to any customization option.

What this means: You don't need to click a "Preview" button or save your changes to see them. As soon as you change a color, font size, or text, the preview updates immediately. This makes it easy to experiment and see what looks best.

Important: The preview shows your widget exactly as it will appear when embedded. However, changes you make are not live on your website until you click "Save & Publish". The preview is just for testing and design purposes.

Embedding Widgets on Your Website

Getting Your Embed Code

1

After customizing your widget, scroll down to the "Embed Code" section below the preview.

2

You'll see a code block with an iframe tag. This is your embed code.

3

Click the "Copy" button to copy the entire embed code to your clipboard.

Adding to Your Website

Once you have the embed code, you can add it to any page on your website. The process depends on your website platform:

WordPress

  1. Edit the page or post where you want the widget
  2. Add a "Custom HTML" or "Code" block
  3. Paste your embed code
  4. Save and publish the page

Shopify

  1. Go to Online Store → Themes → Actions → Edit code
  2. Find the template file for your page (e.g., page.liquid)
  3. Add the embed code where you want the widget to appear
  4. Save the file

Custom HTML/JavaScript

  1. Open your HTML file in a code editor
  2. Find where you want the widget to appear
  3. Paste the embed code directly into the HTML
  4. Save and upload the file to your server

Important Notes:

  • The embed code never changes - once you add it to your website, you don't need to update it
  • When you customize your widget and click "Save & Publish", the changes appear automatically on your website
  • You can use the same widget on multiple pages - just paste the same embed code
  • You can create different widgets for different pages if you want different styles

Widget Revisions (Version History)

How Revisions Work

Every time you click "Save & Publish", Mouthfully automatically saves a snapshot of your widget settings. This is called a "revision". Think of it like a backup or version history.

What this means: If you make changes to your widget and later decide you liked the old version better, you can restore a previous revision to go back to those settings.

Viewing Revisions

Below the embed code section, you'll see a "Revision History" section. This shows your recent widget versions, with the most recent at the top.

Each revision shows:

  • The date and time it was saved
  • A "Restore" button to go back to that version

Restoring a Revision

  1. Find the revision you want to restore in the list
  2. Click the "Restore" button next to it
  3. Confirm that you want to restore (this will replace your current settings)
  4. Your widget settings will immediately revert to that previous version
  5. The restored version becomes your new "current" version

Revision Limits:

Mouthfully keeps a maximum of 3 revisions per widget. When you create a 4th revision, the oldest one is automatically deleted. This keeps the list manageable and ensures you always have access to your 3 most recent versions.

What revisions save: All your customization settings (colors, fonts, text, sizing, etc.) are saved in each revision. When you restore, everything goes back to exactly how it was.

Save & Publish

What Happens When You Publish

When you're happy with your widget customization and ready to make it live, click the "Save & Publish" button at the bottom of the customization form.

What "Save & Publish" does:

  • Saves all your customization settings to the database
  • Creates a new revision (if you haven't reached the 3-revision limit)
  • Updates the live widget immediately - changes appear on your website right away
  • Shows a success message confirming the save

Important:

The preview window shows your changes instantly, but those changes are only visible to youuntil you click "Save & Publish". Visitors to your website will see the old version until you publish.

After Publishing

Once published, your widget updates appear on your website within seconds. You don't need to change the embed code or update anything on your website - it happens automatically.

Widget Limits by Plan

Different subscription plans allow different numbers of widgets. This limit determines how many separate widgets you can create and customize.

How to check your limit: When you try to create a new widget, if you've reached your limit, you'll see a message explaining that you need to upgrade your plan to create more widgets.

Note: You can delete old widgets to free up space for new ones, or upgrade your plan to increase your widget limit. Check your plan details in the Billing section for specific limits.

Common Questions

Can I use the same widget on multiple pages?

Yes! You can paste the same embed code on as many pages as you want. When you update the widget, it updates everywhere it's embedded.

Do I need to update the embed code when I customize my widget?

No! The embed code never changes. Once you add it to your website, you never need to touch it again. All customization changes appear automatically when you click "Save & Publish".

Can I create different widgets for different pages?

Yes! As long as you haven't reached your widget limit, you can create multiple widgets with different styles, colors, or text. Each widget has its own embed code.

What happens if I delete a widget?

If you delete a widget, it's permanently removed and cannot be recovered. The embed code will stop working on any pages where it was used. Make sure you really want to delete it before confirming.

Can I change the widget type after creating it?

No, the widget type (Compact Form, Form with USPs, etc.) cannot be changed after creation. If you want a different type, you'll need to create a new widget. However, you can customize all other aspects (colors, fonts, text, etc.) as much as you want.

Why don't my changes appear on my website immediately?

Changes only appear on your live website after you click "Save & Publish". The preview window shows changes instantly, but those are just for your reference. Always click "Save & Publish" when you're ready to make changes live.