Using Variables in Themes

Once users fill out your configuration form, the data is stored in salesive.config.json. This guide shows you how to access and use these variables in your theme.

Configuration File Structure

When a user submits your form, their data is saved to salesive.config.json:

{
    "name": "my-theme",
    "version": "1.0.0",
    "description": "My Salesive Theme",
    "author": "Theme Developer",
    "errorHandling": {
        "reportErrors": false,
        "errorReportingUrl": "",
        "showComponentStack": true,
        "showReloadButton": true,
        "customErrorMessages": {
            "default": "Something went wrong in the application.",
            "network": "Network error. Please check your connection.",
            "notFound": "The requested resource was not found."
        }
    },
    "variables": {
        "heroTitle": "Welcome to My Store",
        "heroImage": "https://files.salesive.com/api/files/abc123",
        "primaryColor": "#0d65d9",
        "phoneNumber": "+1 (555) 123-4567",
        "email": "[email protected]"
    }
}

Variable Structure

All form field values are stored in the variables object, using the field id as the key:

{
  "id": "heroTitle",
  "type": "text",
  "label": "Hero Title",
  "default": "Welcome"
}

Accessing Variables

Salesive provides the salesive-dev-tools package for accessing configuration variables in your React themes.

Installation

Install the package in your theme project:

npm install salesive-dev-tools
# or
yarn add salesive-dev-tools
# or
pnpm add salesive-dev-tools

Setup

1. Configure Vite Plugin

Add the Salesive config plugin to your vite.config.js:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { salesiveConfigPlugin } from "salesive-dev-tools";

export default defineConfig({
    plugins: [react(), salesiveConfigPlugin()],
});

The plugin automatically injects your config into the application during development.

2. Create Configuration File

Your salesive.config.json file should be in the project root with variables from the form:

{
    "name": "my-theme",
    "version": "1.0.0",
    "description": "My Salesive Theme",
    "author": "Your Name",
    "variables": {
        "heroTitle": "Welcome to My Store",
        "heroImage": "https://files.salesive.com/api/files/abc123",
        "primaryColor": "#0d65d9",
        "phoneNumber": "+1 (555) 123-4567",
        "email": "[email protected]"
    }
}

Using Variables in React Components

Using the React Hook

The useSalesiveConfig hook is the primary way to access variables in React components:

import { useSalesiveConfig } from "salesive-dev-tools";

function Hero() {
    // Get specific variables
    const heroTitle = useSalesiveConfig("heroTitle");
    const heroImage = useSalesiveConfig("heroImage");
    const primaryColor = useSalesiveConfig("primaryColor");

    return (
        <div
            className="hero"
            style={{
                backgroundImage: `url(${heroImage})`,
                backgroundColor: primaryColor,
            }}
        >
            <h1>{heroTitle}</h1>
        </div>
    );
}

Getting All Variables

You can also retrieve all variables at once:

import { useSalesiveConfig } from "salesive-dev-tools";

function Hero() {
    // Get all variables
    const allVariables = useSalesiveConfig();

    return (
        <div
            className="hero"
            style={{ backgroundImage: `url(${allVariables.heroImage})` }}
        >
            <h1>{allVariables.heroTitle}</h1>
            <p>Contact: {allVariables.email}</p>
        </div>
    );
}

Using in Non-Component Code

For accessing config outside of React components, use the helper function:

import { getSalesiveConfig } from "salesive-dev-tools";

// Get a specific variable
const appName = getSalesiveConfig("heroTitle");

// Get all variables
const allVariables = getSalesiveConfig();

Dynamic Configuration Updates

Update configuration values at runtime and all components will automatically re-render:

import { updateSalesiveConfig, setSalesiveConfig } from "salesive-dev-tools";

// Update a specific variable
setSalesiveConfig("primaryColor", "#ff0000");

// Update multiple variables at once
updateSalesiveConfig({
    variables: {
        primaryColor: "#ff0000",
        heroTitle: "Updated Title",
    },
});

// Use a function to update based on previous state
updateSalesiveConfig((prevConfig) => ({
    ...prevConfig,
    variables: {
        ...prevConfig.variables,
        heroTitle: `${prevConfig.variables["heroTitle"]} - Updated`,
    },
}));

All components using useSalesiveConfig will automatically update when configuration changes.

CSS Variables

The plugin automatically injects all variables as CSS custom properties:

function ThemedButton() {
    const primaryColor = useSalesiveConfig("primaryColor");

    return <button style={{ backgroundColor: primaryColor }}>Click Me</button>;
}

Or use the auto-injected CSS variables directly:

.button-primary {
    background-color: var(--primaryColor);
}

.text-accent {
    color: var(--accentColor);
}

Variable Types and Usage

Text Variables

Use text variables for content throughout your theme:

import { useSalesiveConfig } from "salesive-dev-tools";

function ContactInfo() {
    const storeName = useSalesiveConfig("storeName");
    const aboutUs = useSalesiveConfig("aboutUsDescription");
    const email = useSalesiveConfig("contactEmail");
    const phone = useSalesiveConfig("phoneNumber");
    const website = useSalesiveConfig("websiteUrl");

    return (
        <div>
            <h1>{storeName}</h1>
            <p>{aboutUs}</p>
            <a href={`mailto:${email}`}>{email}</a>
            <a href={`tel:${phone}`}>{phone}</a>
            <a href={website} target="_blank">
                Visit Website
            </a>
        </div>
    );
}

Media Variables

Single Image

import { useSalesiveConfig } from "salesive-dev-tools";

function Logo() {
    const logo = useSalesiveConfig("logo");

    return <img src={logo} alt="Store Logo" className="logo" />;
}

Multiple Images (Array)

import { useSalesiveConfig } from "salesive-dev-tools";

function BannerCarousel() {
    const heroBanners = useSalesiveConfig("heroBanners");

    return (
        <div className="carousel">
            {heroBanners.map((banner, index) => (
                <img key={index} src={banner} alt={`Banner ${index + 1}`} />
            ))}
        </div>
    );
}

Color Variables

Use color variables for theming:

import { useSalesiveConfig } from "salesive-dev-tools";

function ThemedSection() {
    const primaryColor = useSalesiveConfig("primaryColor");
    const textColor = useSalesiveConfig("textColor");

    return (
        <div style={{ backgroundColor: primaryColor }}>
            <h2 style={{ color: textColor }}>Title</h2>
        </div>
    );
}

Or use CSS with auto-injected variables:

.hero {
    background-color: var(--primaryColor);
}

.button {
    background-color: var(--accentColor);
    color: var(--buttonTextColor);
}

.link {
    color: var(--secondaryColor);
}

Select Variables

Single Select

import { useSalesiveConfig } from "salesive-dev-tools";

function Content() {
    const layoutStyle = useSalesiveConfig("layoutStyle");

    // Use in className
    return (
        <div className={`content content--${layoutStyle}`}>
            {/* Content here */}
        </div>
    );
}

// Or conditional rendering
function LayoutContent() {
    const layoutStyle = useSalesiveConfig("layoutStyle");

    if (layoutStyle === "grid") {
        return <GridLayout />;
    } else if (layoutStyle === "list") {
        return <ListLayout />;
    }
    return <MasonryLayout />;
}

Multi Select (Array)

import { useSalesiveConfig } from "salesive-dev-tools";

function Features() {
    const enabledFeatures = useSalesiveConfig("enabledFeatures");

    return (
        <>
            {enabledFeatures.includes("wishlist") && <WishlistButton />}
            {enabledFeatures.includes("cart") && <CartIcon />}
            {enabledFeatures.includes("reviews") && <ReviewSection />}
        </>
    );
}

Default Values

Always provide fallback values in case a variable is not set:

import { useSalesiveConfig } from "salesive-dev-tools";

function Hero() {
    const heroTitle = useSalesiveConfig("heroTitle") || "Welcome to Our Store";
    const primaryColor = useSalesiveConfig("primaryColor") || "#0d65d9";

    return (
        <div style={{ backgroundColor: primaryColor }}>
            <h1>{heroTitle}</h1>
        </div>
    );
}

Complete Example

Here’s a complete example showing how to use various variable types:

Form Schema
Config Output
Theme Usage

{
  "pages": [
    {
      "page": "home",
      "title": "Home Page",
      "sections": [
        {
          "id": "hero",
          "title": "Hero Section",
          "fields": [
            {
              "id": "heroTitle",
              "type": "text",
              "inputType": "text",
              "label": "Hero Title",
              "default": "Welcome",
              "required": true
            },
            {
              "id": "heroSubtitle",
              "type": "text",
              "inputType": "textarea",
              "label": "Hero Subtitle",
              "required": false
            },
            {
              "id": "heroBanners",
              "type": "media",
              "mediaType": "image",
              "label": "Hero Banners",
              "multiple": true,
              "maxItems": 5,
              "required": true
            }
          ]
        },
        {
          "id": "colors",
          "title": "Brand Colors",
          "fields": [
            {
              "id": "primaryColor",
              "type": "color",
              "label": "Primary Color",
              "default": "#0d65d9",
              "required": true
            }
          ]
        }
      ]
    }
  ]
}

Best Practices

Always Provide DefaultsNever assume a variable will be set. Always provide fallback values to prevent broken layouts when variables are missing.

Sanitize User InputIf displaying user-provided text or URLs, sanitize the input to prevent XSS attacks, especially for HTML rendering.

Variable Naming

Use descriptive, semantic names: heroTitle instead of title1
Follow camelCase convention: primaryColor, phoneNumber
Be consistent across your entire theme
Document which variables are required vs optional

Testing Variables

Development Testing

Create a test salesive.config.json with sample data:

{
  "variables": {
    "heroTitle": "Test Hero Title",
    "heroImage": "https://via.placeholder.com/1920x1080",
    "primaryColor": "#ff0000",
    "phoneNumber": "+1 (555) 123-4567"
  }
}

Production Validation

Before deploying your theme:

Test with minimal required variables only
Test with all variables filled
Test with very long text values
Test with special characters in text fields
Test with various image sizes and formats
Test with all possible select option combinations

Variable Documentation

Document your theme’s variables in a README.md:

## Required Variables

-   `heroTitle` (string): Main hero section title
-   `primaryColor` (hex): Primary brand color
-   `logo` (image URL): Store logo

## Optional Variables

-   `heroSubtitle` (string): Optional hero subtitle
-   `secondaryColor` (hex): Secondary brand color (default: #64748b)

This helps users understand what each variable does and which ones are required.

Getting Started

Schema Reference

Implementation

Using Variables in Themes

Using Variables in Themes

Configuration File Structure

Variable Structure

Accessing Variables

Installation

Setup

1. Configure Vite Plugin

2. Create Configuration File

Using Variables in React Components

Using the React Hook

Getting All Variables

Using in Non-Component Code

Dynamic Configuration Updates

CSS Variables

Variable Types and Usage

Text Variables

Media Variables

Single Image

Multiple Images (Array)

Color Variables

Select Variables

Single Select

Multi Select (Array)

Default Values

Complete Example

Best Practices

Testing Variables

Development Testing

Production Validation

Variable Documentation

Next Steps

View Examples

Schema Structure

Getting Started

Schema Reference

Implementation

​Using Variables in Themes

​Configuration File Structure

​Variable Structure

​Accessing Variables

​Installation

​Setup

​1. Configure Vite Plugin

​2. Create Configuration File

​Using Variables in React Components

​Using the React Hook

​Getting All Variables

​Using in Non-Component Code

​Dynamic Configuration Updates

​CSS Variables

​Variable Types and Usage

​Text Variables

​Media Variables

​Single Image

​Multiple Images (Array)

​Color Variables

​Select Variables

​Single Select

​Multi Select (Array)

​Default Values

​Complete Example

​Best Practices

​Testing Variables

​Development Testing

​Production Validation

​Variable Documentation

​Next Steps

View Examples

Schema Structure

Using Variables in Themes

Configuration File Structure

Variable Structure

Accessing Variables

Installation

Setup

1. Configure Vite Plugin

2. Create Configuration File

Using Variables in React Components

Using the React Hook

Getting All Variables

Using in Non-Component Code

Dynamic Configuration Updates

CSS Variables

Variable Types and Usage

Text Variables

Media Variables

Single Image

Multiple Images (Array)

Color Variables

Select Variables

Single Select

Multi Select (Array)

Default Values

Complete Example

Best Practices

Testing Variables

Development Testing

Production Validation

Variable Documentation

Next Steps