Ghost provides a set of attributes that turn HTML forms into your own subscription flow. The following sections show how to use these HTML attributes and configure them to your needs.

Subscription forms

The only two elements a subscription form requires is an email input field and a submit button. To turn it into a functional subscription form add the attribute data-members-form to the form element and data-members-email to the email input field:

<form data-members-form>
  <input data-members-email type="email" required="true"/>
  <button type="submit">Continue</button>
</form>

That's it, your site can now accept members 🎉

Extending forms

The data-members-form accepts a series of optional values to customise user flows. The following explains these options as well as their fallback flows:

• data-members-form="signin" – The default behaviour of members forms. If a member uses this form they will be sent a sign in email, if they are not already a member they will be sent a sign up email instead
• data-members-form="signup" – If a member uses this form they will be sent a sign up email, if they are already a member they will be sent a sign in email instead
• data-members-form="subscribe" – If a member uses this form they will be sent a subscribe email, if they are already a member they will be sent a sign in email instead

Form states

Whenever a members form is submitted it'll pass through a series of states, which are reflected in the HTML as classes. The classes loading, success and error when the submission is loading, has been successful or has hit an error.

Examples

<form data-members-form class="loading">...</form>

<form data-members-form class="success">...</form>

<form data-members-form class="error">...</form>

Signing out

Sometimes users want to ensure that their account is secure by signing out of their account after they finished viewing their members only content. Creating a sign out button can be done by applying a data attributed named data-members-signout to an <a> element:

<a href="javascript:" data-members-signout>Sign out</a>

Members labels

Members labels can be used to tag members into groups, either manually in Ghost admin or automatically via a form or integration. Labels can be added to a Member as soon as they sign up using a single hidden HTML input element.

In the following example any Member signing up using the form will have the label 'Early Adopters' applied:

<form data-members-form="subscribe">

  <input data-members-label type="hidden" value="Early Adopters" />

  <input data-members-email type="email" required="true"/>
  <button type="submit">Subscribe</button>
</form>

Multiple labels can be added to a form, and can be added without any pre-configuration.

Error messages

Error messages can be shown whenever a members form or subscription button causes an error. Showing the message can be done by adding a child element to the <form> or <a> element with the attribute data-members-error.

Example

<form data-members-form>
  ...
  <p data-members-error><!-- error message will appear here --></p>
</form>

Create a sign in & out component

A common use case would be to create a component that shows a signin form when the member is logged out, and a signout button when a member is logged in. This can be achieved by using the above HTML in conjunction with @members helper.

Example

{{#if @member}}
  <a href="javascript:" data-members-signout>Sign out</a>
{{else}}
  <form data-members-form="signin">
    <input data-members-email type="email" required="true"/>
    <button type="submit">Sign in</button>
  </form>
{{/if}}

Members enabled helper

To maximise compatibility theme developers may want to optionally show Members UI if the Members feature is enabled in Ghost admin. @labs.members is a helper that can be used to check if Members has been enabled.

Example

{{#if @labs.members}}
  <form data-members-form="signin">
    <input data-members-email type="email" required="true"/>
    <button type="submit">Sign in</button>
  </form>
{{/if}}

{{#unless @labs.members}}
  <!-- hide if Members is enabled in Ghost admin -->
{{/unless}}

Next steps

For more detail into how Ghost themes can be customised with the use of @member check out Content visibility. Or take memberships one step further and implement a Stripe checkout flow with monthly and yearly subscription plans with member checkout buttons.