Skip to main content

Form

The Form component is a context-based container that handles form submission, validation, and component registration within the form. It provides centralized state management and validation for all form fields.

Import​

Phaselis exports Form as the main component for form management.

import { Form , FormReference } from "phaselis";

  • Form: Main component to handle form data, validation, and submission.

  • FormReference: interface for form reference.

Usage​

Basic Form​

import { Form, FormReference, Textfield, InputGroup, Button } from "phaselis";
import { useRef } from "react";

const Example = () => {
  const refForm = useRef<FormReference>(null);

  return (
    <Form ref={refForm}>
      <InputGroup label="User Name">
        <Textfield name="username" rightIcon="User" />
      </InputGroup>
      <Button text="Submit" />
      <Button text="Reset" type="reset" />
    </Form>
  );
};

export default Example;

Props​

children required​

ReactNode

The form fields and components within the form, which are registered and managed by the form context.

<Form>
  <Textfield name="username" placeholder="Username" />
  <Textfield name="password" placeholder="Password" type="password" />
</Form>

id​

string

An optional unique identifier for the form, useful for debugging or tracking form instances.

import { Textfield } from "phaselis";
<Form id="loginForm">
  <Textfield />
</Form>

onSubmit​

(event?: any, values?: any) => void

Callback triggered when the form is successfully submitted. Receives the event and all form values.

import { Textfield, Button } from "phaselis";
<Form
  onSubmit={(e, values) =>
    console.log("Form submitted with values:", values)
  }
>
  <Textfield />
  <Button type="submit">Submit</Button>
</Form>

onReset​

(event?: any) => void

Callback triggered when the form is reset, clearing all values and errors. Receives an optional event.

import { Textfield, Button } from "phaselis";
<Form onReset={() => console.log("Form reset")}>
  <Textfield />
  <Button type="reset">Reset</Button>
</Form>

onError​

(error?: any, extra?: any) => void

Callback triggered when validation errors are found during submission. Receives the error message and fields with errors.

import { Textfield, InputGroup, Button, required } from "phaselis";
<Form onError={(error, fields) => console.log("Form errors:", fields)}>
  <InputGroup label="User Name">
    <Textfield
      name="username"
      rightIcon="User"
      validations={[required("required")]}
    />
  </InputGroup>
  <Button type="submit">Submit</Button>
</Form>

onChange​

(event?: any, state?: any) => void

Callback triggered whenever a form field value changes. Receives the event and the updated form state.

import { Textfield, InputGroup } from "phaselis";
<Form onChange={(e, state) => console.log("Form changed:", state)}>
  <InputGroup label="User Name">
    <Textfield name="username" rightIcon="User" />
  </InputGroup>
</Form>

Methods​

The functions below are available through the FormReference interface, which can be accessed using the useRef hook.

setValues​

Sets multiple form field values programmatically.

formRef.current?.setValues({ username: "testUser", email: "user@example.com" });

getValues​

Returns the current values of all form fields.

const values = formRef.current?.getValues();

validate​

Validates a specific form field by its name, returning true if it passes validation.

const isValid = formRef.current?.validate("username");

validateAll​

Validates all fields within the form. Returns true if all fields are valid.

const allValid = formRef.current?.validateAll();

getErrorField​

Retrieves an array of field names that have validation errors.

const errors = formRef.current?.getErrorField();

showError​

Displays a validation error message for a specific field.

formRef.current?.showError("username", "Username is required");

hideError​

Clears the error message for a specific field.

formRef.current?.hideError("username");

hideErrors​

Clears all validation error messages across all fields.

formRef.current?.hideErrors();