Need help with elliptical?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

197 Stars 20 Forks Apache License 2.0 609 Commits 2 Opened issues


Interactive natural language parsing library in Javascript

Services available


Need anything else?

Contributors list

# 77,113
587 commits
# 129,221
Amazon ...
1 commit
# 26,703
1 commit
# 229,466
1 commit
# 712,297
1 commit
# 743,625
1 commit


Build Status Join Gitter Chat js-standard-style npm

Elliptical is a Javascript library for building interactive natural language text interfaces.

It is framework-independent and runs on both the client and the server. It works with any written language that can be represented with Unicode. It is functional, compositional, easily extensible, and it's got great docs.

There are addons to allow for internationalization, linguistic extension, sideways data loading, and more.

There are pre-built phrases for parsing English dates and times, numbers, urls, phone numbers, email addresses, arbitrary strings, and more. Of course, you can develop your own phrases.

To see an example of Elliptical in action, check out the Lacona App.

Full Documentation


npm install elliptical

What is an Interactive Natural Language Interface?

Interactive Natural Language Interfaces allow users to enter data in a natural, unstructured way, but still have interactive nicities like intelligent suggestions, sorting, autocomplete, and syntax highlighting.

Well-designed interfaces can give users an unprecedented level of expressiveness and efficiency, while still being easy to learn and use.

Elliptical helps you build interfaces like this. You create natural language grammars by combining linguistic building blocks (called

). Elliptical uses that grammar to process strings, and returns objects that describe the input, offer suggestions, and allow for intelligent sorting.

Elliptical also uses the user input to build plain Javascript objects, so you can easily do things based upon the user's input.

Lacona is extensible, allowing phrases to have smart internationalization functionality, make use of external data sources, and more. This allows for powerful, dynamic grammars that are still easy to understand.

Elliptical is not:

  • a library to extract meaningful information from unstructured text, like
    . Elliptical does not know anything about English (or any other language's) grammar. Rather, it parses possible strings according to a predefined schema.
  • a voice command system, like Siri. Elliptical only operates on text (though it could conceivably be used as a layer in such an application).
  • a machine learning system. Elliptical parses strings according to a preset algorithm
  • a static string parser, like regular expressions. Elliptical schemata are dynamic - can execute arbitrary code, pull data from external sources, and interact with one another. Abstractions are provided to make these complex tasks as reasonable as possible.
  • designed for automated parsing. Elliptical is designed to build interactive textural interfaces for relatively short inputs.


You can play with this example yourself at elliptical-example.

/** @jsx createElement */
import {createElement, compile} from 'elliptical'

// Some data to work with const countryData = [ {text: "China (People's Republic of)", value: 'CN'}, {text: 'Ireland', value: 'IE'}, {text: 'Macedonia (the former Yugoslav Republic of)', value: 'MK'}, {text: 'United Kingdom of Great Britain and Northern Ireland', value: 'IE'}, {text: 'United States', value: 'US'} ]

// Define a Phrase const Country = { describe () { return ( ) } }

// Build our grammar out of Elements const grammar = ( )

// Obtain a parse function from our grammar const parse = compile(grammar)

// Parse based upon a given query const outputs = parse('flights to irela') console.log(outputs)

/* [{ // direct match words: [ {text: 'flights', input: true}, {text: ' to ', input: true}, {text: 'Irela', input: true, argument: 'Country'}, {text: 'nd', input: false, argument: 'Country'} ]}, results: { direction: 'to', country: 'IE' }, score: 1 }, { // mid-string match words: [ {text: 'flights', input: true}, {text: ' to ', input: true}, {text: 'United Kingdom of Great Britain and Northern ', input: false, argument: 'Country'}, {text: 'Ireland', input: true, argument: 'Country'} ]}, results: { direction: 'to', country: 'GB' }, score: 0.5673076923076923 }, { // fuzzy match words: [ {text: 'flights', input: true}, {text: ' to ', input: true}, {text: 'Macedon', input: false, argument: 'Country'}, {text: 'i', input: true, argument: 'Country'}, {text: 'a (the fo', input: false, argument: 'Country'}, {text: 'r', input: true, argument: 'Country'}, {text: 'm', input: false, argument: 'Country'}, {text: 'e', input: true, argument: 'Country'}, {text: 'r Yugos', input: false, argument: 'Country'}, {text: 'la', input: true, argument: 'Country'}, {text: 'v Republic of)', input: false, argument: 'Country'} ]}, results: { direction: 'to', country: 'MK' }, score: 0.024999999999999998 }] */

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.