Embeddable Elements
Embeddable elements are individual components that make up the contents of the GrowSurf window. They inherit the same styles and dynamic behavior that you see in the GrowSurf window -- but embeddable elements can be 100% customized using HTML data attributes.
You can configure each component's styles by changing your campaign's Theme (in the Design step of the Campaign Editor), or you can use data attributes to override and completely customize styles.
Just like the GrowSurf window, embeddable elements have two UI states that display differently to New Visitors ("no auth" state) and to Participants ("auth" state)
Important Note: You must have the GrowSurf Universal Code installed within the same webpage that you are using embeddable elements on.
Important Note: If you see the "no auth" state when you are expecting to see the "auth" state, it is most likely because you have participant authentication enabled for your campaign and there is no cookie saved on the participant's browser. Please see this article for more details.
Tip for Troubleshooting Styling: 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 JSON.parse() 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 Embedded Form).
To force re-rendering, call growsurf.initElements(), which destroys all embeddable elements in the DOM and forces GrowSurf to re-render them.
growsurf.initElements();
The embedded form is an element that has two different UI states.
For new visitors, the signup form is shown (this is the "no auth" state).
For participants, their unique referral link with share buttons are displayed (this is the "auth" state).
Example usage:
<div data-grsf-block-form></div>
<div data-grsf-block-formdata-grsf-email="gavin@hooli.com"data-grsf-first-name="Gavin"data-grsf-last-name="Belson"data-grsf-metadata="{'company': 'Hooli, Inc', 'companySize': 10000}"data-grsf-label-style="{'color': '#515151', 'font-size': '10px'}"data-grsf-gdpr-paragraph-style="{'color': '#222222', 'font-size': '11px'}"data-grsf-gdpr-checkbox-style="{'color': '#222222', 'font-size': '11px'}"data-grsf-button-style="{'background-color': '#5890E7', 'color': '#fcfcfc', 'font-family': 'Sans', 'font-size': '12px'}"data-grsf-link-style="{'color': '#515151'}"data-grsf-email-button-style="{'background-color': '#5890E7', 'color': '#fcfcfc', 'font-family': 'Arial', 'font-size': '12px'}"data-grsf-email-button-text="Share"data-grsf-twitter-button-style="{'background-color': '#5890E7', 'font-family': 'Arial', 'font-size': '12px'}"data-grsf-twitter-button-text="Share"data-grsf-facebook-button-style="{'background-color': '#5890E7', 'font-family': 'Courier New', 'font-size': '12px'}"data-grsf-facebook-button-text="Share"data-grsf-pinterest-button-style="{'background-color': '#5890E7', 'letter-spacing': '1.2', 'font-size': '12px'}"data-grsf-pinterest-button-text="Pin It"data-grsf-sms-button-style="{'background-color': '#5890E7', 'color': '#fcfcfc', 'font-family': 'Arial', 'font-size': '12px'}"data-grsf-sms-button-text="Text it"data-grsf-messenger-button-style="{'background-color': '#5890E7', 'letter-spacing': '1.2', 'font-size': '12px'}"data-grsf-messenger-button-text="Share on Messenger"data-grsf-whatsapp-button-style="{'background-color': '#5890E7', 'letter-spacing': '1.2', 'font-size': '12px'}"data-grsf-whatsapp-button-text="Share on WhatsApp"data-grsf-share-instructions="Share this unique link with your friends"data-grsf-share-instructions-style="{'padding': '10px'}"data-grsf-copy-link-container-style="{'padding': '10px'}"data-grsf-redirect-url="https://replaceme.com"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into an embedded form. |
| 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. |
| String | (Optional) If provided with If the participant already exists in the referral campaign, then this attribute will be ignored. |
| String | (Optional) If provided with If the participant already exists in the referral campaign, then this attribute will be ignored. |
| Object | (Optional) If provided with If the participant already exists in the referral campaign, then this attribute will be ignored. |
| Object | (Optional) Adds inline styles to the GDPR consent paragraph text (if GDPR enabled). |
| Object | (Optional) Adds inline styles to the GDPR consent checkbox text (if GDPR is enabled). |
| Object | (Optional) Adds inline styles to the form input labels. |
| Object | (Optional) Adds inline styles to any button elements. |
| Object | (Optional) Adds custom styles to any link elements. |
| Object | (Optional) Adds inline styles to the Email share button. |
| String | (Optional) Sets the text of the Email share button. |
| Object | (Optional) Adds inline styles to the Twitter share button. |
| String | (Optional) Sets the text of the Twitter share button. |
| Object | (Optional) Adds inline styles to the Facebook share button. |
| String | (Optional) Sets the text of the Facebook share button. |
| Object | (Optional) Adds inline styles to the Pinterest share button. |
| String | (Optional) Sets the text of the Pinterest share button. |
| Object | (Optional) Adds inline styles to the SMS share button. |
| Object | (Optional) Sets the text of the SMS share button. |
| Object | (Optional) Adds inline styles to the Messenger share button. |
| Object | (Optional) Sets the text of the Messenger share button. |
| Object | (Optional) Adds inline styles to the WhatsApp share button. |
| Object | (Optional) Sets the text of the WhatsApp share button. |
| String | (Optional) Sets the text of the share instructions (these instructions are only visible when the participant is in the auth state). |
| Object | (Optional) Adds inline styles to the share instructions. |
| Object | (Optional) Adds inline styles to the container of the input box and Copy Link button. |
| 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 to their friends/family.
Example usage:
<div data-grsf-block-invite></div>
<div data-grsf-block-invitedata-grsf-email="gavin@hooli.com"data-grsf-instructions-text="Invite your friends/family!"data-grsf-instructions-style="{'text-align': 'left'}"data-grsf-label-style="{'font-weight': 'bold'}"data-grsf-input-placeholder-text="Enter email addresses here"data-grsf-preview-link-text="Preview your message"data-grsf-link-style="{'color': '#8885E1'}"data-grsf-submit-button-text="Send Invite To Friends"data-grsf-button-style="{'background-color': '#5890E7', 'text-transform': 'initial', 'font-family': 'Arial', 'color': '#FFFFFF', 'border-radius': '6px' }"data-grsf-contact-pill-style="{'background-color': '#8885E1', 'color': '#fff'}"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into an embedded invite. |
| 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. |
| String | (Optional) Sets the text of the invite instructions. |
| Object | (Optional) Adds inline styles to the invite instructions. |
| Object | (Optional) Adds inline styles to the form input labels. |
| String | (Optional) Sets the placeholder text of the email address input field. |
| 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. |
| 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. |
| 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. |
| Object | (Optional) Adds inline styles any button elements. If no value is provided, the button styles will inherit from the GrowSurf window button styles. |
| 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. |
The embedded button is an element that opens up the GrowSurf window when clicked.
Example usage:
<div data-grsf-block-button></div>
<div data-grsf-block-buttondata-grsf-email="gavin@hooli.com"data-grsf-button-text="Join My Referral Program"data-grsf-button-style="{'background-color': '#5890E7', 'text-transform': 'initial', 'font-family': 'Arial', 'color': '#FFFFFF', 'border-radius': '6px' }"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into an embedded button. |
| String | (Optional) The email of the participant to display the button element for. If the participant does not yet exist within the campaign, they will be newly added. |
| String | (Optional) Sets the text of the embedded button. If no value is provided, the button text will default to the GrowSurf window signup form button text. |
| Object | (Optional) Adds inline styles to the button. If no value is provided, the button styles will inherit from the GrowSurf window button styles. |
The embedded leaderboard is an element that has two different UI states.
For new visitors, the leaderboard is displayed (this is the "no auth" state).
For participants, the leaderboard is displayed with their row highlighted (this is the "auth" state).
Example usage:
<div data-grsf-block-leaderboard></div>
<div data-grsf-block-leaderboarddata-grsf-email="gavin@hooli.com"data-grsf-button-style="{'background-color': 'red', 'font-family': 'Sans'}"data-grsf-link-style="{'background-color': 'red', 'color': '#CCCCCC', 'font-family': 'Courier New'}"data-grsf-leaderboard-title="Current Standings"data-grsf-rank-column-text="Position"data-grsf-participants-column-text="People"data-grsf-referrals-column-text="Count"data-grsf-winners-icon-style="{'background-color': 'green', 'color': 'CCCCCC'}"data-grsf-header-style="{'display':'none'}"data-grsf-list-item-style="{'border-radius': '0', 'padding': '0', 'box-shadow': 'none', 'align-items': 'flex-start'}"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into an embedded leaderboard. |
| 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. |
| Object | (Optional) Adds inline styles to any buttons within the leaderboard. |
| Object | (Optional) Adds custom styles to any link elements within the embedded leaderboard. |
| String | (Optional) Sets the text of the title above the leaderboard. |
| String | (Optional) Sets the text of the rank column header. |
| String | (Optional) Sets the text of the participants column header. |
| Object | (Optional) Adds inline styles to the winner icon that is displayed next to the winner. |
| Object | (Optional) Adds inline styles to the header that is displayed above the leaderboard list. |
| Object | (Optional) Adds inline styles to the list items that are displayed within the leaderboard list. |
The embedded rewards is an element that has two different UI states.
For new visitors, the campaign rewards are displayed (this is the "no auth" state).
For participants, the campaign rewards are displayed with the participant's progress being displayed next to each one (this is the "auth" state).
Example usage:
<div data-grsf-block-rewards></div>
<div data-grsf-block-rewardsdata-grsf-email="gavin@hooli.com"data-grsf-card-style="{'background-color': '#FDFDFD', 'box-shadow': 'none', 'border-radius': '12px', 'padding': '10px'}"data-grsf-title-style="{'font-size': '16px'}"data-grsf-horizontal="true"data-grsf-horizontal-scroll="true"data-grsf-required-referrals-text="Req Refs"data-grsf-required-referrals-style="{'background-color': '#117a8b', 'color': '#CCCCCC'}"data-grsf-top-referrers-text="Top ambassadors"data-grsf-top-referrers-style="{'background-color': '#5890E7', 'color': '#FFFFFF'}"data-grsf-reward-limit-text="per winner"data-grsf-reward-monthly-limit-text="per sunny month"data-grsf-reward-limit-style="{'color': 'black'}"data-grsf-progress-icon-style="{'background-color': '#d39e00', 'color': '#000000'}"data-grsf-max-progress-icons="6"data-grsf-footer-style="{'text-align': 'center', 'color': '#E7B558'}"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into embedded rewards. |
| 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. |
| Object | (Optional) Adds custom styles to the reward card(s). |
| Object | (Optional) Adds custom styles to the reward title. |
| Boolean | (Optional) Displays the rewards in a horizontal format. |
| Boolean | (Optional) If |
| 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. |
| 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. NOTE Only |
| 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 |
| 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. NOTE Only |
| String | (Optional) Updates the "max per referrer" text displayed within the reward. |
| String | (Optional) Updates the "per month" text displayed within the reward. |
| String | (Optional) Adds inline styling for the "max per referrer" text and/or "per month" text displayed within the reward. |
| 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 |
| Number | (Optional) Updates the max number of progress icons to display. |
| String | (Optional) Adds inline styles to the footer text messages (e.g, "manual approval" footer text, "max rewards shown" footer text). |
The embedded stats is an element that displays a participant's referral statistics and rank.
The referral count text ("X referrals made") will only be displayed if you have at least one non-Leaderboard-type reward
The rank text ("#X your rank") will only be displayed if you have at least one Leaderboard-type reward
Example usage:
<div data-grsf-block-stats></div>
<div data-grsf-block-statsdata-grsf-email="gavin@hooli.com"data-grsf-referral-count-style="{'background-color': '#007bff', 'color': '#ffffff', 'border-radius': '20px', 'max-width': '260px', 'width': 'fit-content'}"data-grsf-referral-count-text="total referrals made"data-grsf-rank-style="{'background-color': '#007bff', 'color': '#ffffff', 'border-radius': '20px', 'max-width': '260px', 'width': 'fit-content'}"data-grsf-rank-text="Position"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into embedded stats |
| String | (Optional) The email of the participant to display stats for. If the participant does not yet exist within the campaign, they will be newly added. |
| Object | (Optional) Adds inline styling to the element that displays the participant's referral count. |
| String | (Optional) Sets the text that is used to label the participant's referral count. |
| Object | (Optional) Adds inline styling to the element that displays the participant's rank. |
| String | (Optional) Sets the text that labels the participant's rank. |
The embedded next milestone is an element that displays how many referrals a participant needs to make to unlock the next/upcoming milestone reward (only applies to milestone rewards).
In the Campaign Editor, make sure to update your milestone reward's advanced settings to set the Next Milestone prefix and suffix values (see image).
If the participant has reached all milestones, then nothing will be rendered
Example usage:
<div data-grsf-block-next-milestone></div>
<div data-grsf-block-next-milestonedata-grsf-milestones="[{'goal': 2, 'prefix': 'You are only', 'suffix': 'referrals away from winning a free t-shirt!', 'monthly': false},{'goal': 5, 'prefix': 'You are only', 'suffix': 'referrals away from winning a free jacket!', 'monthly': false},{'goal': 10, 'prefix': 'You are only', 'suffix': 'referrals away from a free trip to Hawaii!', 'monthly': false}]"data-grsf-only-show-number="true"data-grsf-email="gavin@hooli.com"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into an embedded next milestone |
| Array<Object> | (Optional) Set this attribute if you want to override your campaign's milestone rewards so that you can define your own milestone rewards as an Array. Each Object should follow this format:
The following is an example Object:
|
| String | (Optional) The email of the participant to display their next milestone reward to. If the participant does not yet exist within the campaign, they will be newly added. |
| Boolean | (Optional) If set to |
The embedded referral status lets a participant view the individual progress of their referrals and email invitees.
For email invitees, if they have not yet signed up, their email address will display as obfuscated
Example usage:
<div data-grsf-block-referral-status></div>
<div data-grsf-block-referral-statusdata-grsf-email="gavin@hooli.com"data-grsf-referral-status-title="Referral Status"data-grsf-your-referral-column-text="Your Friend"data-grsf-status-column-text="Their Status"data-grsf-button-style="{'background-color': '#5890E7', 'color': '#fcfcfc', 'font-size': '12px', 'border-radius': '100%'}"data-grsf-header-style="{'display':'none'}"data-grsf-list-item-style="{'border-radius': '0', 'padding': '0', 'box-shadow': 'none', 'align-items': 'flex-start'}"data-grsf-link-style="{'background-color': '#8885E1', 'color': '#fff'}"></div>
Data attributes:
HTML Attribute | Data Type | Description |
| N/A | (Required) This attribute turns any HTML element into an embedded referral status element. |
| 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. |
| Object | (Optional) Adds inline styles to any buttons within the referral status element. |
| Object | (Optional) Adds custom styles to any link elements within the embedded referral status element. |
| String | (Optional) Sets the text of the title above the referral status list. |
| String | (Optional) Sets the text of the Status column header. |
| String | (Optional) Sets the text of the Your Referral column header. |
| Object | (Optional) Adds inline styles to the header that is displayed above the referrals list. |
| Object | (Optional) Adds inline styles to the list items that are displayed within the referrals list. |