Embeddable Elements
Embedded elements are UI elements you can embed into your web app to create a whitelabel referral experience within your own user portal. Referral links are auto-generated for your users.
Last updated
Was this helpful?
Embedded elements are UI elements you can embed into your web app to create a whitelabel referral experience within your own user portal. Referral links are auto-generated for your users.
Last updated
Was this helpful?
Embeddable elements are one-line-of-code inline block elements that you can insert into your own "Refer and Earn" webpage
To change basic styles, update elements from the Campaign Editor.
Embeddable elements can be fully customized using HTML data attributes.
Some embeddable elements have two UI states that will display differently to participants and non-participants
Important Notes:
To force re-rendering, call growsurf.initElements()
, which destroys and recreates all embeddable elements in the DOM.
The embedded form will display the participant's unique referral link and social sharing options.
If the participant is not signed in, then the embedded form will display a signup form.
Example usage:
This is the bare minimum code required to display this element.
Data attributes:
HTML Attribute
Data Type
Description
data-grsf-block-form
N/A
(Required) This attribute turns any HTML element into an embedded form.
data-grsf-email
String
(Optional) If provided with a valid email address, a new participant will be created, or an existing participant will be returned — and their unique referral link and social share buttons will be displayed.
data-grsf-first-name
String
(Optional) If provided with data-grsf-email
, then this value will be saved as the new participant's first name property.
If the participant already exists in the referral campaign, then this attribute will be ignored.
data-grsf-last-name
String
(Optional) If provided with data-grsf-email
, then this value will be saved as the new participant's last name property.
If the participant already exists in the referral campaign, then this attribute will be ignored.
data-grsf-metadata
Object
If the participant already exists in the referral campaign, then this attribute will be ignored.
data-grsf-gdpr-paragraph-style
Object
(Optional) Adds inline styles to the GDPR consent paragraph text (if GDPR enabled).
data-grsf-gdpr-checkbox-style
Object
(Optional) Adds inline styles to the GDPR consent checkbox text (if GDPR is enabled).
data-grsf-label-style
Object
(Optional) Adds inline styles to the form input labels.
data-grsf-button-style
Object
(Optional) Adds inline styles to any button elements.
data-grsf-link-style
Object
(Optional) Adds custom styles to any link elements.
data-grsf-social-buttons-layout-theme
Number
(Optional) Set the theme of the social buttons. Choose from the following options:
1
- Color buttons with text
2
- Gray buttons with text
3
- Color icons
4
- Gray icons
Example: data-grsf-social-buttons-layout-theme="2"
.
data-grsf-field-*-label
String
(Optional) Sets the label text for the targeted input field.
Replace *
with one of the following options: email
, first-name
, last-name
, custom-field
.
Example: data-grsf-field-first-name-label
.
data-grsf-field-*-placeholder
String
(Optional) Sets the placeholder text for the targeted input field.
Replace *
with one of the following options: email
, first-name
, last-name
, custom-field
.
Example: data-grsf-field-first-name-placeholder
.
data-grsf-*-button-style
Object
(Optional) Adds inline styles to the targeted social share button.
Replace *
with one of the following options: email
, facebook
, twitter
, threads
, bluesky
, pinterest
, linkedin
, sms
, messenger
, whatsapp
, wechat
, telegram
, reddit
, tumblr
, qrcode
.
Example: data-grsf-facebook-button-style
.
data-grsf-*-button-text
String
(Optional) Sets the text of the targeted social share button.
Replace *
with one of the following options: email
, facebook
, twitter
, threads
, bluesky
, pinterest
, linkedin
, sms
, messenger
, whatsapp
, wechat
, telegram
, reddit
, tumblr
, qrcode
.
Example: data-grsf-facebook-button-text
.
data-grsf-*-button-message
String
(Optional) Sets the pre-populated message of the targeted social share button.
Replace *
with one of the following options: email
, facebook
, twitter
, pinterest
, sms
, whatsapp
, reddit
, tumblr
.
Example: data-grsf-facebook-button-message
.
Include {{shareUrl}}
to dynamically set the participant's Share URL within the pre-populated message.
To change the subject line for email messages, set data-grsf-email-button-subject
.
data-grsf-share-instructions
String
(Optional) Sets the text of the share instructions (these instructions are only visible when the participant is in the auth state).
data-grsf-share-instructions-style
Object
(Optional) Adds inline styles to the share instructions.
data-grsf-share-url-input-style
Object
(Optional) Adds inline styles to the Share URL input field.
data-grsf-copy-link-button-layout-theme
Number
(Optional) Set the theme of the "Copy Link" button. Choose from the following options:
1
- Text button
2
- Icon style #1
3
- Icon style #2
4
- Icon style #3
Example: data-grsf-copy-link-button-layout-theme="3"
.
data-grsf-copy-link-button-text
String
(Optional) Sets the text of the 'Copy Link' button.
data-grsf-copy-link-button-style
Object
(Optional) Adds inline styles to the 'Copy Link' button.
data-grsf-copy-link-container
Object
(Optional) Adds inline styles to the container of the input box and Copy Link button.
data-grsf-redirect-url
String
(Optional) Redirects to the given URL upon form submission
The embedded invite is an element that lets a participant send a bulk email invite out to a list of email addresses. It will only be displayed to signed-in participants.
Example usage:
This is the bare minimum code required to display this element.
Data attributes:
HTML Attribute
Data Type
Description
data-grsf-block-invite
N/A
(Required) This attribute turns any HTML element into an embedded invite.
data-grsf-email
String
(Optional) The email of the participant to display the invite element for. If the participant does not yet exist within the campaign, they will be newly added.
data-grsf-instructions-text
String
(Optional) Sets the text of the invite instructions.
data-grsf-instructions-style
Object
(Optional) Adds inline styles to the invite instructions.
data-grsf-label-style
Object
(Optional) Adds inline styles to the form input labels.
data-grsf-input-style
Object
(Optional) Adds inline styles to the email address input field.
data-grsf-input-placeholder-text
String
(Optional) Sets the placeholder text of the email address input field.
data-grsf-preview-link-text
String
(Optional) Sets the text of the preview link. If no value is provided, the button text will default to the GrowSurf window invite preview link text.
data-grsf-preview-subject-label
String
(Optional) Sets the label text for the email subject line in the preview section.
data-grsf-preview-subject-placeholder
String
(Optional) Sets the placeholder text for the email subject line in the preview section.
data-grsf-preview-subject
String
(Optional) Sets the pre-populated value for the email subject line in the preview section.
data-grsf-preview-subject-style
Object
(Optional) Adds inline styles to the preview subject input field.
data-grsf-preview-message-label
String
(Optional) Sets the label text for the email message body in the preview section.
data-grsf-preview-message-placeholder
String
(Optional) Sets the placeholder text for the email message body in the preview section.
data-grsf-preview-message
String
(Optional) Sets the pre-populated value for the email message body in the preview section.
Include {{shareUrl}}
to dynamically set the participant's Share URL within the pre-populated message.
data-grsf-preview-message-style
Object
(Optional) Adds inline styles to the preview message input field.
data-grsf-link-style
Object
(Optional) Adds inline styles to any link elements. If no value is provided, the link styles will inherit from the GrowSurf window link styles.
data-grsf-submit-button-text
String
(Optional) Sets the text of the submit button. If no value is provided, the button text will default to the GrowSurf window invite submit button text.
data-grsf-button-style
Object
(Optional) Adds inline styles to any button elements. If no value is provided, the button styles will inherit from the GrowSurf window button styles.
data-grsf-contact-pill-style
Object
(Optional) Adds custom styles to the contact pills, which appear underneath the email address input field when email addresses have been entered. If no value is provided, the button styles will inherit from the GrowSurf window contact pill styles.
data-grsf-*-button-style
Object
(Optional) Adds inline styles to the targeted address book button. If no value is provided, the button styles will inherit from the GrowSurf window button styles.
Replace *
with one of the following options: google
.
Example: data-grsf-google-button-style
.
data-grsf-*-button-text
String
(Optional) Sets the text of the targeted address book button. If no value is provided, the button text will default to the GrowSurf window invite Google Contacts button text.
Replace *
with one of the following options: google
.
Example: data-grsf-google-button-text
.
data-grsf-contact-picker-search-text
String
(Optional) Sets the "Search" text in the contact picker.
data-grsf-contact-picker-suggestions-text
String
(Optional) Sets the "Suggestions" text in the contact picker.
data-grsf-contact-picker-results-text
String
(Optional) Sets the "Results" text in the contact picker.
data-grsf-contact-picker-load-more-button-text
String
(Optional) Sets the "Load More" button text in the contact picker.
The embedded rewards will display the participant's earned rewards. If the participant's rewards are not approved yet or if they have not yet unlocked any rewards, they will see an empty state. This element will only be displayed to signed-in participants.
Example usage:
This is the bare minimum code required to display this element.
Data attributes:
HTML Attribute
Data Type
Description
data-grsf-block-rewards
N/A
(Required) This attribute turns any HTML element into embedded rewards.
data-grsf-email
String
(Optional) The email of the participant to display the rewards element for. If the participant does not yet exist within the campaign, they will be newly added.
data-grsf-card-style
Object
(Optional) Adds custom styles to the reward card(s).
data-grsf-title-style
Object
(Optional) Adds custom styles to the reward title.
data-grsf-horizontal
Boolean
(Optional) Displays the rewards in a horizontal format.
data-grsf-horizontal-scroll
Boolean
(Optional) If data-grsf-horizontal
is set to true
, this property will display rewards in a single scrollable row.
data-grsf-required-referrals-text
String
(Optional) Sets the "required referrals" text. This is the text that is used to indicate the number of referrals a participant must make in order to earn the reward.
NOTE
This element only displays for non-Leaderboard reward types.
data-grsf-required-referrals-style
Object
(Optional) Adds custom inline styling to the "required referrals" tag displayed for non Leaderboard reward types. This is the element within the reward that is used to indicate the number of referrals a participant must make in order to earn the reward.
data-grsf-top-referrers-text
String
(Optional) Updates the "top referrers" text displayed for Leaderboard reward types. This is the text that is used to indicate the reward goal for Leaderboard type rewards.
NOTE
This element only displays for Leaderboard reward types
data-grsf-top-referrers-style
Object
(Optional) Adds custom styling to the "top referrers" tag. This is the element within the Leaderboard reward that is used to indicate the rank threshold the participant must reach in order to earn the reward.
data-grsf-reward-limit-text
String
(Optional) Updates the "max per referrer" text displayed within the reward.
data-grsf-reward-monthly-limit-text
String
(Optional) Updates the "per month" text displayed within the reward.
data-grsf-reward-limit-style
String
(Optional) Adds inline styling for the "max per referrer" text and/or "per month" text displayed within the reward.
data-grsf-progress-icon-style
Object
(Optional) Updates the inline styling of the progress icon style used to display the progress the participant has made in order to achieve the reward goal.
NOTE
Only background-color
, color
, and display
style properties are currently supported.
data-grsf-max-progress-icons
Number
(Optional) Updates the max number of progress icons to display.
data-grsf-footer-style
String
(Optional) Adds inline styles to the footer text messages (e.g, "manual approval" footer text, "max rewards shown" footer text).
The embedded referral status will display the progress of the participant's referrals. If no one has signed up yet using the participant's unique referral link or if the participant hasn't sent out any email invites, they will see an empty state. This element will only be displayed to signed-in participants.
For email invitees, if they have not yet signed up, their email address will display as obfuscated
Example usage:
This is the bare minimum code required to display this element.
Data attributes:
HTML Attribute
Data Type
Description
data-grsf-block-referral-status
N/A
(Required) This attribute turns any HTML element into an embedded referral status element.
data-grsf-email
String
(Optional) The email of the participant to display the referral status element for. If the participant does not yet exist within the campaign, they will be newly added.
data-grsf-button-style
Object
(Optional) Adds inline styles to any buttons within the referral status element.
data-grsf-link-style
Object
(Optional) Adds custom styles to any link elements within the embedded referral status element.
data-grsf-referral-status-title
String
(Optional) Sets the text of the title above the referral status list.
data-grsf-referral-status-title-style
Object
(Optional) Adds inline styles to the text of the title above the referral status list.
data-grsf-status-column-text
String
(Optional) Sets the text of the Status column header.
data-grsf-your-referral-column-text
String
(Optional) Sets the text of the Your Referral column header.
data-grsf-header-style
Object
(Optional) Adds inline styles to the header that is displayed above the referrals list.
data-grsf-list-item-style
Object
(Optional) Adds inline styles to the list items that are displayed within the referrals list.
The embedded leaderboard will show a public list of all the participants in ranked order by their number of successful referrals. It will display to both participants and non-participants.
Example usage:
This is the bare minimum code required to display this element.
Data attributes:
HTML Attribute
Data Type
Description
data-grsf-block-leaderboard
N/A
(Required) This attribute turns any HTML element into an embedded leaderboard.
data-grsf-email
String
(Optional) The email of the participant to display the leaderboard element for. If the participant does not yet exist within the campaign, they will be newly added.
data-grsf-button-style
Object
(Optional) Adds inline styles to any buttons within the leaderboard.
data-grsf-link-style
Object
(Optional) Adds custom styles to any link elements within the embedded leaderboard.
data-grsf-leaderboard-title
String
(Optional) Sets the text of the title above the leaderboard.
data-grsf-leaderboard-title-style
Object
(Optional) Adds inline styles to the text of the title above the leaderboard.
data-grsf-rank-column-text
String
(Optional) Sets the text of the rank column header.
data-grsf-participants-column-text
String
(Optional) Sets the text of the participants column header.
data-grsf-winners-icon-style
Object
(Optional) Adds inline styles to the winner icon that is displayed next to the winner.
data-grsf-header-style
Object
(Optional) Adds inline styles to the header that is displayed above the leaderboard list.
data-grsf-list-item-style
Object
(Optional) Adds inline styles to the list items that are displayed within the leaderboard list.
The embedded How It Works will display the How It Works section of your referral program. This element will be always be displayed regardless of whether a participant is signed in or not.
The embedded FAQ will display the FAQ section of your referral program. This element will be always be displayed regardless of whether a participant is signed in or not.
The embedded Terms will display the Terms section of your referral program. This element will be always be displayed regardless of whether a participant is signed in or not.
You must have the installed on the same webpage that embeddable elements are on.
For troubleshooting auth states, please view for more details.
If you don't see styles applied to embedded elements, please check your browser developer console for errors/warnings. Data attributes must be parsable by the function.
Although embedded elements listen for changes in data attributes and update dynamically, if you run into issues where the embedded elements do not render/refresh, you can force re-rendering. This may be useful if you are working with dynamic data (such as as setting data-grsf-email
to the user's email in the ).
Please make sure to wait for the GrowSurf Universal Code to load by using the grsfReady
event listener. .
For single-page applications (SPAs), there may be issues with embeddable elements rendering on the page due to how URL routes are handled. In this case, calling growsurf.initElements()
may not work and you will need to call to re-initialize GrowSurf to make the embeddable elements render.
And here's what you would have in your JavaScript (make sure to use the event listener anytime you call any growsurf
functions):
(Optional) If provided with data-grsf-email
, then this value will be saved as the new participant's .
Custom fields are supported, so if you have an input field called "Phone Number", you would set data-grsf-field-phone-number-label
(make sure to follow ).
Custom fields are supported, so if you have an input field called "Phone Number", you would set data-grsf-field-phone-number-placeholder
(make sure to follow ).
And here's what you would have in your JavaScript (make sure to use the event listener anytime you call any growsurf
functions):
And here's what you would have in your JavaScript (make sure to use the event listener anytime you call any growsurf
functions):
And here's what you would have in your JavaScript (make sure to use the event listener anytime you call any growsurf
functions):
And here's what you would have in your JavaScript (make sure to use the event listener anytime you call any growsurf
functions):