Embeddable Elements

Embedded elements are ready-made UI components that are 100% customizable, and can be quickly inserted into your HTML for displaying campaign and participant information inline on your webpage.

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

(Optional) Forcefully re-rendering embeddable elements

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();

Embedded Form

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

The embedded form has two different UI states

Example usage:

Basic
100% customized
<div data-grsf-block-form></div>
<div data-grsf-block-form
data-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-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-share-instructions="Share this unique link with your friends">
</div>

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

(Optional) If provided with data-grsf-email, then this value will be saved as the new participant's metadata.

If the participant already exists in the referral campaign, then this attribute will be ignored.

data-grsf-label-style

Object

(Optional) Adds inline styles to the form input labels.

data-grsf-button-style

Object

(Optional) Adds inline styles to the Copy Link button.

data-grsf-link-style

Object

(Optional) Adds custom styles to any link elements.

data-grsf-email-button-style

Object

(Optional) Adds inline styles to the Email share button.

data-grsf-email-button-text

String

(Optional) Sets the text of the Email share button.

data-grsf-twitter-button-style

Object

(Optional) Adds inline styles to the Twitter share button.

data-grsf-twitter-button-text

String

(Optional) Sets the text of the Twitter share button.

data-grsf-facebook-button-style

Object

(Optional) Adds inline styles to the Facebook share button.

data-grsf-facebook-button-text

String

(Optional) Sets the text of the Facebook share button.

data-grsf-pinterest-button-style

Object

(Optional) Adds inline styles to the Pinterest share button.

data-grsf-pinterest-button-text

String

(Optional) Sets the text of the Pinterest share button.

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

Embedded Button

The embedded button is an element that opens up the GrowSurf window when clicked.

The embedded button has one UI state

Example usage:

Basic
100% customized
<div data-grsf-block-button></div>
<div data-grsf-block-button
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

data-grsf-block-button

N/A

(Required) This attribute turns any HTML element into an embedded button.

data-grsf-button-text

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.

data-grsf-button-style

Object

(Optional) Adds inline styles to the button. If no value is provided, the button styles will inherit from the GrowSurf window button styles.

Not seeing your styles applied to your button?

Check your browser developer console for errors or warnings related to block elements. The data-grsf-button-style attribute must be parsable by the JSON.parse() function.

Embedded Leaderboard

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

The embedded leaderboard has two different UI states

Example usage:

Basic
100% customized
<div data-grsf-block-leaderboard></div>
<div data-grsf-block-leaderboard
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'}">
</div>

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

NOTE

Only background-color and color style properties are currently supported.

Embedded Rewards

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

The embedded rewards has two different UI states

Example usage:

Basic
100% customized
<div data-grsf-block-rewards></div>
<div data-grsf-block-rewards
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-progress-icon-style="{'background-color': '#d39e00', 'color': '#000000'}">
</div>

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

NOTE

Only background-color and color style properties are currently supported.

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.

NOTE

Only background-color and color style properties are currently supported.

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

NOTE

Only background-color and color style properties are currently supported.

Embedded Stats

The embedded stats is an element that displays a participant's referral statistics and rank.

The embedded stats has only one UI state (for participants)

Example usage:

Basic
100% customized
<div data-grsf-block-stats></div>
<div data-grsf-block-stats
data-grsf-email="gavin@hooli.com"
data-grsf-referral-count-style="{'background-color': '#F0F0F0', 'font-family': 'Arial', 'color': '#000000', 'border-radius': '6px'}"
data-grsf-referral-count-text="total referrals made"
data-grsf-rank-style="{'background-color': '#117a8b', 'font-family': 'Arial', 'color': '#FFFFFF', 'border-radius': '6px'}"
data-grsf-rank-text="Position">
</div>

Data attributes:

HTML Attribute

Data Type

Description

data-grsf-block-stats

N/A

(Required) This attribute turns any HTML element into embedded stats

data-grsf-email

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.

data-grsf-referral-count-style

Object

(Optional) Adds inline styling to the element that displays the participant's referral count.

data-grsf-referral-count-text

String

(Optional) Sets the text that is used to label the participant's referral count.

data-grsf-rank-style

Object

(Optional) Adds inline styling to the element that displays the participant's rank.

data-grsf-rank-text

String

(Optional) Sets the text that labels the participant's rank.