VTEX Developer Portal

All ContributorsAll Contributors

The Store Newsletter app provides a set of blocks that you can use to create a newsletter subscription form.

newsletter-demonewsletter-demo

Configuration

  1. Add vtex.store-newsletter to your app's dependencies in the manifest.json file:
 "dependencies": {
+  "vtex.store-newsletter": "1.x"
 }

Now, you are able to use all blocks exported by the store-newsletter app. Check out the full list below:

Block nameDescription
newsletter-formmandatorymandatory Top level block that provides context to all its children.
newsletter-input-emailmandatorymandatory Renders an email input in the newsletter form.
newsletter-input-nameRenders an name input in the newsletter form.
newsletter-input-phoneRenders an phone input in the newsletter form.
newsletter-checkbox-confirmationRenders a confirmation checkbox in the newsletter form.
newsletter-hidden-fieldDoesn't render anything, but enables hidden fields on the form to fetch custom data and save them in the store's Master Data whenever a user subscribes to the newsletter.
newsletter-submitmandatorymandatory Renders a Submit button for the newsletter form.
  1. In the desired store template, such as the store.home, add the newsletter-form block and its desired children:
{
  "store.home": {
    "children": ["newsletter-form"]
  },

  "newsletter-form": {
    "children": [
      "newsletter-input-email",
      "newsletter-input-name",
      "newsletter-submit"
    ]
  }
}

newsletter-form props

Prop nameTypeDescriptionDefault value
ErrorStateblockBlock to be rendered if the submission of the form fails. If none is passed, a default error component will be rendered.undefined
SuccessStateblockBlock to be rendered if form submission succeeds. If none is passed, a default success component will be rendered.undefined
LoadingStateblockBlock to be rendered while the form submission is loading. If none is passed, the default behavior is for the submit button to show a spinner during this loading period.undefined
classesCustomCSSClassesUsed to override default CSS handles. To better understand how this prop works, we recommend reading about it here. Note that this is only useful if you're importing this block as a React component.undefined

newsletter-input-email props

Prop nameTypeDescriptionDefault value
placeholderTextstringPlaceholder text for the email input.Enter your email address (translated according to the store's locale).
inputLabelstringLabel for the email input.null
errorMessagestringError message to be shown if email is invalid.Invalid email address (translated according to the store's locale).
classesCustomCSSClassesUsed to override default CSS handles. To better understand how this prop works, we recommend reading about it here. Note that this is only useful if you're importing this block as a React component.undefined

newsletter-input-name props

Prop nameTypeDescriptionDefault value
placeholderTextstringPlaceholder text for name input.Enter your name (translated according to the store's locale).
inputLabelstringLabel for the name input.null
errorMessagestringError message to be shown if name input is empty.Invalid name (translated according to the store's locale).
classesCustomCSSClassesUsed to override default CSS handles. To better understand how this prop works, we recommend reading about it here. Note that this is only useful if you're importing this block as a React component.undefined

newsletter-input-phone props

Prop nameTypeDescriptionDefault value
placeholderTextstringPlaceholder text for phone input.Enter your phone (translated according to the store's locale).
inputLabelstringLabel for the phone input.null
errorMessagestringError message to be shown if phone input is empty.Invalid phone (translated according to the store's locale).
classesCustomCSSClassesUsed to override default CSS handles. To better understand how this prop works, we recommend reading about it here. Note that this is only useful if you're importing this block as a React component.undefined

newsletter-checkbox-confirmation props

Prop nameTypeDescriptionDefault value
checkboxLabelstringLabel for the confirmation checkbox. This prop supports the ICU Message Format, exposing two variables for you to interpolate: firstLink and secondLink.I agree to received this newsletter. (translated according to the store's locale).
firstLabelLinkObjectConfigures the firstLink variable to be interpolated by the text passed to checkboxLabel. checkbox.undefined.
secondLabelLinkObjectConfigures the secondLink variable to be interpolated by the text passed to checkboxLabel. checkbox.undefined
classesCustomCSSClassesUsed to override default CSS handles. To better understand how this prop works, we recommend reading about it here. Note that this is only useful if you're importing this block as a React component.undefined
  • firstLabelLink and secondLabelLink objects:
Prop nameTypeDescriptionDefault value
urlstringThe link's URL.undefined
textstringText displayed on the link.undefined

newsletter-hidden-field props

Prop nameTypeDescriptionDefault value
dynamicFields[enum]Desired hidden fields responsible for saving the user's custom data on Master Data once the newsletter form is submitted. Notice that the name of the fields must be written in an array and represent which user data they save. Possible values are: bindingUrl and bindingId. Caution: To properly save the data, you must also create the desired filters in the Master Data's Client entity.undefined

newsletter-submit props

Prop nameTypeDescriptionDefault value
submitButtonLabelstringText displayed on the submit button.Subscribe (translated according to the store's locale).
classesCustomCSSClassesUsed to override default CSS handles. To better understand how this prop works, we recommend reading about it here. Note that this is only useful if you're importing this block as a React component.undefined

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles
confirmationCheckboxContainer
confirmationCheckboxLabel
defaultErrorMessage
defaultSuccessMessage
emailInputContainer
emailInputContainer--invalid
emailInputLabel
formSubmitContainer
formSubmitContainer--invalid
nameInputContainer
nameInputContainer--invalid
nameInputLabel
newsletterForm
phoneInputContainer
phoneInputContainer--invalid
phoneInputLabel

Contributors ✨

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!

Updated 8 months ago


Store Newsletter


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.