@atlaskit/form
Version:
A form allows people to input information.
107 lines (106 loc) • 4.27 kB
TypeScript
/**
* @jsxRuntime classic
* @jsx jsx
*/
import { type FormEvent, type ReactNode } from 'react';
type SupportedElements = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
export interface FieldProps<FieldValue, Element extends SupportedElements = HTMLInputElement> {
id: string;
isRequired: boolean;
isDisabled: boolean;
isInvalid: boolean;
onChange: (value: FormEvent<Element> | FieldValue) => void;
onBlur: () => void;
onFocus: () => void;
value: FieldValue;
name: string;
'aria-invalid': 'true' | 'false';
'aria-labelledby': string;
'aria-describedby'?: string;
}
export interface Meta {
dirty: boolean;
dirtySinceLastSubmit: boolean;
submitFailed: boolean;
submitting: boolean;
touched: boolean;
valid: boolean;
error?: string;
submitError?: boolean;
validating?: boolean;
}
export type FieldComponentProps<FieldValue, Element extends SupportedElements> = {
/**
* Content to render in the field. This is a function that is called with props for the field component and other information about the field. This cannot be used at the same time as the `component` prop, as the `children` prop will be ignored.
*/
children?: (args: {
fieldProps: FieldProps<FieldValue, Element>;
error?: string;
valid: boolean;
meta: Meta;
}) => ReactNode;
/**
* Content to render in the field. This will be rendered with the `*Message` props. This cannot be used at the same time as the `children` prop, as the `children` prop will be ignored.
*/
component?: (args: {
fieldProps: FieldProps<FieldValue, Element>;
}) => ReactNode;
/**
* Renders a `HelperMessage` with the provided content when using the `component` prop.
*/
helperMessage?: ReactNode;
/**
* Renders an `ErrorMessage` with the provided content when using the `component` prop.
*/
errorMessage?: ReactNode;
/**
* Renders a `ValidMessage` with the provided content when using the `component` prop.
*/
validMessage?: ReactNode;
/**
* Sets the default value of the field. If a function is provided, it is called with the current default value of the field.
*/
defaultValue?: FieldValue | ((currentDefaultValue?: FieldValue) => FieldValue);
/**
* Passed to the ID attribute of the field. This is randomly generated if it is not specified.
*/
id?: string;
/**
* Sets whether the field is required for submission. Required fields are marked with a red asterisk.
*/
isRequired?: boolean;
/**
* Sets whether the field is disabled. Users cannot edit or focus on the fields. If the parent form component is disabled, then the field will always be disabled.
*/
isDisabled?: boolean;
/**
* Label displayed above the form field.
*/
label?: ReactNode;
/**
* Element displayed after the label, and after the red asterisk if field is required.
*/
elementAfterLabel?: ReactNode;
/**
* Specifies the name of the field. This is important for referencing the form data.
*/
name: string;
/**
* Access the current field value and transform it to return a different field value.
*/
transform?: (event: FormEvent<Element> | FieldValue, current: FieldValue) => FieldValue;
/**
* Checks whether the field input is valid. This is usually used to display a message relevant to the current value using `ErrorMessage`, `HelperMessage` or `ValidMessage`.
*/
validate?: (value: FieldValue | undefined, formState: Object, fieldState: Meta) => string | void | Promise<string | void>;
/**
* A `testId` prop is provided for specified elements, which is a unique string that appears as a data attribute `data-testid` in the rendered code, serving as a hook for automated tests
*/
testId?: string;
/**
* The `aria-required` prop is disallowed. It is automatically applied when using `isRequired` via `fieldProps`.
*/
'aria-required'?: never;
};
export default function Field<FieldValue = string, Element extends SupportedElements = HTMLInputElement>(props: FieldComponentProps<FieldValue, Element>): JSX.Element;
export {};