> For the complete documentation index, see [llms.txt](https://subscriptions-docs.tech-arms.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://subscriptions-docs.tech-arms.io/features/customization/how-to-customize-the-subscription-widget.md).

# Create Your Own Widget

Create a widget from the Default or Grid template, change its text, layout, and style, choose its products, then save and publish it to your storefront.

The widget editor lets you build the purchase box that customers see on your product pages. You choose a template, change the text and style of each part, choose which products use the widget, and publish it.

This page covers the **Default** and **Grid** templates. For special templates, see [Create your Special Templates](https://subscriptions-docs.tech-arms.io/features/customization/create-your-special-templates.md).

## Create a widget

{% stepper %}
{% step %}

### Choose a template

In the app menu, click **Widgets**, then click **Create Widget** (or **Create new widget** if you have no widgets yet). The **Create new widget** window opens.

On **Default templates** or **Grid templates**, click **Use this template**. Click the eye icon (**View example**) to see the template on our demo store first.

![The Create new widget window with the Special templates, Default templates, and Grid templates cards](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FCFOK4FHj0jhqePjaZePZ%2Fcreate-widget-choose-template.png?alt=media)
{% endstep %}

{% step %}

### Customize the widget

The editor opens with a live preview. Change the blocks and settings as described below. The preview updates as you edit.
{% endstep %}

{% step %}

### Save

Click **Save** in the bar at the top of the editor. The widget is created and appears in your widget list.

Saving does **not** change your storefront. The widget stays in draft mode until you publish it.
{% endstep %}

{% step %}

### Activate

Click **More actions** next to the widget name, then click **Activate**. The badge next to the name changes to **Active**. Click **Save**.

![More actions next to the widget name, with Activate and Delete](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FxPGysxfvs0VHIrG8krcL%2Fcreate-widget-more-actions.png?alt=media)
{% endstep %}

{% step %}

### Publish

Click **Publish** at the top of the editor, then click **Publish** again in the **Publish widget** dialog.

After publishing, changes can take 1 to 3 minutes to appear on your storefront.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Save is not Publish.** Every time you save, the widget goes back to **Unpublished**, and your storefront keeps showing the last published version. Click **Publish** after each change you want customers to see.
{% endhint %}

## The editor

![The widget editor: panel buttons on the left, widget name and More actions in the center, Inspector, Localize, and device buttons on the right](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FeRXwGAjWeD30j8AXXSzL%2Fcreate-widget-editor.png?alt=media)

The top bar of the editor has:

| Control                                     | What it does                                                                            |
| ------------------------------------------- | --------------------------------------------------------------------------------------- |
| Gear icon (**Widget Settings**)             | Opens the widget settings: name, default selection, products, priority, and custom CSS. |
| Layout icon (**Subscriptions Form Design**) | Opens the list of sections and blocks.                                                  |
| Widget name and status badge                | Shows the name and **Active** or **Deactive**.                                          |
| **More actions**                            | **Activate** or **Deactivate**, and **Delete**.                                         |
| Cursor icon (**Activate Inspector**)        | When on, pointing at a part of the preview highlights its block in the left panel.      |
| **Localize**                                | Opens Shopify Translate & Adapt to translate the widget text.                           |
| Mobile and desktop icons                    | Switch the preview between mobile and desktop width.                                    |

### Choose the preview product

At the top of **Subscriptions Form Design**, **Preview** shows which product the preview uses. By default it's a sample product. Click the edit icon (**Edit Product**), choose **Product** or **Variant**, and pick one of your products to see the widget with its real plans and prices.

### Choose a style preset

Above the preview, click a style chip (**Slate**, **Carbon**, **Paper**, **Citrus**, **Obsidian**, or **Champagne**) to apply a ready-made color style. The preset is added to the top of your **Custom CSS**. Your own CSS below it is kept.

## Blocks

Click the layout icon (**Subscriptions Form Design**) to see the widget's three sections and their blocks.

![The Subscriptions Form Design panel with the three sections and their blocks](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2Fw9lBcGOA6ECgr54pvRTP%2Fcreate-widget-blocks.png?alt=media)

| Section                 | Blocks you can use                                                                | What they show                                                                                                                                                                        |
| ----------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Product price**       | **Subscription price**, **Compare price**, **Extra information**                  | The subscription price, the original price crossed out, and a savings line (default: `subscription - save {{save_value}}`).                                                           |
| **Subscription form**   | **Title**, **Onetime purchase**, **Subscription plan group**, **Trial Promotion** | The title (default "Purchase options"), the one-time purchase option, your selling plans and plan options with the savings badge, and the trial message for Try Before You Buy plans. |
| **Subscription footer** | **Additional Information**, **Subscription details**                              | Extra text about your subscription, and a "Subscription details" box that explains how the subscription works.                                                                        |
| Any section             | **Text**, **Custom Html**                                                         | Your own text, or your own HTML and CSS.                                                                                                                                              |

To work with blocks:

* **Edit a block**: click it. Its settings open, such as text, color, font size, padding, and border.
* **Hide or show a block**: point at the block and click the eye icon. For example, hide **Onetime purchase** to sell the product as subscription only.
* **Delete a block**: point at the block and click the delete icon.
* **Move a block**: drag it to a new position inside its section.
* **Add a block**: click **Add block** under a section and choose a block. Some blocks can be added only once, and a widget can have up to 30 blocks.

### Useful settings in Subscription plan group

| Setting                                          | What it does                                                                                                            |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Group title**                                  | The name shown for each selling plan. Default: the selling plan name. (Default template only.)                          |
| **Price style**                                  | **Hide**, **Show discounted and compare price**, or **Show discounted price**. Controls the price block above the form. |
| **Label** (in **Plan option settings**)          | The text above the plan options, for example "Delivery every".                                                          |
| **Option content(HTML)**                         | The text of each plan option.                                                                                           |
| **Default label** (in the badge settings)        | The savings badge, default `Save {{save_value}}`.                                                                       |
| **Adjustment label**, **Delayed discount label** | Extra badge text for plans whose discount changes after some orders.                                                    |

Text fields that accept variables, such as `{{save_value}}` or `{{plan_price}}`, list them under the field. Keep the braces when you use a variable.

## Widget Settings

Click the gear icon (**Widget Settings**).

| Section                | Setting                                                                     | What it does                                                                                                    |
| ---------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **General**            | **Widget name**                                                             | The name in your widget list. Customers don't see it.                                                           |
| **General**            | **Subscription option selected by default?**                                | When ticked, the product page opens with the first subscription plan selected instead of **One-time purchase**. |
| **Apply to resources** | **Priority**                                                                | 0 to 100. When several widgets apply to one product, the highest number wins.                                   |
| **Apply to resources** | **All**, **Specific products**, **Specific collections**, **Specific tags** | Which products use this widget.                                                                                 |
| **Custom CSS**         | CSS box                                                                     | Your own styles for the whole widget.                                                                           |

![The Widget Settings panel with General, Apply to resources, and Custom CSS](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FGmkCaU8q3AEiNl9kM4ns%2Fcreate-widget-settings.png?alt=media)

To learn how the app picks a widget when several apply, see [Widgets](https://subscriptions-docs.tech-arms.io/features/customization.md).

{% hint style="info" %}
Custom CSS also applies to the price block, which sits in your theme's page. Write narrow selectors so your CSS doesn't change other parts of the product page.
{% endhint %}

## Translate the widget

Click **Localize** in the top bar to translate the widget text with Shopify Translate & Adapt. **Localize** is available only after the widget is **Active** and published. For the full steps, see [Multilingual widget](https://subscriptions-docs.tech-arms.io/features/translation/multilingual-widget.md).

## Deactivate or delete a widget

* **Deactivate**: click **More actions** > **Deactivate**, click **Save**, then click **Publish**. The widget is removed from your storefront. If you only save, your storefront keeps showing the widget.
* **Delete**: click **More actions** > **Delete**, then confirm. The widget is removed from the app and your storefront right away. This can't be undone.

## Good to know

* If you leave the editor with unsaved changes, the app asks you to save or discard them.
* Publishing a widget that is **Deactive** removes it from your storefront. Activate it first.
* Products that no published, active widget applies to show the app's built-in default widget, without your changes.
* Click **Need help?** in the **Subscriptions Form Design** panel to chat with us about your widget design.

*If you need help, feel free to reach out to us via in-app* [***Live chat***](https://go.crisp.chat/chat/embed/?website_id=c4ae10a3-f762-4968-b35a-c931caf62a96)***,*** [***Book a call***](https://calendly.com/ta-subscription-app-support/30min) *or at* [***support@tech-arms.io***](mailto:support@tech-arms.io)***.***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://subscriptions-docs.tech-arms.io/features/customization/how-to-customize-the-subscription-widget.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
