Matcha Documentation

This comprehensive guide covers everything you need to install, configure, and customize the Matcha Shopify theme. Matcha is a modern, clean coffee theme built around mint and sage green tones with a minimal editorial aesthetic. Use the sidebar navigation to jump to a specific section, or scroll through for the complete reference.

Getting Started

System Requirements

Matcha requires a Shopify store on any current plan (Basic Shopify, Shopify, Advanced, or Shopify Plus). The theme is built on Online Store 2.0 and requires no additional apps for core functionality.

Installation

After completing your purchase, you will receive a ZIP file containing the theme. Follow these steps to install it on your Shopify store:

1. Log in to your Shopify admin panel at your-store.myshopify.com/admin.
2. Navigate to Online Store > Themes in the left sidebar.
3. In the Theme library section, click the Add theme button.
4. Select Upload ZIP file from the dropdown menu.
5. Choose the downloaded ZIP file from your computer and wait for the upload to complete. This typically takes 15-30 seconds.
6. Once uploaded, the theme will appear in your theme library. Click Customize to open the visual theme editor, or click Actions > Publish to make it your live theme immediately.

Activating Matcha

Once you have uploaded and customized the theme to your liking:

1. Go to Online Store > Themes in your Shopify admin.
2. Find Matcha in your theme library.
3. Click Actions > Publish.
4. Confirm the activation in the dialog. Your previous theme will be moved to the theme library and can be restored at any time.

Using Shopify CLI

If you prefer working with the command line, you can deploy the theme using Shopify CLI:

shopify theme push --store your-store.myshopify.com

This requires the Shopify CLI to be installed and authenticated with your store. Extract the ZIP file first, then run the command from the extracted directory. Refer to the official Shopify CLI documentation for setup instructions.

Theme Settings

Colors

Matcha ships with a carefully curated mint and sage green palette centered around the primary accent #5B8C6A. You can fully customize every color without code changes. In the Shopify theme editor, navigate to Theme settings > Colors to configure:

• Primary color — The main sage green (#5B8C6A) used for buttons, links, badges, and accent elements. Change this to match your brand identity.
• Secondary color — Applied to secondary buttons, hover states, and supporting UI elements. Default is a lighter mint tone.
• Background color — The main background color for all pages. Default is a warm off-white for a clean, airy feel.
• Text color — Body text color. Default is a soft charcoal for comfortable reading.
• Header background & text — Separate color controls for the centered logo header, navigation links, and mobile drawer.
• Footer background & text — Independent footer color settings for background, headings, and link colors.
• Sale / Badge colors — Customize the appearance of sale badges, "New" tags, and "Sold out" indicators independently.
• Trust bar colors — Background and text colors for the scrolling trust ticker that appears below the header.

Typography

Navigate to Theme settings > Typography to select fonts for headings and body text. Matcha pairs a modern sans-serif heading font with a clean body font for readability. You can choose from the full Shopify-hosted font library or provide a custom font URL. The theme supports:

• Heading font — Applied to all headings (h1 through h6), section titles, product names, and collection titles. The default is a geometric sans-serif for a fresh, modern look.
• Body font — Used for paragraphs, product descriptions, navigation links, form labels, and all general UI text.
• Font size scale — Adjust the base font size (default: 16px). All other sizes scale proportionally, so a single change updates the entire typographic hierarchy.
• Letter spacing — Fine-tune letter spacing for headings and body text independently. Wider spacing pairs well with the minimal aesthetic.

Layout

Under Theme settings > Layout, you can control the overall page structure and visual style:

• Content width — Set the maximum width of the main content area. Default is 1200px. Wider values work well for image-heavy stores.
• Section spacing — Control vertical padding between sections (small, medium, or large). Affects all pages globally. Matcha defaults to generous spacing for a breathing, editorial feel.
• Border radius — Set the corner radius for buttons, cards, input fields, and image containers. Default is a subtle 4px for soft edges without being overly rounded.
• Enable animations — Toggle scroll-triggered fade and slide animations on or off globally. Disabling animations can improve performance on older devices.
• Card style — Choose between flat, elevated (subtle shadow), or outlined card styles for product cards and content blocks.

Header & Navigation

Centered Logo Header

Matcha uses a warm centered logo header layout by default. Your brand logo is positioned at the center of the header with navigation links split evenly on either side. This layout creates a balanced, sophisticated appearance ideal for specialty coffee and lifestyle brands.

Upload your brand logo in the header section settings. For best results, use a transparent PNG or SVG file. Recommended dimensions: height between 40px and 60px. The theme will scale the logo proportionally based on the max-width value you set.

Sticky Behavior

The header supports sticky behavior that keeps it visible as customers scroll down the page. When enabled, the header shrinks slightly and gains a subtle background blur as the user scrolls past the hero section. Configure sticky settings under Header section > Sticky header:

• Enable sticky header — Master toggle for the sticky behavior.
• Shrink on scroll — When enabled, the header reduces its height from 80px to 60px after scrolling. This preserves screen space while keeping navigation accessible.
• Background on scroll — Choose between solid white, frosted glass (background blur), or transparent. Frosted glass is the default and provides a modern layered effect.
• Show shadow on scroll — Adds a subtle bottom shadow to the header when scrolled to visually separate it from page content.

Navigation Menu

Select which Shopify navigation menu to display in the header. Create and manage your menus in Shopify Admin > Online Store > Navigation. The theme supports up to two levels of dropdown nesting for the centered layout. Dropdowns appear as clean, minimal panels beneath the header with smooth fade-in animations.

Mobile Drawer

On screens below 768px, the header collapses into a hamburger icon that opens a slide-in drawer menu from the left side. The mobile drawer includes:

• Your logo at the top of the drawer for brand consistency
• Full navigation with accordion-style expandable submenus
• Search bar integrated at the top of the drawer
• Account and cart icons in the drawer header
• Social media links at the bottom of the drawer

The drawer uses a smooth slide animation and dims the page content behind it with a semi-transparent overlay. Tapping the overlay or pressing the close button dismisses the drawer.

Hero Section

Centered-Minimal Variant

Matcha uses the centered-minimal hero variant instead of a fullscreen slider. This hero style features a contained, centered composition with ample white space around the content. The result is a refined, editorial look that lets your imagery and messaging breathe.

In the theme editor, select the hero section on your homepage template. The centered-minimal variant supports:

• Hero image — A single high-quality image displayed within a contained frame. Recommended size: 1400 x 700px. The image is displayed at a max-width of 1100px with rounded corners.
• Heading — Large centered text overlaid on or below the image. Supports two sizes: large (hero-scale) and medium (section-scale).
• Subheading — A supporting line of text below the heading with lighter weight and reduced opacity.
• Button — A single centered call-to-action button with customizable text, URL, and style (filled sage green or outline).
• Text position — Place the heading and subheading over the image (with overlay) or below the image in a separate text block.
• Overlay opacity — When text is positioned over the image, control the dark overlay from 0% to 60% for readability.

Image Fallback

If no hero image is uploaded, the hero section gracefully falls back to a solid background color with your heading text centered on top. The fallback background color is configurable under the hero section settings. This ensures your homepage always looks intentional, even before you have added imagery.

Text Customization

All hero text supports rich formatting options:

• Font override — Use the global heading font or select a different font just for the hero heading.
• Text color — Override the default text color for the hero section independently.
• Text alignment — Center (default), left, or right alignment.
• Heading size — Choose from small, medium, large, or extra-large presets.
• Animation — Text can fade in, slide up, or appear without animation when the page loads.

Product Page

Editorial Layout

Matcha product pages use an editorial layout that presents product information in a storytelling format. Instead of a standard two-column grid, the layout alternates between image-focused and text-focused blocks as the customer scrolls down:

• Top section — Large product image on the left with title, price, variant picker, and add-to-cart on the right.
• Story block — Full-width text section below the fold for long-form product storytelling.
• Image gallery — Additional product images displayed in a staggered two-column layout with parallax scroll effects.
• Details accordion — Collapsible sections for shipping, returns, ingredients, and custom content.

Flavor Profiles

Each product can display tasting notes and flavor characteristics using a clean badge system integrated directly into the product page.

Setup:

1. In Shopify Admin > Products, add tags to your products using the format flavor:Chocolate, flavor:Citrus, flavor:Caramel, etc.
2. The theme reads tags prefixed with flavor: and renders them as styled pill badges near the product title.
3. Badge colors are automatically derived from a curated palette that matches the Matcha sage green aesthetic.
4. To override badge colors, go to Theme settings > Coffee Features > Flavor Badge Colors.

Variant Picker

The product page supports multiple variant picker styles. In the product section settings, choose between:

• Buttons — Minimal pill-style buttons with sage green active states. This is the default and best matches the Matcha aesthetic.
• Dropdown — Standard dropdown selectors for each option (Size, Grind, Roast, etc.).
• Color swatches — Visual color circles for blend or packaging color options.

Image Gallery

The product page image gallery supports stacked, carousel, or thumbnail grid layouts. Images support pinch-to-zoom on mobile and click-to-zoom on desktop. The gallery automatically groups images by variant when variant-specific images are assigned.

Collection Page

Masonry 2-Column Grid

Matcha uses a masonry-style 2-column grid for collection pages that creates visual variety by alternating between tall and standard card heights. This editorial approach makes browsing feel more like reading a curated magazine than scrolling a product catalog.

Layout pattern:

• Column A — Tall cards with larger images and more vertical space for product titles and flavor badges.
• Column B — Standard cards offset vertically to create the masonry stagger effect.
• Feature cards — Every 5th product spans both columns as a horizontal feature card with a landscape image and extended description.

To configure the masonry layout, go to Theme settings > Collection Page > Layout and select Masonry 2-Column. You can also switch to a standard 3-column or 4-column grid if you prefer a more conventional layout.

Filters

Collection pages include a sidebar filter panel powered by Shopify's native storefront filtering API. Filters are automatically generated based on your product data. Available filter types include:

• Price range slider — Interactive dual-handle slider for min/max price filtering.
• Roast level — Filter by roast level when products use the custom.roast_level metafield.
• Origin — Filter by coffee origin region.
• Flavor tags — Filter by flavor profile tags (chocolate, fruity, nutty, etc.).
• Availability — Toggle between in-stock and out-of-stock products.
• Product type — Filter by product type (whole bean, ground, pods, equipment, etc.).

To configure which filters appear, go to Shopify Admin > Online Store > Navigation > Collection and search filters. The theme displays all filters you enable there, styled with the Matcha sage green accents.

Sort Options

A sort dropdown appears at the top of every collection page. Customers can sort products by: Featured (manual order), Best selling, Alphabetical (A-Z and Z-A), Price (low to high and high to low), and Date (newest and oldest). The selected sort preference updates the page URL for bookmarkable results.

Cart Drawer

AJAX Cart

Matcha includes a fully AJAX-powered cart drawer that slides in from the right side of the screen when a customer adds a product. The entire add-to-cart and update process happens without any page reloads, providing a seamless shopping experience. To configure:

1. In the theme editor, go to Theme settings > Cart.
2. Set Cart type to Drawer. Alternatively, choose Page for a traditional full-page cart.
3. Enable Cart recommendations to show complementary products inside the cart drawer.
4. Enable Cart note to let customers add special instructions (e.g., grind preferences, gift messages).
5. Toggle Trust badges to display security and payment icons below the checkout button.

Free Shipping Bar

The free shipping bar displays a progress indicator showing how much more the customer needs to spend to qualify for free shipping. It updates dynamically as items are added or removed, with a smooth animated fill effect in sage green.

1. Navigate to Theme settings > Cart > Free shipping bar.
2. Enable the free shipping bar toggle.
3. Set the Free shipping threshold amount (e.g., $50, $75). This should match your actual shipping policy.
4. Customize the message text. Use the {amount} placeholder for the remaining amount. Example: "Add {amount} more for free shipping!"
5. When the threshold is reached, a celebration message appears with a checkmark animation.

Upsell Products

The cart drawer can display upsell product recommendations below the cart items. These are pulled from Shopify's product recommendations API or from a manually curated collection. Customers can add upsell items directly from the cart drawer without leaving the page.

Terms Checkbox

Require customers to agree to your terms and conditions before proceeding to checkout. Enable this under Theme settings > Cart > Terms checkbox. Link the checkbox label text to your terms and conditions page. When enabled, the checkout button remains disabled until the checkbox is checked.

Coffee Features

Flavor Wheel

The flavor wheel section displays visual intensity bars for flavor categories, helping customers understand the tasting profile of each coffee at a glance.

Setup:

1. In the theme editor, click Add section > Flavor Wheel on the product page template.
2. Click Add block for each flavor category.
3. For each flavor, set:

• Flavor Name — e.g., "Chocolate", "Nutty", "Citrus", "Floral"
• Intensity — A value from 1 to 5
• Color — Choose a color for the intensity bar. Defaults to shades within the sage green palette.

Bars render horizontally with filled segments matching the intensity value. The Matcha flavor wheel uses soft rounded bars that complement the minimal aesthetic.

Brewing Guide

The brewing guide section displays step-by-step method cards with specifications for grind size, coffee-to-water ratio, water temperature, and brew time.

Setup:

1. In the theme editor, click Add section > Brewing Guide.
2. Click Add block to add a brewing method card.
3. For each method, configure:

• Method Name — e.g., "Pour Over", "French Press", "AeroPress", "Cold Brew"
• Icon — Choose from built-in brewing method icons or upload a custom SVG
• Grind Size — e.g., "Medium-Fine"
• Ratio — e.g., "1:16"
• Temperature — e.g., "200 F / 93 C"
• Brew Time — e.g., "3:30"
• Steps — Add numbered steps for the brewing process

Each method renders as a clean card with rounded corners, a subtle sage green border, and a specs grid. The cards use a zigzag layout on desktop for visual variety.

Trust Ticker

The trust ticker is a continuously scrolling horizontal bar that displays trust signals, certifications, and key selling points. It appears below the header and scrolls automatically from right to left.

Setup:

1. In the theme editor, select the Trust Ticker section (typically placed directly below the header or above the footer).
2. Click Add block to add ticker items. Each item supports:

• Text — The message to display, e.g., "Free Shipping Over $50", "Roasted Fresh Daily", "100% Arabica"
• Icon — Optional inline icon (checkmark, leaf, star, truck, etc.) displayed before the text
• Link — Optional URL to make the ticker item clickable

The ticker automatically duplicates its content to create a seamless infinite scroll loop. Scrolling speed is configurable in the section settings (slow, medium, or fast). On hover, the ticker pauses so customers can read the content.

Zigzag Benefits Layout

The benefits section uses a zigzag editorial layout that alternates image and text content on each row. Each row presents a key selling point with a large image on one side and a heading, description, and optional button on the other.

Setup:

1. In the theme editor, click Add section > Zigzag Benefits.
2. Click Add block for each benefit row.
3. For each block, configure:

• Image — A high-quality photo representing the benefit. Recommended: 800 x 600px.
• Heading — The benefit title, e.g., "Ethically Sourced", "Roasted to Order"
• Description — A paragraph explaining the benefit in detail.
• Button text & URL — Optional CTA to learn more.

Rows automatically alternate: the first row shows the image on the left and text on the right, the second row reverses, and so on. On mobile, all rows stack vertically with the image on top.

Testimonials — Large Single Quotes

Matcha displays customer testimonials as large single-quote blocks rather than a carousel of small cards. Each testimonial takes up significant vertical space with oversized quotation marks, the review text in a large serif font, and the customer name below.

Setup:

1. In the theme editor, click Add section > Testimonials.
2. Click Add block for each testimonial.
3. For each block, configure:

• Quote text — The customer review or testimonial text.
• Customer name — Attribution name.
• Customer title — Optional subtitle, e.g., "Verified Buyer" or "Subscriber since 2024".
• Star rating — Display 1-5 stars above the quote (optional).

Testimonials display one at a time in a vertical stack on the homepage. On desktop, each quote block is centered with generous padding and a decorative oversized opening quotation mark in sage green. Navigation between testimonials uses a simple fade transition triggered by scroll or dot indicators.

Newsletter — Split Layout with Social Proof

The newsletter section uses a split layout: one half contains the signup form with heading, description, and email input, while the other half displays social proof metrics such as subscriber count, average rating, and trust badges.

Setup:

1. In the theme editor, click Add section > Newsletter.
2. Configure the left panel (signup form):

• Heading — e.g., "Join the Morning Club"
• Description — Supporting text explaining the value of subscribing.
• Discount code — Optionally display a code after successful submission.
• Form integration — Integrates with Shopify customer list by default. Can connect to Klaviyo, Mailchimp, or other platforms via their Shopify app.

Configure the right panel (social proof):

• Subscriber count — Display a number like "12,000+ coffee lovers" to build credibility.
• Average rating — Show your store's average review score.
• Trust icons — Add certification or payment security badges.
• Background image — Optional lifestyle image behind the social proof panel.

Featured Collection — Masonry 2-Column

The homepage featured collection section uses the same masonry 2-column layout as the collection page, displaying a curated selection of products in an editorial grid.

Setup:

1. In the theme editor, click Add section > Featured Collection.
2. Select the collection to feature from the dropdown.
3. Set the number of products to display (4, 6, 8, or 10).
4. Choose whether to show the "View all" button linking to the full collection page.

The masonry layout automatically assigns tall and standard card heights to create visual variety. The first product in the selection receives a larger card size for emphasis.

Freshness Counter

The freshness counter displays the number of days since the coffee was roasted, helping customers gauge freshness at a glance.

Setup:

1. Create a product metafield with the namespace and key custom.roast_date.
2. Set the metafield type to Date.
3. Enter the roast date for each product.
4. The counter calculates the days since roasting in real time and displays a badge on the product page.

Display logic:

• 0-7 days: "Freshly Roasted" with a green badge
• 8-21 days: Shows the day count with a neutral badge
• 22+ days: Shows the day count with a subtle muted style

Origin Card

The origin card displays the coffee's sourcing information in a clean card on the product page.

Setup:

1. Create the following product metafields in Shopify Admin:

• custom.origin_region (Single line text) — e.g., "Yirgacheffe, Ethiopia"
• custom.origin_altitude (Single line text) — e.g., "1,900 - 2,200 masl"
• custom.origin_process (Single line text) — e.g., "Natural"
• custom.origin_variety (Single line text) — e.g., "Heirloom"

The origin card automatically appears on the product page when at least one origin metafield has a value. In Matcha, the card uses a clean white background with sage green accents and subtle iconography for each data point.

Sticky Navigation

How It Works

Matcha includes a dedicated sticky navigation bar that is always visible as the customer scrolls. This is separate from the main header sticky behavior and provides persistent access to key navigation elements.

The sticky navigation bar appears at the top of the viewport once the customer scrolls past the main header. It contains a compact version of your primary navigation, the cart icon with item count, and an optional search icon. The bar is thinner than the main header (48px height) to minimize content obstruction.

Transparent vs Solid Mode

The sticky navigation supports two visual modes that you can configure under Theme settings > Sticky Navigation:

• Solid mode — The sticky bar has a solid white (or custom color) background at all times. This provides maximum contrast and readability against any page content. Best for stores with busy or colorful imagery.
• Transparent mode — The sticky bar starts with a transparent background when overlaying the hero section and transitions to a solid background once the customer scrolls past the hero. This creates a seamless visual integration with the hero image. Navigation links switch from white (over hero) to dark (over content) automatically.

Configuration

Navigate to Theme settings > Sticky Navigation to configure:

• Enable sticky navigation — Master toggle. When disabled, only the main header is shown.
• Mode — Solid or transparent (as described above).
• Background color — The solid background color for the sticky bar. Default matches your header background.
• Text color — Navigation link color in the sticky bar.
• Show logo — Toggle whether a small version of your logo appears in the sticky bar.
• Show search — Toggle the search icon in the sticky bar.
• Show cart count — Display the number of items in the cart next to the cart icon.
• Transition speed — Control how quickly the sticky bar appears and disappears (fast, medium, slow).

License & Activation

License Terms

Each Matcha purchase grants you a single-store license. This means you may install and use the theme on:

• One (1) live production Shopify store
• One (1) development or staging store for testing purposes

Using the theme on additional production stores requires purchasing additional licenses. Contact our support team for multi-license pricing.

Entering Your License Key

After purchasing the theme, you will receive a license key via email. To activate:

1. Install the theme on your Shopify store following the installation steps above.
2. Open the theme editor and navigate to Theme settings > License.
3. Enter your license key in the License key field.
4. Click Save. The theme will verify your license against our server and activate all premium features.

Removing the Watermark

The unlicensed version of Matcha displays a small "Theme by beBriz" watermark in the footer and a periodic toast notification reminding you to activate. Once you enter a valid license key:

• The footer watermark is automatically removed.
• Toast notifications stop appearing.
• All premium sections and features become fully functional.
• Future theme updates are unlocked for your store.

Domain Verification

Your license is tied to a single Shopify store domain. During activation, the theme records your store's .myshopify.com domain as the authorized installation. This is a one-time process. If you need to transfer the theme to a different store or change your store domain, contact our support team with your license key and the new domain to update the verification record.

Need Help?

If you cannot find the answer to your question in this documentation, visit our support page to contact our team directly. We typically respond within 24 hours on business days.