Skip to content
This repository has been archived by the owner. It is now read-only.
Turning web forms into conversations
TypeScript CSS JavaScript
Branch: master
Clone or download
Pull request Compare This branch is 6 commits ahead, 553 commits behind space10-community:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Conversational Form

License: MIT

Turning web forms into conversations. Conversational Form is an open-source concept by SPACE10 to easily turn any form element on a web page into a conversational form interface. It features conversational replacement of all input elements, reusable variables from previous questions and complete customization and control over the styling.

Learn why we did it

Quick demo

Below you will find guides to inlcude the ConversationalForm into a page containing a form or try a quick demo

Getting started

Include ConversationalForm in your page

<script type="text/javascript" src="" crossorigin></script>

ConversationalForm will automatically look through the DOM for a form element with the attibute cf-form, and auto-instantiate.

<form id="my-form-element" cf-form ...>

That's it! Your form is now conversational 👍

Optional attributes

If you want to have the ConversationalForm appended to a certain element (when auto-instantiating) then add attribute cf-context to an element, otherwise the ConversationalForm will be appended to the body element.

<div cf-context ...>

If you don't want to have the UserInput to auto focus.

<form id="my-form-element" cf-form cf-prevent-autofocus>

Add this to

tag to disable animations completly.

<form id="my-form-element" cf-form cf-no-animation>


For more control over the output exclude the attribute cf-form from the form element and instantiate either with vanilla JS or jQuery:

Self-instantiate with vanilla JS

new cf.ConversationalForm(<ConversationalFormOptions> {
	formEl: <HTMLFormElement>,
	// dictionaryData?: {}, // overwrite the default user Dictionary items
	// dictionaryRobot?: {}, // overwrite the default robot Dictionary items
	// context?: // context of where to append the ConversationalForm (see also cf-context attribute)
	// tags?: tags, // pass in custom tags (when prevent the auto-instantiation of ConversationalForm)
	// submitCallback?: () => void | HTMLButtonElement // custom submit callback if button[type=submit] || form.submit() is not wanted..
	// flowStepCallback? (dto: FlowDTO, success: () => void, error: () => void) => boolean // allow for a global validation method, asyncronous, so a value can be validated through a server, call success || error
	// preventAutoStart? boolean // start the form in your own time, {cf-instance}.start(), exclude cf-form from form tag, see examples: manual-start.html
	// preventAutoAppend? boolean // prevent the form from auto appending, this means you have to do it yourself at some point x.appendChild({cf-instance}.el);
	// userImage: "..." //base64 || image url // overwrite user image, without overwritting the user dictionary
	// robotImage: "..." //base64 || image url // overwrite robot image, without overwritting the robot dictionary
	// loadExternalStyleSheet?: boolean // can be set to false to allow for loading and packaging of Conversational Form styles within a larger project.
	// scrollAccerlation?: number // optional horizontal scroll accerlation value

Instantiate with jQuery

$("form").conversationalForm(<ConversationalFormOptions> {

Parameters to pass the constructor of ConversationalForm: <ConversationalFormOptions>

  • formEl: HTMLFormElement | string
  • context?: HTMLElement | string
    • Set the context of where the ConversationalForm will be appended to
    • If not set then ConversationalForm will get appended to document.body
  • tags?: Array
    • [cf.Tag.createTag(element), ...]
  • dictionaryData?: object
  • dictionaryAI?: object
  • submitCallback?: () => void | HTMLButtonElement
    • An alternative way to submit the form. Can be a Function or an HTMLButtonElement (click will be called). If not defined the component will search in the formEl after a button[type=”submit”] and call click() if not button is found final fallback will be to call submit() on formEl.
  • userImage?: string
    • Set a different userImage. "..." //base64 || image url

Map your own tags

The Conversational Form automatically detects the accepted tags in the passed in form element. If this is not desired then you are able to define your own tags, and pass them into the constructor.:

var fields = []"input, select, button"), 0);
for (var i = 0; i < fields.length; i++) {
	var element = fields[i];

Tags can then be set in the instantiation object, see ConversationalFormOptions

DOM Element attributes

input pattern="" attribute

pattern attribute will automatically be used if set in tag.:

<input type="text" pattern="^hello" cf-questions="Your answer needs to include 'hello'" ..


  • to map questions directly to a tag.
  • seperate by | to allow for more questions, app will shuffle.
<input type="text" cf-questions="What is your name?|Please tell me your name." ..


  • tag specific, set the placeholder text on the UserInput field
<input type="text" cf-input-placeholder="Should include http" ..

{One way value-binding} with cf-questions:

For cui-questions, add {previous-answer} to insert the value from the previous user-answer.

<input type="text" cf-questions="Hello {previous-answer}" ..

previous input could be firstname.

<input type="text" cf-questions="So you want to travel to {previous-answer}" ..

previous input could be a select:option list with countries.


  • set a label to the field, [type="radio"|"checkbox"]
<input type="radio" cf-label="Subscribe to newsletter" ..


  • Javascript validate a before submitting
  • OBS. eval is used.
  • Asyncronous, so a value can be validated through a server
  • three parameters is passed to the method
    • dto: FlowDTO
    • success: () => void //callback
    • error: (optionalErrorMessage?: string) => void //callback
<input type="text" cf-validation="window.validateFunction" ..


  • to map error messages directly to a tag.
  • seperate by | to allow for more error, app will shuffle.
<input type="text" cf-error="Text is wrong wrong|Input is not right" ..

Public API

When instantiating ConversationalForm a reference to the instance will be available in window scope.



Sets focus on Conversational Form'



add a robot reponse, this you would usually do at the end of a process.

window.ConversationalForm.addRobotChatResponse("You have reached the end of the form!");

See example of end-message here


add a robot reponse, this you would usually do at the end of a process.

window.ConversationalForm.addUserChatResponse("Hello from user.");

See example of end-message here


remove the ConversationalForm by calling:



get the FormData object of mapped form element, pass in true to get a serialized object back (JSON).

window.ConversationalForm.getFormData(serialized: boolean);


remap registered tags and start flow from {index}


Overwrite styles

You can overwrite the UI with your own styles. Please see the source styles/css files for more info.

Contribute to ConversationalForm

We welcome contributions in the form of bug reports, pull requests, or thoughtful discussions in the GitHub issue tracker.

ConversationalForm is a concept by SPACE10. Brought to life by Felix Nielsen, RWATGG. Designed by Charlie Isslander.

Get the source


$ bower install conversational-form --save

Build the source



$ cd gulp-tasks
$ npm install



Install local gulp from project root

$ npm install gulp

Typescript Typings


$ cd src/scripts
$ typings install

Gulp tasks

main task

watch task, watches .styl, .ts, .jpg, .png, .gif, compiles to /build

# compiles (same as build) and watches files.
$ gulp

sub tasks

# compiles build files, to run locally.
$ gulp build

# compiles distribution files
$ gulp dist

# run docs
$ gulp --docs

# build docs
$ gulp build --docs

install new packages for dev

$ cd gulp-tasks
$ npm install --save-dev XX

Version log

User previous versions. These versions are also available through bower and Github tags


<!-- v0.9.0 -->
<script type="text/javascript" src="" crossorigin></script>

Examples and tests

When you are up and running, you can find a few form tests and examples in the /examples folder.

Browser support

Tested in latest Chrome, Firefox, Safari and Internet Explorer.

Websites that use Conversational Form

If you have a project that uses Conversational Form, feel free to make a PR to add it to this list:

  • ...
You can’t perform that action at this time.