LynxFormX

LynxFormX is a lightweight and intuitive form library built for the Lynx framework for mobile development. It streamlines form management by automatically binding fields, handling validation, and providing easy-to-use hooks for custom field manipulation—all with strong TypeScript support.

---

Features

• Declarative API:
  Define forms with <Form>, bind inputs with <Field>, show errors with <Error>, and submit with <SubmitButton>.

• Validation Options:

  • Zod Schema: Use a Zod schema for validation by providing the schema prop (only accepts Zod).
  • Custom Validation: Alternatively, pass a validation function that returns an object with field names as keys and error messages as values.

• Flexible Submission:
  The onSubmit function receives form values as the first parameter, and a helpers object with setValue and setError functions as the second parameter, enabling you to update values and set errors for any field.

• Type-Safe Forms:
  Form structure is inferred from initialValues (optional) or provided via generics (e.g., <Form<FormValues>>). Unlike Formik, you do not need to supply initialValues to define the form structure—the structure is formed by the <Field> components.

• Custom Field Manipulation:
  For more advanced use cases, use the useField hook to access a field's value, error, touched status, and helper functions setValue and setError for granular control.

• Smart Submit Button:
  <SubmitButton> optionally accepts disableOnSubmit and disabledClassName props. It automatically performs validation and triggers onSubmit upon successful validation.

• Standard Attribute Forwarding:
  All components pass standard attributes to their underlying tags:

  • Form forwards props to <view>
  • SubmitButton forwards props to <view>
  • Error forwards props to <text>
  • Field forwards props to <input>

---

Installation

Install LynxFormX via npm:

1npm install lynx-form-x

---

Usage

Basic Form Example

Below is a basic example using a Zod schema for validation:

1import { z } from 'zod';
2import { Form, Field, Error, SubmitButton } from 'lynx-form-x';
3
4interface FormValues {
5  login: string;
6  password: string;
7}
8
9const schema = z.object({
10  login: z.string().nonempty('Enter login'),
11  password: z.string().nonempty('Enter password'),
12}));
13
14export function App() {
15  return (
16    <Form<FormValues>
17      schema={schema}
18      onSubmit={async (values, { setValue, setError }) => {
19        console.log(values);
20        // Perform submission logic here
21        await new Promise((resolve) => setTimeout(resolve, 1000));
22      }}
23    >
24      <Field name="login" />
25      <Error name="login" />
26      <Field name="password" />
27      <Error name="password" />
28      <SubmitButton
29        className="button"
30        disableOnSubmit
31        disabledClassName="disabled"
32      >
33        Submit
34      </SubmitButton>
35    </Form>
36  );
37}

Using Custom Validation Function

If you prefer a custom validation function, simply pass it as the validation prop:

1import {Form, Field, Error, SubmitButton, Errors} from 'lynx-form-x'
2
3interface FormValues {
4  email: string
5  username: string
6}
7
8const customValidation = (values: FormValues) => {
9  const errors: Errors<FormValues> = {}
10  if (!values.email.includes('@')) {
11    errors.email = 'Invalid email address'
12  }
13  if (values.username.length < 3) {
14    errors.username = 'Username must be at least 3 characters'
15  }
16  return errors
17}
18
19export function App() {
20  return (
21    <Form<FormValues>
22      validation={customValidation}
23      onSubmit={(values, {setValue, setError}) => {
24        console.log(values)
25      }}
26    >
27      <Field name='email' />
28      <Error name='email' />
29      <Field name='username' />
30      <Error name='username' />
31      <SubmitButton
32        className='button'
33        disableOnSubmit
34        disabledClassName='disabled'
35      >
36        Submit
37      </SubmitButton>
38    </Form>
39  )
40}

Advanced Usage with useField

For more granular control over individual fields, use the useField hook:

1import {useField} from 'lynx-form-x'
2
3interface FormValues {
4  firstName: string
5  lastName: string
6}
7
8export function CustomInput({name}: {name: keyof FormValues}) {
9  const {value, error, touched, setValue, setError} = useField(name)
10
11  // some custom logic
12
13  return (
14    <view>
15      <Field name={name} />
16      {error && touched && <text>{error}</text>}
17      /* some custom layout */
18    </view>
19  )
20}
21
22export function App() {
23  return (
24    <Form<FormValues>
25      onSubmit={(values) => {
26        console.log(values)
27      }}
28    >
29      <CustomInput name='firstName' />
30      <CustomInput name='lastName' />
31      <SubmitButton>Submit</SubmitButton>
32    </Form>
33  )
34}

---

API Reference

<Form>

• Props:
  • initialValues?: (optional) Object with initial form values.
  • schema?: (optional) A Zod schema used for validation.
  • validation?: (optional) A custom validation function. Should return an object where keys are field names and values are error messages.
  • onSubmit: Function called on form submission. Receives two arguments:
    1. values: The current form values.
    2. helpers: An object containing setValue and setError functions to update any field.

<Field>

• Props:
  • name: The field name. The library binds the input to this name in the form state.

<Error>

• Props:
  • name: The field name to display an error for.

<SubmitButton>

• Props:
  • disableOnSubmit?: (optional) If true, disables the button during form submission.
  • disabledClassName?: (optional) CSS class applied when the button is disabled.
• Behavior:
  • Automatically validates the form and triggers onSubmit upon successful validation.

useField Hook

• Usage:
  • Accepts a field name.
  • Returns an object with:
    • value: Current field value.
    • error: Current field error.
    • touched: Whether the field has been touched.
    • setValue: Function to update the field value.
    • setError: Function to update the field error.

---

Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check issues page.

---

License

MIT

---

Enjoy building forms with LynxFormX!
If you have any questions or feedback, please open an issue or contact the maintainer.

---

This README is a starting point—feel free to customize and enhance the examples and documentation to better fit your project needs!