Looking for documentation on gluestack-ui v2 with NativeWind? Refer to this link.
This is an illustration of a Themed FormControl component with default configuration.
size
isDisabled
isInvalid
isReadOnly
isRequired
<Box h="$32" w="$72">
  <FormControl
    size="md"
    isDisabled={false}
    isInvalid={false}
    isReadOnly={false}
    isRequired={false}
  >
    <FormControlLabel mb="$1">
      <FormControlLabelText>Password</FormControlLabelText>
    </FormControlLabel>
    <Input>
      <InputField type="password" defaultValue="12345" placeholder="password" />
    </Input>
    <FormControlHelper>
      <FormControlHelperText>
        Must be at least 6 characters.
      </FormControlHelperText>
    </FormControlHelper>
    <FormControlError>
      <FormControlErrorIcon as={AlertCircleIcon} />
      <FormControlErrorText>
        At least 6 characters are required.
      </FormControlErrorText>
    </FormControlError>
  </FormControl>
</Box>

API Reference

Import

To use this component in your project, include the following import statement in your file.
import { FormControl } from '@gluestack-ui/themed';

Anatomy

The structure provided below can help you identify and understand a FormControl component's various parts.
export default () => (
  <FormControl>
    <FormControlLabel>
      <FormControlLabelText />
    </FormControlLabel>
    <FormControlHelper>
      <FormControlHelperText />
    </FormControlHelper>
    <FormControlError>
      <FormControlErrorIcon />
      <FormControlErrorText />
    </FormControlError>
  </FormControl>
)

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

FormControl

It inherits all the properties of React Native's View component.
Prop
Type
Default
Description
size
'sm' | 'md' | 'lg'
'sm'
Sets the size of the FormControl children.
isInvalid
bool
false
When true, invalid state.
isRequired
bool
false
If true, astrick gets activated.
isDisabled
bool
false
Disabled state true.
isReadOnly
bool
false
To manually set read-only state.
isDisabled
bool
false
To manually set disable to the FormControl.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_labelText
Prop to style FormControlLabelText Component
_helperText
Prop to style FormControlHelperText Component
_errorText
Prop to style FormControlErrorText Component
_labelAstrick
Prop to style FormControlLabelAstrick Component

FormControlLabel

It inherits all the properties of React Native's View component.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_labelText
Prop to style FormControlLabelText Component

FormControlLabelText

It inherits all the properties of React Native's Text component.

FormControlHelper

It inherits all the properties of React Native's View component.

FormControlHelperText

It inherits all the properties of React Native's Text component.

FormControlError

It inherits all the properties of React Native's View component.

FormControlErrorIcon

It inherits all the properties of gluestack Style's AsForwarder component.

FormControlErrorText

It inherits all the properties of React Native's Text component.

Features

  • Keyboard support for actions.
  • Support for hover, focus and active states.
  • Option to add your styles or use the default styles.

Themed

The themed version of the component is a pre-styled version of the component, which allows you to quickly integrate the component into your project. The component's design and functionality are fully defined, allowing you to focus on the more important aspects of your project. To know more about Themed Library please visit this link.

Props

FormControl component is created using View component from react-native. It extends all the props supported by React Native View, utility props and the props mentioned below.

FormControl

Name
Value
Default
size
sm | md | lg
md
Note: These props are exclusively applicable when utilizing the default configuration of gluestack-ui/config. If you are using a custom theme, these props may not be available.

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Form Control with Input

The Input Component can be incorporated within the FormControl.
<FormControl minWidth="$80">
  <FormControlLabel>
    <FormControlLabelText>Name</FormControlLabelText>
  </FormControlLabel>
  <Input>
    <InputField />
  </Input>
  <FormControlHelper>
    <FormControlHelperText>
      What would you like people to call you?
    </FormControlHelperText>
  </FormControlHelper>
</FormControl>

Form Control with Radio

The Radio Component can be incorporated within the FormControl.
<FormControl>
  <FormControlLabel>
    <FormControlLabelText>Favourite fruit</FormControlLabelText>
  </FormControlLabel>
  <RadioGroup my="$2">
    <VStack space="sm">
      <Radio size="sm" value="Mango">
        <RadioIndicator mr="$2">
          <RadioIcon>
            <CircleIcon />
          </RadioIcon>
        </RadioIndicator>
        <RadioLabel>Mango</RadioLabel>
      </Radio>
      <Radio size="sm" value="Apple">
        <RadioIndicator mr="$2">
          <RadioIcon>
            <CircleIcon />
          </RadioIcon>
        </RadioIndicator>
        <RadioLabel>Apple</RadioLabel>
      </Radio>
      <Radio size="sm" value="Orange">
        <RadioIndicator mr="$2">
          <RadioIcon>
            <CircleIcon />
          </RadioIcon>
        </RadioIndicator>
        <RadioLabel>Orange</RadioLabel>
      </Radio>
    </VStack>
  </RadioGroup>
  <FormControlHelper>
    <FormControlHelperText>
      Choose the fruit you like the most
    </FormControlHelperText>
  </FormControlHelper>
</FormControl>

Form Control with Checkbox

The Checkbox Component can be incorporated within the FormControl.
<FormControl>
  <FormControlLabel>
    <FormControlLabelText>Sign up for newsletters</FormControlLabelText>
  </FormControlLabel>
  <CheckboxGroup my="$2">
    <VStack space="sm">
      <Checkbox size="sm" value="Mango">
        <CheckboxIndicator mr="$2">
          <CheckboxIcon>
            <CheckIcon />
          </CheckboxIcon>
        </CheckboxIndicator>
        <CheckboxLabel>Daily Bits</CheckboxLabel>
      </Checkbox>
      <Checkbox size="sm" value="Apple">
        <CheckboxIndicator mr="$2">
          <CheckboxIcon>
            <CheckIcon />
          </CheckboxIcon>
        </CheckboxIndicator>
        <CheckboxLabel>Event Updates</CheckboxLabel>
      </Checkbox>
      <Checkbox size="sm" value="Orange">
        <CheckboxIndicator mr="$2">
          <CheckboxIcon>
            <CheckIcon />
          </CheckboxIcon>
        </CheckboxIndicator>
        <CheckboxLabel>Sponsorship</CheckboxLabel>
      </Checkbox>
    </VStack>
  </CheckboxGroup>
  <FormControlHelper>
    <FormControlHelperText>
      Subscribe to newsletters for updates
    </FormControlHelperText>
  </FormControlHelper>
</FormControl>

Form Control with Textarea

The Textarea Component can be incorporated within the FormControl.
<FormControl>
  <FormControlLabel>
    <FormControlLabelText>Comment</FormControlLabelText>
  </FormControlLabel>
  <Textarea>
    <TextareaInput />
  </Textarea>
  <FormControlHelper>
    <FormControlHelperText>Type your comment above</FormControlHelperText>
  </FormControlHelper>
</FormControl>

Form Control with Inline Form

Inline forms can utilize FormControl for seamless integration and enhanced functionality.
<HStack space="md">
  <FormControl>
    <Input>
      <InputField placeholder="Username" />
    </Input>
  </FormControl>
  <FormControl>
    <Select>
      <SelectTrigger>
        <SelectInput placeholder="Country" />
        <SelectIcon mr="$3">
          <Icon as={ChevronDownIcon} />
        </SelectIcon>
      </SelectTrigger>
      <SelectPortal>
        <SelectBackdrop />
        <SelectContent>
          <SelectDragIndicatorWrapper>
            <SelectDragIndicator />
          </SelectDragIndicatorWrapper>
          <SelectItem label="India" value="India" />
          <SelectItem label="Sri Lanka" value="Sri Lanka" />
          <SelectItem label="Uganda" value="Uganda" />
          <SelectItem label="Japan" value="Japan" />
        </SelectContent>
      </SelectPortal>
    </Select>
  </FormControl>
  <FormControl>
    <Button bg="$darkBlue600">
      <ButtonText fontSize="$sm" fontWeight="$medium">
        Next
      </ButtonText>
    </Button>
  </FormControl>
</HStack>

Form Control with Form in Modal

Modal or other Overlay components can utilize FormControl for state management and error control.
function App() {
  const [showModal, setShowModal] = useState(false)
  return (
    <Center h={500}>
      <Button
        py="$2.5"
        px="$3"
        bg="$darkBlue600"
        onPress={() => {
          setShowModal(true)
        }}
      >
        <ButtonText>Change Settings</ButtonText>
      </Button>
      <Modal
        isOpen={showModal}
        onClose={() => {
          setShowModal(false)
        }}
      >
        <ModalBackdrop />
        <ModalContent maxWidth="$96">
          <ModalBody p="$5">
            <VStack space="xs" mb="$4">
              <Heading>Change Settings</Heading>
              <Text size="sm">
                Make modifications to the settings with ease.
              </Text>
            </VStack>
            <VStack py="$2" space="xl">
              <FormControl>
                <FormControlLabel>
                  <FormControlLabelText>Name</FormControlLabelText>
                </FormControlLabel>
                <Input>
                  <InputField value="Wade Warren" />
                </Input>
              </FormControl>
              <FormControl>
                <FormControlLabel>
                  <FormControlLabelText>Email</FormControlLabelText>
                </FormControlLabel>
                <Input>
                  <InputField value="wadewarren@sample.com" />
                </Input>
              </FormControl>
              <FormControl>
                <FormControlLabel>
                  <FormControlLabelText>Volume</FormControlLabelText>
                </FormControlLabel>
                <Slider defaultValue={60} sliderTrackHeight={4}>
                  <SliderTrack>
                    <SliderFilledTrack />
                  </SliderTrack>
                  <SliderThumb />
                </Slider>
              </FormControl>
              <FormControl>
                <HStack space="sm">
                  <Switch size="sm" />
                  <FormControlLabelText>Dark Mode</FormControlLabelText>
                </HStack>
              </FormControl>
            </VStack>
            <Button
              mt="$4"
              onPress={() => {
                setShowModal(false)
              }}
            >
              <ButtonText>Save Changes</ButtonText>
            </Button>
          </ModalBody>
        </ModalContent>
      </Modal>
    </Center>
  )
}

Form Control with Error

Error messages can be displayed using FormControl.
<FormControl isInvalid>
  <FormControlLabel>
    <FormControlLabelText>
      Which time slot works best for you?
    </FormControlLabelText>
  </FormControlLabel>
  <RadioGroup my="$2">
    <VStack space="sm">
      <Radio size="sm" value="Mango">
        <RadioIndicator mr="$2">
          <RadioIcon>
            <CircleIcon />
          </RadioIcon>
        </RadioIndicator>
        <RadioLabel>Monday</RadioLabel>
      </Radio>
      <Radio size="sm" value="Apple">
        <RadioIndicator mr="$2">
          <RadioIcon>
            <CircleIcon />
          </RadioIcon>
        </RadioIndicator>
        <RadioLabel>Tuesday</RadioLabel>
      </Radio>
      <Radio size="sm" value="Orange">
        <RadioIndicator mr="$2">
          <RadioIcon>
            <CircleIcon />
          </RadioIcon>
        </RadioIndicator>
        <RadioLabel>Wednesday</RadioLabel>
      </Radio>
    </VStack>
  </RadioGroup>
  <FormControlError>
    <FormControlErrorIcon as={AlertCircleIcon} />
    <FormControlErrorText>
      Choose one time slot for the meeting
    </FormControlErrorText>
  </FormControlError>
</FormControl>

Form Control with Form Actions

Form Action Buttons can also be utilized in conjunction with FormControl.
<HStack>
  <FormControl>
    <Button action="negative" mr="$4">
      <ButtonText>Delete</ButtonText>
    </Button>
  </FormControl>
  <FormControl>
    <Button variant="outline" action="secondary">
      <ButtonText>Cancel</ButtonText>
    </Button>
  </FormControl>
</HStack>

Unstyled

All the components in gluestack-ui are unstyled by default. To customize your UI using the extendedTheme, please refer to this link. The import names of components serve as keys to customize each component.

Spec Doc

Explore the comprehensive details of the Input in this document, including its implementation details, checklist, and potential future additions. Dive into the thought process behind the component and gain insights into its development journey.