OptionKit — Documentation

Guide to installing and using OptionKit (version 0.3.1), the free product add-ons plugin for WooCommerce. Product page: https://007aj.com/optionkit.

1. Installation

Install and activate WooCommerce 8.0 or newer.
In WordPress, go to Plugins → Add New and install OptionKit, or upload the optionkit zip file with Upload Plugin (or copy the optionkit folder to /wp-content/plugins/).
Activate OptionKit on the Plugins screen. The database tables are created on activation.
Open WooCommerce → OptionKit.

If WooCommerce is missing, inactive or older than 8.0, OptionKit shows a notice and does nothing else until WooCommerce is ready. On WordPress 6.5 and newer, WordPress itself asks you to activate WooCommerce first.

If OptionKit Add-ons is active on the same site, OptionKit pauses itself and shows a notice. Both plugins use the same option groups, so nothing is lost; you can deactivate OptionKit.

2. Requirements and compatibility

Item	Requirement
WordPress	6.3 or later (tested up to 7.1)
PHP	7.4 or later (tested on 7.4 and 8.4)
WooCommerce	8.0 or later, required (tested up to 11.1)
Order storage	High-Performance Order Storage (HPOS) and legacy posts storage are both supported; compatibility with HPOS is declared
Cart and Checkout blocks	Supported through the Store API; compatibility is declared
Who can manage option groups	Users with the `manage_woocommerce` capability (store managers and administrators)

3. Where to find things

WooCommerce → OptionKit: the list of option groups, an Export JSON link per group, the Import group (JSON) form and a Status box (WooCommerce version, order storage type and whether the database tables are installed).
WooCommerce → OptionKit settings: Delete data on uninstall (off by default).
Product edit screen, Product data → OptionKit tab: Local option groups for that one product.

4. Creating an option group

Open WooCommerce → OptionKit and click Add group.
Enter a Name (and optionally a Slug).
Choose a Status: Draft groups are never shown to customers; Active groups are.
Set a Priority. When several groups apply to one product, lower numbers are shown first.
Choose the products under Assignment (see Assigning groups to products) and click Create group.
Click Add field to add the fields customers will fill in.

A group can be moved to the trash with Trash group at the bottom of its edit screen.

5. Fields

Type	What the customer sees
Text	A one-line text box, for example engraving text. Up to 500 characters unless you set a lower max length.
Text area	A multi-line text box; line breaks are kept. Up to 5,000 characters unless you set a lower max length.
Number	A number box with optional min, max and step, checked on the server.
Dropdown	One choice from a list.
Radio buttons	One choice, all choices visible.
Checkboxes	Any number of choices; each ticked choice adds its price.

Field settings

Label (required) and Description (help text shown under the field and linked to it for screen readers).
Placeholder and Default. For checkboxes, defaults are pre-ticked.
Required: required when the field is visible. Checked in the browser and again on the server.
Sort: order of the field inside the group.
Field price: used by text, text area and number fields when a value is entered (see Pricing types).
Limits: Max length for text fields; Min, Max and Step for number fields.
Choices (dropdown, radio buttons and checkboxes): a label, a value and a price per row. Click Add choice for more rows; rows without a label are ignored.
Conditional (basic): see Showing and hiding fields.

6. Pricing types

Each choice, and each text, text area or number field, can carry a price. The product page shows a live preview; the price that goes into the cart is always recalculated on the server from the product's own fields.

Price type	How it is charged
None	No charge.
Flat	The amount is added to the price of each item, so it is multiplied by the quantity.
% of base	A percentage of the product price (the variation's price for variable products), added to each item.
Per qty	The amount per item, multiplied by the quantity (the same calculation as Flat, labelled separately for clarity).
One-time	Added once per cart line, whatever the quantity. WooCommerce shows it spread over the line's unit price.

For dropdowns, radio buttons and checkboxes the choice price is used; for checkboxes every ticked choice adds its own price. For text, text area and number fields the field price is charged only when the customer enters a value. A cart line's unit price never goes below zero.

7. Assigning groups to products

On the group's edit screen, under Assignment:

All products.
Product IDs (include, comma-separated).
Product IDs (exclude): these products never get the group through its assignment.
Categories and Tags: tick the product categories and tags the group applies to. Categories are listed as a tree. A group assigned to a category also applies to products in its subcategories, at any depth (for example, a group on Furniture also reaches products that are only in Furniture → Tables → Desks). Tags match the tags a product has.

To add a group to one product, open the product, go to Product data → OptionKit and tick it under Local option groups. Only active groups are listed. A local group always applies to that product, in addition to global assignments.

Only Active groups are shown. When several groups apply, they are shown in priority order (lower first).

8. Showing and hiding fields

Each field can be shown or hidden based on one other field in the same group. In the field editor under Conditional (basic):

Choose Show when or Hide when.
Choose the field the condition depends on.
Choose an operator: equals, not equals, contains, is empty, is not empty, is checked or not checked.
Enter the value to compare with. For choice fields, use the choice's value (not its label).

Hidden fields are not charged and are not required. The server checks the same rules: values sent for hidden fields are dropped before they reach the cart.

9. Product page, cart and orders

Fields appear on the product page above the add-to-cart button, with an "Options total" and "Total" box that updates as the customer chooses.
Products with option fields show "Select options" in shop lists and product blocks, so customers open the product page and choose their options first.
Selections are checked against the product's own fields on the server: unknown keys, values that are not one of the field's choices and values of hidden fields are dropped. Text is length-capped, numbers are checked against min and max, and required options are enforced.
Selections are shown in the classic cart, the Cart and Checkout blocks, the order, order emails, the customer's account and the order screen, with HPOS or legacy order storage.

10. JSON export and import

On WooCommerce → OptionKit, click Export JSON next to a group to download it (fields, choices, prices, conditions and assignments). To bring a group in, use Import group (JSON). Imported groups are always created as Draft, so you can check them before activating. Assignments refer to product, category and tag IDs, which may differ between sites, so review them after importing to another site.

11. Free plugin limits

Up to 3 active option groups. Draft groups do not count.
Up to 15 fields per group.

When a limit is reached, a notice explains it. Existing groups keep working; deactivate a group (set it to Draft) or remove a field to make room.

12. Features in OptionKit Add-ons

OptionKit Add-ons is a separate, standalone paid plugin from 007AJ. It has everything in OptionKit without the group and field limits, plus range slider, date, file upload, calculated fee, signature, repeater and shortcode/HTML fields, formula and lookup-table prices, color, image and button swatches, several conditions per field with AND/OR matching, group layouts (accordion, tabs, steps, popup), editing options from the cart, starter templates, import tools for WooCommerce Product Add-Ons, PPOM and ThemeComplete EPO data, and option analytics. See the OptionKit Add-ons documentation.

It reads the same option groups. While it is active, OptionKit pauses itself, so you can switch without rebuilding anything.

13. Accessibility

The product page fields aim at WCAG 2.2 AA:

Every field has a label; descriptions and prices are linked to their inputs.
Radio buttons and checkboxes are grouped and named.
Visible keyboard focus and reduced-motion support.
Totals are announced politely to screen readers once typing pauses, not on every key.
A missing required option shows an inline message next to the field and moves focus to the first problem, before the browser's own message appears. Required options are also checked on the server.

Please report any barrier to admin@007aj.com.

14. Privacy and personal data

The options a customer chooses or types in (for example engraving text) are kept with the cart item and saved with the order items when the order is placed. They are stored on your own site only and kept as long as the order.
They are included in Tools → Export Personal Data.
Tools → Erase Personal Data: when WooCommerce is set to remove personal data from orders on erasure requests (WooCommerce → Settings → Accounts & Privacy), option values saved on that customer's orders are anonymised. Otherwise they are kept with the order and the eraser reports that they were retained. Option prices stay part of the order totals.
Suggested privacy policy text is added under Settings → Privacy.
OptionKit makes no outbound requests, sends nothing to 007AJ and does not track usage.

15. Deactivating, uninstalling and deleting data

Deactivating stops OptionKit but keeps everything. Deleting the plugin also keeps your settings and option groups unless you first tick Delete data on uninstall in WooCommerce → OptionKit settings; then the settings, the option group tables and the cache are removed. If OptionKit Add-ons is still installed, the shared option group tables are kept for it. Options already saved on orders are part of those orders and are never removed.

16. Known limits

One condition per field, based on another field in the same group.
Up to 3 active groups and 15 fields per group.
Field types are text, text area, number, dropdown, radio buttons and checkboxes; there are no formula prices, swatches, uploads or layouts in this plugin.
Excludes are by product ID.
Options cannot be changed from the cart; customers remove the line and add the product again.

17. Questions

Does OptionKit need WooCommerce?

Yes, WooCommerce 8.0 or newer.

Can I use it with variable products?

Yes. Groups are assigned to the product; "% of base" prices use the chosen variation's price.

Why is the total on the product page only a preview?

The browser cannot be trusted with prices. When the product is added to the cart, the server recalculates every option price from the product's own fields, so a changed page cannot change what is charged.

Is it compatible with HPOS and the block checkout?

Yes, both are declared and tested.

Does it slow down my shop?

No scripts or styles are loaded on pages without option fields. Where there are fields, OptionKit adds about 4 KB of script and 1 KB of styles (gzipped), and resolved option groups are cached between requests.

What happens to my data when I delete the plugin?

It is kept unless you tick "Delete data on uninstall" first. See Deactivating, uninstalling and deleting data.

Where do I get help?

Email admin@007aj.com.

18. Changelog

0.3.1

Fixed: a group assigned to a parent category now also applies to products that are only in one of its subcategories (any depth). Excludes work the same way.
The category list on the group screen is shown as a tree (subcategories indented under their parent).
Cached product lookups are cleared when a product category is added, moved or deleted, or when a product's categories or tags change.
Developer: new filter optionkit_match_child_categories (return false to match direct categories only, as before).

0.3.0

Accessibility: field labels and descriptions are linked to their inputs, radio buttons and checkboxes are grouped and named, the totals are announced to screen readers after typing pauses (instead of on every key), missing required options show an inline message and move focus to the first problem, visible focus outlines, and reduced motion support.
Performance: resolved option groups are cached in one non-autoloaded option between requests and cleared whenever a group, field, choice, rule or assignment changes.
Uninstall (when opted in) also removes the option group cache and tables the separate edition may have left behind.
Required options are checked before the browser's own bubble appears, with the same inline message.
Developer hooks: nested row values for extension field types, an order-level privacy erase action, a group-label filter and storefront validators/readers.

0.2.2

Field editor: readable field type names, text max length and number min / max / step settings; posted choice rows are sanitized field by field.
Option group list queries use prepared table names (Plugin Check).
Products whose only priced field needs no customer input are charged correctly.
Storefront form fields have consistent styling; checkbox defaults are pre-ticked.
Developer hooks: field types, price modes, field markup, validation, display values, storefront config and privacy export/erase.

0.2.1

Security: option selections are now checked against the product's own fields before they reach the cart or the order. Unknown keys, values that are not one of the field's choices and values of hidden fields are dropped.
Text and textarea values are length-capped; textarea keeps line breaks; numbers are validated against min/max on the server; checkbox min/max choices are enforced.
Store API: the cart item extension is now registered.
Product page total box showed the currency symbol as an HTML entity; fixed.
Field editor: more than two choices per field (blank rows plus an "Add choice" button).
Products with option fields show "Select options" in shop lists and product blocks.
Personal data exporter and eraser cover option values saved on orders; privacy policy text updated.
Performance: no database write on every request; active groups are loaded once per request.

0.2.0

Option group, field and choice editing, product/category/tag assignment (include/exclude and priority), per-product local groups, storefront fields and totals box, flat/%/qty/one-time pricing calculated on the server, cart and order item data, Store API cart item extension, limits of 3 active groups and 15 fields, basic conditionals, JSON import/export for one group.
HPOS and Cart/Checkout blocks compatibility declarations retained.

0.1.1

Code prefixes renamed to optionkit_ for wordpress.org guidelines. Database tables keep their names (okt_groups, okt_fields, okt_choices, okt_rules, okt_assignments).

0.1.0

Initial release scaffold: WooCommerce dependency check, HPOS and Cart/Checkout blocks compatibility declarations, option group tables, Option groups and Settings screens, opt-in uninstall clean-up, personal data exporter and eraser hooks, translation template.

Support: admin@007aj.com · Privacy · Terms · 007aj.com