KILB Canvas Product Configurator with Visual Previews

Getting Started

After installing the KILB Canvas Configurator, you will find a new menu entry "KILB Canvas Configurator" in the Content section of your Shopware Admin sidebar. Click it to open the configurator admin dashboard.

Step 1: Create a Configurator

Click "Create Configurator" and fill in the following fields:

• Name — An internal name for identification (e.g., "Shoe Configurator", "Phone Case Designer").
• Canvas Width / Height (px) — The base resolution of the canvas in pixels. This determines the aspect ratio and the quality of the generated images. Choose dimensions that match your product images (e.g., 800 x 800 for a square product).
• Preview Width / Height (px) — The display size of the live preview on the storefront (min 100, max 1024). The aspect ratio is locked to the canvas dimensions, so changing one value updates the other automatically.
• Background Image — Optionally select a background image from the Shopware media library. This image will be the base layer of the canvas, visible behind all other layers.
• Use canvas preview as line-item image — When enabled, the customer's designed canvas will be shown as the product image in the shopping cart and order confirmation instead of the default product image.

Click "Save" to create the configurator.

Step 2: Add Options

After saving the configurator, you will see the Options section. Click "Add Option" to create a new option.

• Label — The name displayed to the customer in the storefront (e.g., "Background", "Hair Color", "Your Name").
• Type — Choose Image for selectable image layers or Text for customer text input.
• Required — Enable this if the customer must make a selection or enter text before adding to cart.

Options are displayed in the order they appear in the list. Use the arrow buttons to reorder them.

Step 3: Add Option Values

Click "Edit" on an option to manage its values. Then click "Add Value".

For Image Options

Each value represents a selectable image layer:

• Label — The name shown on the selection button (e.g., "Blue", "Wood", "Marble").
• Image Mask — Select the image layer from the Shopware media library. This image will be overlaid on the canvas when the customer selects this value. Use transparent PNG files for best results.
• Selection Image — Optionally set a separate thumbnail image for the selection button. If not set, the image mask is used as fallback. This is useful when the image mask is a full-canvas layer but you want to show a small, cropped preview on the button.

For Text Options

Each value represents a text input field with its own configuration:

• Label — Descriptive name (e.g., "Front Text", "Back Engraving").
• Default Text — Pre-filled text the customer sees before typing. Can be translated per language.
• Max Characters — Limits the number of characters the customer can enter.

Position and Alignment (Both Types)

• Position X / Y — Coordinates in pixels on the canvas where the element is placed.
• Horizontal Alignment — Left, Center, or Right alignment relative to the position point.
• Vertical Alignment — Top, Center, or Bottom alignment relative to the position point.

Step 4: Configure Text Properties (Text Options Only)

For text option values, you can define the available colors, fonts, and sizes that customers can choose from. In the option value edit view, you will find the Properties section.

Adding Colors

1. Click "Add Color".
2. Enter a hex color code (e.g., #FF0000 for red).
3. Optionally set the opacity (1 = fully opaque, 0 = fully transparent).
4. Click "Add".
5. Repeat for all colors you want to offer. You can mark one color as the default.

Adding Fonts

Fonts must be uploaded to your Shopware media library before they can be used:

1. Open the Shopware Admin and navigate to Content > Media.
2. Create a folder named exactly KilbCanvasConfiguratorFonts (case-sensitive, no spaces).
3. Download the one or multiple available fonts from here: https://canvas-configurator.kilb.tech/fonts  -> the number of available fonts will continuously increased
4. Upload the available font PDF files in your media library's folder.
5. Return to the configurator admin dashboard and edit your text option value.
6. In the Font Properties section, click "Add Font".
7. Select a font from the dropdown — it lists all TTF files found in the KilbCanvasConfiguratorFonts folder.
8. Click "Add". Repeat for all fonts you want to offer.
9. Mark one font as the default that will be pre-selected for the customer.

Adding Sizes

1. Click "Add Size".
2. Enter the font size in pixels (e.g., 24).
3. Click "Add".
4. Repeat for all sizes you want to offer. Mark one as the default.

Important: For text to render correctly on the canvas, each text option value should have at least one color, one font, and one size configured.

Step 5: Assign Products

Navigate to the Products tab of your configurator. Here you can link the configurator to one or more Shopware products:

1. Click "Assign Product".
2. Use the search field to find products by name.
3. Click a product to assign it. The configurator will now appear on that product's detail page in the storefront.
4. Product variants are supported — you can assign the configurator to individual variants.

A single configurator can be assigned to multiple products. To remove an assignment, click "Remove" next to the product.

Step 6: Translations

If your shop supports multiple languages, you can translate all texts (configurator name, option labels, option value labels, default texts) per language. Edit any entity and switch to the desired language to add translations manually.

Alternatively, use the "Translate Missing" button on the configurator edit page. This AI-powered feature automatically translates all missing texts across all your configured shop languages in one click.

Managing Orders

Navigate to the Orders section in the configurator admin dashboard. Here you see all orders that contain configured products.

• Use the search field to filter by order number or configurator name.
• Click "Preview" to open a canvas preview of the customer's design.
• In the preview modal, you can see all customer selections (chosen options, entered text, font, color, size).
• Use the export options to download the design:
  • PNG — Standard image format, ideal for print production.
  • WebP — Compressed image format for digital use.
  • PDF — Vector-quality export with embedded fonts, ideal for professional printing.
  • JSON — Full FabricJS canvas state for archival or re-rendering.
• Adjust the resolution scale factor to control export quality.
• Toggle "Include Background Image" to include or exclude the background layer.
• Mark orders as "Done" to track your fulfillment progress.

Duplicating a Configurator

To create a similar configurator without starting from scratch, click the "Copy" button on any existing configurator. This duplicates the configurator including all its options, option values, and property configurations. The copy will appear with the same name — rename it to distinguish it from the original.