Minsky Formkit Webform

Vue 3 module that integrates Drupal Webforms with FormKit, providing validation rules, multi-step support, localization, and styling utilities commonly required in Minsky projects.

Local development

Install dependencies:

  yarn install

Build the module:

  yarn run build

Run the development environment:

  yarn run dev

Using the package locally in another project

To install the module from a local path:

  yarn add /path-to-local-minsky-formkit-map

This is useful when developing the package and testing changes inside another project.

Installation

Install from npm:

  yarn add minsky-webform-formkit

Peer dependencies

Ensure the following peer dependencies are installed in your project:

"peerDependencies": {
  "vue": "^3.3.0",
  "@formkit/vue": "^1.7.0",
  "@formkit/core": "^1.7.0",
  "@formkit/addons": "^1.7.0",
  "@formkit/i18n": "^1.7.0",
  "gsap": "^3.12.0"
}

These dependencies are commonly used in FormKit projects and are required for the module to function correctly.

Install them if they are not already present:

yarn add vue @formkit/vue @formkit/core @formkit/addons @formkit/i18n gsap

Setup

Register the plugin in your Vue application together with your FormKit configuration.

App.vue example

import { createApp } from 'vue';
import CustomApp from './CustomApp.vue';

import MinskyWebformFormKit from 'minsky-webform-formkit';
import customConfig from './formkit.config';

const app = createApp(CustomApp);

app.use(MinskyWebformFormKit, customConfig);

app.mount('#app');

FormKit configuration

The module provides a default FormKit configuration that includes:

• multi-step form support
• validation rules
• localization (NL / EN / FR)
• custom inputs (phone, recaptcha)
• custom plugins

Example default configuration:

const config = {
  plugins: [customLabelPlugin, htmlHelpPlugin, createMultiStepPlugin({ allowIncomplete: false })],
  rules: {
    internationalPhone,
    phone,
    iban,
    vat,
    insz,
    timeRule,
  },
  messages: {
    nl: {
      validation: {
        phone: 'Dit is geen geldig telefoonnummer.',
        required: 'Dit veld is verplicht.',
        vat: 'Dit is geen geldig Btw-nummer.',
        is: 'Dit veld is verplicht.',
        timeRule({ node }) {
          return timeMessage(node);
        },
      },
    },
    en: {
      validation: {
        phone: 'This is not a valid phone number.',
        required: 'This field is required.',
        is: 'This field is required.',
        vat: 'This is not a valid VAT number.',
      },
    },
    fr: {
      validation: {
        phone: "Ce numéro de téléphone n'est pas valide.",
        required: 'Ce champ est obligatoire.',
        is: 'Ce champ est obligatoire.',
        vat: "Ce numéro de TVA n'est pas valide.",
      },
    },
  },
  locales: { nl, en, fr },
  locale: document.documentElement.lang,
  inputs: {
    phoneEnhanced: createInput(FormKitPhoneEnhanced),
    recaptcha: createInput(FormKitRecaptcha),
  },
};

export default config;

You can extend or override this configuration by passing your own config object when installing the plugin.

Styles

Import the default styles in your main stylesheet:

@import 'minsky-webform-formkit/dist/index';

Overriding styles

You can override CSS variables to customize the appearance of the form.

Example:

.webform-formkit--class-modifier {
  /* =========================================================================  */
  /* customize form here */
  /* =========================================================================  */
  --f-color: var(--c-blue-medium);
  --f-markup-color: var(--c-blue-dark);
  --f-input-text-color: var(--c-blue-medium);
  --f-input-border-color: var(--c-blue-light);
  --f-input-border-width: 0.1rem;
  --f-input-border-radius: 0.6rem;
  --f-input-padding: 1.5rem 2.4rem 1.3rem 2.4rem;
  --f-input-outline: 0.2rem solid var(--c-primary);
  --f-input-background-color: transparent;
  --f-input-font-family: inherit;
  --f-input-font-size: 1.6rem;
  --f-input-placeholder-color: var(--c-blue-light);
  --f-input-placeholder-font-style: inherit;
  --f-input-height: 5.2rem;
  --f-label-margin-bottom: 0.5rem;

  // description
  --f-description-color: var(--c-blue-dark);

  // submit btn
  --f-submit-btn-background-color: #000;
  --f-submit-btn-text-color: #fff;
  --f-submit-btn-border-color: #000;
  --f-submit-btn-border-width: 1px;
  --f-submit-btn-border-radius: 0;
  --f-submit-btn-font-family: inherit;
  --f-submit-btn-min-width: initial; // must be defined for mobile devices
  --f-submit-btn-min-height: initial; // must be defined for mobile devices
  --f-submit-btn-hover-text-color: #000;
  --f-submit-btn-hover-background-color: #fff;
  --f-submit-btn-hover-border-color: #000;
  --f-submit-btn-disabled-background-color: #e5e5e5;

  // radio-buttons & check-boxes
  --f-radio-check-border-color: var(--c-blue-light);
  --f-radio-check-background-color: #fff;
  --f-radio-check-background-color-active: var(--c-primary);
  --f-radio-check-decorater-height: 2rem;

  // help element
  --f-help-background-color: #000;
  --f-help-color: #fff;
  --f-help-border-color: #000;

  // other
  --f-form-gap: 1.2rem 2rem;
  --f-error-color: #{$c-red-status};
  --f-success-color: #{$c-green-status};

  // webform-fornkit props
  --f-loader-color: var(--c-primary);

  // multistep
  --f-multistep-background-color-tab: var(--c-blue-light);
  --f-multistep-color-tab: var(--c-blue-dark);
  --f-multistep-background-color-tab-active: var(--c-primary);
  --f-multistep-color-tab-active: var(--c-white);

  /* =========================================================================  */
  /* custom styles */
  /* =========================================================================  */
}

Apply the modifier via the classModifier property.

Component API

Properties

| property | required | default | description | | --------------- | -------- | ---------------------------------- | ----------------------------------------------------------------- | | id | true | | Drupal Webform ID | | api | optional | window.location.origin | API base URL used to fetch and submit the form | | classModifier | optional | | CSS class modifier applied to the root element | | defaults | optional | | Default form values | | schemeProcessor | optional | | Function to transform the FormKit schema before rendering | | submitProcessor | optional | | Function to transform submission payload before sending to Drupal | | formDataAddons | optional | | Additional FormKit addons | | forceRedirect | optional | default: () => ({ bool: false }) | Force redirect after successful submission | | cmpLibrary | optional | | Additional components available to the schema | | messages | optional | default: () => {} | Override default UI messages | | setUserData | optional | | Function that stores submitted form data in local storage |

Slots

Placeholder

Rendered before the form schema is loaded.

<template #placeholder>Loading...</template>

afterSchema

Rendered immediately after the FormKit schema.

<template #afterSchema>Additional content</template>

Messages

Default UI messages can be overridden.

Example:

export default {
  global: {
    editor: {
      error: 'Check that the form has been completed correctly. Ensure that no unnecessary conditional fields have been filled in.'
    }
  },
  nl: {
    messages: {
      missing: 'Dit formulier ontbreekt. Controleer of het ID dat u gebruikt correct is.',
      error: 'Er is iets misgegaan bij het laden van het formulier.'
    },
    success: {
      title: 'Bedankt!',
      message: 'We hebben je gegevens goed ontvangen.',
    }
  },
  en: {...},
}

Editor-only validation messages Editor-specific validation messages are only visible to users with editor or administrator roles. To enable this behavior in Drupal, expose user roles via drupalSettings.

JsSettingsHooks.php implementation:

<?php

namespace Drupal\minsky\Hook;

use Drupal\Core\Hook\Attribute\Hook;

class JsSettingsHooks {

  #[Hook('js_settings_alter')]
  public function jsSettingsAlter(array &$settings): void {
    // Provide the user information in drupalSettings to allow JavaScript code to customize
    // the experience for the end user, rather than the server side, which would
    // break the render cache.
    $user = \Drupal::currentUser();
    $settings['user']['roles'] = $user->getRoles();
  }
}