The value your field produces is saved exactly like a normal field's, so it maps to a Salesforce field through the field's mapping the same way. The same file renders on Experience Cloud sites and on Salesforce Sites.

1. Write the field type

   A field type is an object with up to five functions. Only render is required, but a field that stores a value needs getValue too, or nothing is submitted.

   The container comes last. initialize receives the element your HTML was rendered into as its second argument, and getValue, setValue, and validate receive the same element as their last argument. Find your elements inside it. On an Experience Cloud site each field lives in a shadow root, where document.getElementById finds nothing, so a field type that looks itself up through document works only on Salesforce Sites.

   (function () {
       'use strict';
   
       // Read the per-field JSON an admin entered in the field editor.
       // Always guard the parse: this is admin-entered text, and a
       // broken field should fall back to defaults rather than
       // throw and take the whole form's rendering down with it.
       function configFor(field) {
           var defaults = { max: 5 };
           try {
               return Object.assign(defaults, JSON.parse(field.pluginConfiguration || '{}'));
           } catch (e) {
               return defaults;
           }
       }
   
       // Everything is found INSIDE the container QuikForms hands you.
       function valueInput(container) {
           return container ? container.querySelector('.star-rating-value') : null;
       }
   
       var starRating = {
           // Return an HTML STRING. QuikForms inserts it for you.
           render: function (field, context) {
               var cfg = configFor(field);
               var buttons = '';
               for (var i = 1; i <= cfg.max; i++) {
                   buttons += '<button type="button" data-star="' + i + '">*</button>';
               }
               // The hidden input carries the value. Use a class, not an id:
               // it is looked up inside the container, never on the page.
               return '<div class="star-rating">' + buttons +
                      '<input type="hidden" class="star-rating-value" value=""></div>';
           },
   
           // Called once the HTML above is in the page. Attach listeners here,
           // NOT in render: the elements do not exist yet during render.
           initialize: function (fieldId, container) {
               container.addEventListener('click', function (e) {
                   var btn = e.target.closest('[data-star]');
                   if (!btn) return;
                   var input = valueInput(container);
                   input.value = btn.getAttribute('data-star');
                   // A bubbling change event is how QuikForms learns the
                   // value changed. An Experience Cloud form reads the value
                   // only when it hears one.
                   input.dispatchEvent(new Event('change', { bubbles: true }));
               });
           },
   
           // How QuikForms reads the value. The container is the LAST argument.
           getValue: function (fieldId, container) {
               var input = valueInput(container);
               return input ? input.value : '';
           },
   
           // How QuikForms restores a value (session resume, or a
           // pre-populated value). The container is the LAST argument.
           setValue: function (fieldId, value, container) {
               var input = valueInput(container);
               if (input) input.value = value == null ? '' : String(value);
           },
   
           // Optional. Returns {isValid, errors}. Returning a bare string
           // does NOT fail validation: the caller reads .isValid.
           validate: function (fieldId, field, container) {
               if (field.isRequired && !starRating.getValue(fieldId, container)) {
                   return { isValid: false, errors: ['Please choose a rating.'] };
               }
               return { isValid: true, errors: [] };
           }
       };
   
       // The entry point named by JS_Entry_Point__c. QuikForms calls this
       // and hands you the registry, on both renderers.
       window.initStarRating = function (QuikFormsPlugins) {
           QuikFormsPlugins.register('star-rating', {
               name: 'star-rating',
               version: '1.0.0',
               fieldTypes: { starRating: starRating }
           });
       };
   })();

2. Deploy it as a Static Resource

   Name the resource something stable, for example StarRatingPlugin. That name goes in JS_Static_Resource__c, and the global function you defined goes in JS_Entry_Point__c. The entry point must be a plain global function name: QuikForms looks it up on window, so a dotted name such as MyPlugins.init is never found.

3. Register the plugin

   Create one QuikForms_Plugin__mdt record, here with the DeveloperName Star_Rating. Leave every Apex field blank, because there is no Apex.

   Field	Value
   Plugin_Type__c	FieldType
   JS_Static_Resource__c	StarRatingPlugin
   JS_Entry_Point__c	initStarRating
   Is_Active__c	checked
   Version__c	1.0.0

4. Tell the field editor it exists

   A second record, QuikForms_Custom_Field_Type__mdt, is what puts your field type in the field editor's Plugin Field Type list. Without it the plugin loads but no admin can choose it.

   Field	Value
   Plugin__c	Star_Rating, the plugin record you just created
   Field_Type_Name__c	starRating (must match the key in fieldTypes exactly, including case)
   Display_Label__c	Star Rating
   Category__c	Interactive
   Default_Configuration__c	{"max":5}

5. Use it

   Open a field in the field editor, from QuikField Manager or from the pencil on a field in the form builder, and go to the Options & Structure tab:

   • Plugin Field Type lists the field types of every active plugin, shown as the display label with its category, here Star Rating (Interactive). Choose it.
   • Plugin Configuration (JSON) is filled in from the type's Default_Configuration__c. Edit it for this field; it must be valid JSON before the field saves. This is what reaches your configFor() as field.pluginConfiguration.

   The field keeps its own Field Type as a fallback: if the plugin is later deactivated, the field renders as that type instead. Field definitions are shared, so the change applies to every form that uses the field.

The Plugin Field Type list is shown on the Professional plan. To copy a working example, see Range Slider, which is this recipe with ticks and a value bubble.

The Apex version

1. Implement the interfaces

   Every plugin implements quikforms.IQuikFormsPlugin. A validator adds quikforms.IQuikFormsFieldValidator, which also requires getValidationMode().

   A validator runs once for every submitted field, not once per form, so the first thing it does is decide whether the field in front of it is one it cares about. Without that check this example would demand a PO number in every field on every form.

   global class PurchaseOrderValidator implements quikforms.IQuikFormsPlugin, quikforms.IQuikFormsFieldValidator {
   
       private Boolean ready = false;
       private Set<String> fieldIds = new Set<String>{ 'poNumber' };
       private Set<String> allowedPrefixes = new Set<String>{ 'PO', 'SO' };
   
       global quikforms.QuikFormsPluginInfo getPluginInfo() {
           quikforms.QuikFormsPluginInfo info = new quikforms.QuikFormsPluginInfo();
           info.name = 'Purchase Order Validator';
           info.version = '1.0.0';
           info.description = 'Checks that a PO number starts with an allowed prefix.';
           return info;
       }
   
       // Whatever an admin put in Configuration_Schema__c on the plugin
       // record arrives here, already parsed. Never assume a key is present.
       global void initialize(Map<String, Object> configuration) {
           if (configuration != null && configuration.get('fieldIds') instanceof List<Object>) {
               fieldIds.clear();
               for (Object o : (List<Object>) configuration.get('fieldIds')) {
                   fieldIds.add(String.valueOf(o));
               }
           }
           if (configuration != null && configuration.get('allowedPrefixes') instanceof List<Object>) {
               allowedPrefixes.clear();
               for (Object o : (List<Object>) configuration.get('allowedPrefixes')) {
                   allowedPrefixes.add(String.valueOf(o));
               }
           }
           ready = true;
       }
   
       // A plugin that is not ready is skipped.
       global Boolean isReady() {
           return ready;
       }
   
       // Required by the interface. QuikForms decides which method to call
       // from Validation_Mode__c on the plugin record, not from this value.
       global quikforms.QuikFormsValidationMode getValidationMode() {
           return quikforms.QuikFormsValidationMode.SYNC_ONLY;
       }
   
       global quikforms.QuikFormsValidationResult validateSync(quikforms.QuikFormsValidationContext ctx) {
           // Called for EVERY submitted field. Pass anything that is not ours.
           if (!fieldIds.contains(ctx.fieldId)) {
               return quikforms.QuikFormsValidationResult.success();
           }
   
           String value = ctx.fieldValue == null ? '' : String.valueOf(ctx.fieldValue);
           if (String.isBlank(value)) {
               // Let the field's Required setting own this case.
               return quikforms.QuikFormsValidationResult.success();
           }
   
           quikforms.QuikFormsValidationResult result = new quikforms.QuikFormsValidationResult();
           if (!allowedPrefixes.contains(value.left(2).toUpperCase())) {
               // Shown to the visitor on this field, so write it for them.
               result.addError('A purchase order number starts with PO or SO.');
           } else {
               // Optional: replace what gets saved. Key it by the FIELD ID.
               result.setTransformedValue(ctx.fieldId, value.toUpperCase());
           }
           return result;
       }
   
       // Called instead of validateSync when Validation_Mode__c is Async.
       // It is not asynchronous: it also runs at submit, and the visitor waits.
       global quikforms.QuikFormsValidationResult validateAsync(quikforms.QuikFormsValidationContext ctx) {
           return validateSync(ctx);
       }
   }

2. Register it

   Field	Value
   Plugin_Type__c	Validator. Only records of this type run as validators.
   Apex_Class_Name__c	PurchaseOrderValidator
   Validation_Mode__c	Sync
   Configuration_Schema__c	{"fieldIds":["poNumber"],"allowedPrefixes":["PO","SO"]} (optional)
   Error_Behavior__c	What happens if the plugin itself throws: Fatal refuses the submission, Warn and Skippable let it through
   Is_Active__c	checked

   An objection appears on the field it names, in the visitor's form, like a failed Validation Regex. How server validation runs has the full contract.

The JavaScript version

For an instant rule, use the onValidate hook in a plugin's Static Resource, registered the same way as the field type in the first recipe. Any errors you return stop the submission and are shown to the visitor, with or without abort: true.

window.initMatchingEmails = function (QuikFormsPlugins) {
    QuikFormsPlugins.register('matching-emails', {
        name: 'matching-emails',
        hooks: {
            // fieldValues is keyed by field ID. Return synchronously: on a
            // Salesforce Sites form a returned Promise is not waited for.
            onValidate: function (context) {
                var a = context.fieldValues.email;
                var b = context.fieldValues.emailConfirm;
                if (a && b && a !== b) {
                    return { abort: true, errors: ['The two email addresses do not match.'] };
                }
            }
        }
    });
};

onValidate may also return modifiedValues, keyed by field ID. Those values are what gets submitted, while the visitor keeps seeing what they typed. That is how Input Masking saves a phone number without the formatting the visitor sees.

To copy a working example, see Smart Validation, which does cross-field rules on both sides.

There are two moments, both inside the submission and both after the submission has passed server validation:

Handlers run for every record-creating form, single-object and multi-object, and for survey submissions, where the target is Survey__c.

1. Implement the handler

   global class SourceStamper implements quikforms.IQuikFormsPlugin, quikforms.IQuikFormsSubmissionHandler {
   
       private Boolean ready = false;
   
       global quikforms.QuikFormsPluginInfo getPluginInfo() {
           quikforms.QuikFormsPluginInfo info = new quikforms.QuikFormsPluginInfo();
           info.name = 'Source Stamper';
           info.version = '1.0.0';
           info.supportedHooks.add('onBeforeSubmit');
           info.supportedHooks.add('onAfterSubmit');
           return info;
       }
   
       global void initialize(Map<String, Object> configuration) {
           ready = true;
       }
   
       global Boolean isReady() {
           return ready;
       }
   
       global quikforms.QuikFormsSubmissionResult onBeforeSubmit(quikforms.QuikFormsSubmissionContext context) {
           quikforms.QuikFormsSubmissionResult result = new quikforms.QuikFormsSubmissionResult();
   
           // modifyFieldValue changes what gets saved. The key is a QuikForms
           // FIELD ID ('leadSource' here is a field on this form), and QuikForms
           // writes the value to that field's mapped Salesforce field.
           result.modifyFieldValue('leadSource', 'Web Form');
   
           // To stop the submission instead:
           //   return quikforms.QuikFormsSubmissionResult.failure('We cannot accept this right now.');
           return result;
       }
   
       global quikforms.QuikFormsSubmissionResult onAfterSubmit(quikforms.QuikFormsSubmissionContext context) {
           // The record now exists. Do follow-up work here. A Task's WhatId
           // suits a Case or an Account; a Lead or Contact goes in WhoId.
           if (context.recordId != null && context.targetObjectApiName == 'Case') {
               insert new Task(
                   WhatId = context.recordId,
                   Subject = 'Review new submission',
                   ActivityDate = Date.today().addDays(1)
               );
           }
           // Returning null is fine: it means "nothing to report".
           return null;
       }
   }

   Keys are field IDs on every path. A key that is not a field on the form is used as a Salesforce field API name instead, on single-object forms only, which lets you stamp a column the form does not show (for example result.modifyFieldValue('Origin', 'Web') on a Case form). On a multi-object form or a survey, a key that is not one of the form's fields is ignored.

2. Register it, and decide what happens when it fails

   Field	Value
   Plugin_Type__c	SubmissionHandler. Only records of this type run as submission handlers.
   Apex_Class_Name__c	SourceStamper
   Error_Behavior__c	Warn keeps the submission if your plugin throws in onBeforeSubmit; Fatal rejects it
   Execution_Order__c	100
   Is_Active__c	checked

   Error_Behavior__c decides what a failure costs. A plugin that stamps a marketing source is usually Warn, since losing the stamp is better than losing the enquiry. A plugin that enforces a compliance rule is usually Fatal. An exception in onAfterSubmit never rejects the submission, whatever the setting, because the record already exists.

To copy a working example, see Submission Enrichment, which stamps metadata and creates follow-up Tasks.

1. Write the Apex that makes the call

   Two things arrive separately, and mixing them up is the usual mistake:

   • initialize() receives the plugin's own configuration, the JSON in Configuration_Schema__c on the plugin record. It is where settings such as the Named Credential belong, because a visitor cannot change them.
   • What the browser sent arrives on request.body, as a JSON string. Treat it as untrusted input.

   request.timeoutMs carries Timeout_Ms__c from the plugin record (10000 when blank). QuikForms does not apply it for you: pass it to setTimeout, as below.

   global class AddressLookup implements quikforms.IQuikFormsPlugin, quikforms.IQuikFormsCalloutHandler {
   
       private String namedCredential = 'AddressApi';
   
       global quikforms.QuikFormsPluginInfo getPluginInfo() {
           quikforms.QuikFormsPluginInfo info = new quikforms.QuikFormsPluginInfo();
           info.name = 'Address Lookup';
           info.version = '1.0.0';
           // Informational. The gate is Supports_Callout__c on the plugin record.
           info.supportsCallouts = true;
           return info;
       }
   
       // The plugin record's Configuration_Schema__c, parsed. NOT what the
       // browser sent: that is on request.body.
       global void initialize(Map<String, Object> configuration) {
           if (configuration != null && configuration.get('namedCredential') != null) {
               namedCredential = String.valueOf(configuration.get('namedCredential'));
           }
       }
   
       global Boolean isReady() {
           return true;
       }
   
       global quikforms.QuikFormsCalloutResponse executeCallout(quikforms.QuikFormsCalloutRequest request) {
           // The params your JavaScript passed, as a JSON string.
           Map<String, Object> params = String.isBlank(request.body)
               ? new Map<String, Object>()
               : (Map<String, Object>) JSON.deserializeUntyped(request.body);
           Object rawPostcode = params.get('postcode');
           String postcode = rawPostcode == null ? '' : String.valueOf(rawPostcode);
           if (String.isBlank(postcode)) {
               return quikforms.QuikFormsCalloutResponse.failure('No postcode supplied.');
           }
   
           HttpRequest req = new HttpRequest();
           // callout:AddressApi keeps the key out of your code entirely.
           req.setEndpoint('callout:' + namedCredential + '/lookup?postcode=' +
                           EncodingUtil.urlEncode(postcode, 'UTF-8'));
           req.setMethod('GET');
           // Timeout_Ms__c from the plugin record. A form the visitor is
           // waiting on must not hang on someone else's slow server.
           req.setTimeout(request.timeoutMs);
   
           try {
               HttpResponse res = new Http().send(req);
               if (res.getStatusCode() == 200) {
                   // body must be a JSON OBJECT, such as {"city":"..."}. It is
                   // parsed and handed to your JavaScript. An array or plain
                   // text fails the callout.
                   return quikforms.QuikFormsCalloutResponse.success(200, res.getBody());
               }
               // errorMessage reaches the browser. Do not pass a raw
               // third-party error through to a visitor.
               return quikforms.QuikFormsCalloutResponse.failure('Address lookup is unavailable.');
           } catch (Exception e) {
               return quikforms.QuikFormsCalloutResponse.failure('Address lookup is unavailable.');
           }
       }
   }

2. Call it from the browser

   QuikFormsPlugins.callout() is the bridge. pluginName is the plugin record's DeveloperName, here Address_Lookup. It returns a Promise resolving to the parsed JSON your Apex put on response.body.

   window.initAddressLookup = function (QuikFormsPlugins) {
       QuikFormsPlugins.register('address-lookup', {
           name: 'address-lookup',
           hooks: {
               // Fires when a field loses focus, which is the natural moment
               // to look something up.
               onFieldBlur: function (context) {
                   if (context.fieldId !== 'postcode' || !context.value) return;
   
                   // callout() takes ONE options object. It resolves to the
                   // data your Apex returned, and REJECTS on failure.
                   return QuikFormsPlugins.callout({
                       pluginName: 'Address_Lookup',
                       params: { postcode: context.value }
                   }).then(function (data) {
                       if (!data || !data.city) return;
                       // On a Salesforce Sites form, modifiedValues fills these
                       // fields as though the visitor had typed them.
                       return { modifiedValues: { city: data.city, county: data.county } };
                   }).catch(function () {
                       // A lookup failing must never block the form. Let them type it.
                       return undefined;
                   });
               }
           }
       });
   };

   Both renderers apply the modifiedValues a field hook returns, so the filled-in fields update on Experience Cloud and Salesforce Sites alike.

3. Register both halves as one plugin

   Create one QuikForms_Plugin__mdt record with the DeveloperName Address_Lookup:

   Field	Value
   Plugin_Type__c	Integration
   Apex_Class_Name__c	AddressLookup
   JS_Static_Resource__c	AddressLookupPlugin
   JS_Entry_Point__c	initAddressLookup
   Supports_Callout__c	checked. This is the gate: without it every callout is refused.
   Timeout_Ms__c	5000, delivered to your Apex as request.timeoutMs
   Configuration_Schema__c	{"namedCredential":"AddressApi"}
   Is_Active__c	checked

   Each callout counts toward the rate limit on both renderers. On a Salesforce Sites form it is also one request to the QuikForms REST endpoint, so it costs one API call; on an Experience Cloud site it costs none.

4. Let the guest user reach the credential

   A public form runs as the site's guest user, which has no access to anything by default. The QuikForms Guest permission set covers only QuikForms' own Turnstile credential, so give the guest user access to your External Credential's principal in a permission set of your own, or every lookup fails with a permissions error that looks like a bug in your code. See External Credential Access.

To copy a working example, see External Verification, which is this recipe end to end.