Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukasbach/ink-form
Complex user-friendly form component for React Ink
https://github.com/lukasbach/ink-form
cli cmd commandline component forms ink input react reusable ui
Last synced: 3 months ago
JSON representation
Complex user-friendly form component for React Ink
- Host: GitHub
- URL: https://github.com/lukasbach/ink-form
- Owner: lukasbach
- Created: 2021-03-05T21:52:19.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-05-18T14:06:23.000Z (9 months ago)
- Last Synced: 2024-11-05T18:16:43.716Z (3 months ago)
- Topics: cli, cmd, commandline, component, forms, ink, input, react, reusable, ui
- Language: TypeScript
- Homepage: https://lukasbach.github.io/ink-form/
- Size: 15.3 MB
- Stars: 35
- Watchers: 3
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# ink-form
`ink-form` is a Node library for displaying a user-friendly form in a terminal window.
It can be used in two ways, either by using the React Ink component `Form` exported by
the package, or by using the imperative API `openForm(options)`.
## Example usage
npm install ink-form react ink
```typescript jsx
const options = [
{ label: 'Opt 1', value: 'a' },
{ label: 'Opt 2', value: 'b' },
];
const form: FormProps = {
form: {
title: 'Form title',
sections: [
{
title: 'Text and Number fields',
fields: [
{ type: 'string', name: 'field1', label: 'Input with initial value', initialValue: 'Initial value' },
{ type: 'string', name: 'field2', label: 'Masked input', mask: '*' },
{ type: 'integer', name: 'field3', label: 'Integer between -5 and 8, stepsize 2', min: -5, max: 8, step: 2 },
{ type: 'float', name: 'field4', label: 'Float between 0 and 5, stepsize 0.1', min: 0, max: 5, step: 0.1 },
],
},
{
title: 'Select and boolean fields',
fields: [
{ type: 'select', name: 'field5', label: 'Select', options },
{ type: 'multiselect', name: 'field6', label: 'Multi Select', options },
{ type: 'boolean', name: 'field7', label: 'Boolean select', options },
],
},
],
},
};
// either:
(async () => {
const result = await openForm(form);
console.log(`Finished with value`, result);
})();
// or:
render(
{
console.log(`Finished with value`, result);
}}
/>
);
```
If you want to see how using `ink-form` feels, you can clone this repo, run `yarn` to install
dependencies and then run one of the demo scripts:
- `yarn demo:overview` ([See Code](https://github.com/lukasbach/ink-form/blob/main/src/demo/overview.tsx))
- `yarn demo:packagejson` ([See Code](https://github.com/lukasbach/ink-form/blob/main/src/demo/packagejson.tsx))
- `yarn demo:custommanager` ([See Code](https://github.com/lukasbach/ink-form/blob/main/src/demo/custommanager.tsx))
- `yarn demo:imperative` ([See Code](https://github.com/lukasbach/ink-form/blob/main/src/demo/imperative.ts))
## Update Note
This package is now pure ESM as of 2.0.0. (Details: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)
With that upgrade, I had to remove the multi select component as its dependency does not support ESM. Please
use the v1x version branch with CJS if you need that.
## Documentation
Detailed documentation is available at [lukasbach.github.io/ink-form](https://lukasbach.github.io/ink-form/).
Install the package with `npm install ink-form --save` or `yarn add ink-form` to your project.
Then, render the form by invoking the [imperative interface](https://lukasbach.github.io/ink-form/modules.html#openform)
or by rendering the [React Ink component](https://lukasbach.github.io/ink-form/modules.html#form).
Both take [`FormProps`](https://lukasbach.github.io/ink-form/interfaces/formprops.html) as parameters.
The most important property is the `form`-property, which dictates how the form fields are structured. It follows
the [`FormStructure`](https://lukasbach.github.io/ink-form/interfaces/formstructure.html)-interface. Look into the
example above to see an example.
## Custom fields
A form field describes a type of input, i.e. text input, number input etc.
Included are:
- FormFieldString
- FormFieldInteger
- FormFieldFloat
- FormFieldSelect
- FormFieldMultiSelect
- FormFieldBoolean
You can add your own form field by extending
[`AbstractFormField`](https://lukasbach.github.io/ink-form/modules.html#abstractformfield)
and implementing an associated
[`FormFieldManager`](https://lukasbach.github.io/ink-form/interfaces/formfieldmanager.html).
