DocsBlog

  • 0.25.3

  • light

    dark

    system

    Switch mode

  • Cerberus

    Acheron

    Elysium

Get Started
Components
Styling
Theming

Concepts

OverviewCompositionTesting

Layout

Aspect RatioBleedBoxCenterContainerDividerFlexFloatGridLink OverlayScrollableStackWrap

Components

AccordionAdmonitionAvatarButtonCarouselCheckboxClipboardCollapsibleComboboxConfirm ModalCTAModalDate PickerDialogFieldFieldsetFile UploaderIcon ButtonInputLoading StatesMenuNotificationsNumber InputPin InputProgressPrompt ModalRadioRatingSelectSplit ButtonSwitchTableTabsTagTextTextareaToggleTooltip

Utilities

Client OnlyDownload TriggerEnvironmentFeature FlagsFocus TrapForFormat ByteFormat NumberFormat Relative TimeFrameHighlightJSON Tree ViewLocaleLocal StoragePortalPresenceShowsplitPropsTheme

Field

The Field component is used to manage form fields, providing a consistent way to display labels, helper texts, and error messages.

  • npm
  • source
  • recipe
  • Ark
import {
  Field,
  FieldParts,
} from '@cerberus/react'

Usage

The Field component helps manage the state of form fields and ensures consistent display of labels, helper texts, and error messages.

We'll never share your email with anyone else.
A name is required to submit this form. It replaces the helper text.
This will help us learn more about you.0/300
Copy
some-form.tsx
import { Field, Input, Textarea } from '@cerberus/react'
import { Box, VStack } from 'styled-system/jsx'


export function BasicFieldPreview() {
  return (
    <form action={someAction} method="post">
      <Box w="1/2">
        <VStack alignItems="flex-start" gap="lg" w="full">
          <Field
            ids={{
              control: 'email',
            }}
            label="Enter your email"
            helperText="We'll never share your email with anyone else."
            required
          >
            <Input name="email" type="email" />
          </Field>
          <Field
            ids={{
              control: 'invalid-name',
            }}
            label="Invalid example"
            helperText="This is an example of an invalid field."
            errorText="A name is required to submit this form. It replaces the helper text."
            invalid
            required
          >
            <Input name="invalid-name" type="text" />
          </Field>
          <Field
            ids={{
              control: 'message',
            }}
            label="Anything else you want to tell us?"
            helperText="This will help us learn more about you."
            secondaryHelperText="0/300"
          >
            <Textarea name="message" />
          </Field>
        </VStack>
      </Box>
    </form>
  )
}

Hidden Labels

For accessibility compliance, use the hideLabel prop to visually hide labels while keeping them accessible to screen readers. This is useful for search inputs and other cases where the visual label would be redundant.

Label is hidden but accessible to screen readers
Copy
hidden-label-fields.tsx
import { Field, Input } from '@cerberus/react'
import { Box, VStack } from 'styled-system/jsx'


export function HiddenLabelFields() {
  return (
    <Box w="1/2">
      <VStack alignItems="flex-start" gap="lg" w="full">
        <Field
          label="Search something"
          helperText="Label is hidden but accessible to screen readers"
          hideLabel
        >
          <Input name="search" type="search" placeholder="Type to search..." />
        </Field>
        <Field
          label="Global search"
          hideLabel
          required
        >
          <Input name="global-search" type="search" placeholder="Search the entire site..." />
        </Field>
      </VStack>
    </Box>
  )
}

Primitives

You can utilize the primitive components or the css prop to customize the field.

ComponentDescription
FieldRootThe context provider for the Field parts
FieldLabelThe label of the field
FieldInputThe input of the field
FieldTextareaThe textarea of the field
FieldHelperTextThe helper text of the field
FieldErrorTextThe error text of the field
StartIndicatorThe start indicator of the field
StatusIndicatorThe status indicator or end icon of the field
RequiredIndicatorThe required indicator of the field
Custom Helper Text
Copy
import { FieldParts } from '@cerberus/react'
import { Box } from 'styled-system/jsx'


export function CustomField() {
  return (
    <Box w="1/2">
      <FieldParts.Root ids={{ control: 'customField' }}>
        <FieldParts.Label
          css={{
            fontSize: 'xl',
            fontWeight: 'black',
            textTransform: 'uppercase',
          }}
        >
          Custom Label
        </FieldParts.Label>
        <FieldParts.Input
          css={{
            transform: 'skewX(-10deg)',
          }}
          type="text"
        />
        <FieldParts.HelperText
          css={{
            fontStyle: 'italic',
          }}
        >
          Custom Helper Text
        </FieldParts.HelperText>
      </FieldParts.Root>
    </Box>
  )
}

API

Props

The Field component is an abstraction of the primitives and accepts the following props:

NameDefaultDescription
labelThe label to show above the field input.
helperTextThe helper text to show below the field input.
secondaryHelperTextThe secondary helper text to show below the field input at the end of the row.
errorTextThe error text to show below the field input. It replaces the helperText when visible.
hideLabelfalseWhether to hide the label visually while keeping it accessible to screen readers.

The Field component also accepts all the props of the FieldRoot primitive props

Parts

The FieldParts API is an Object containing the full family of components.

Note

It is best to only use the FieldParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

NameDescription
RootThe FieldRoot component which is the Provider for the family.
LabelThe FieldLabel component which displays the label and "required" notice.
InputThe FieldInput component which is the input field.
TextareaThe FieldTextarea component which is the textarea field.
HelperTextThe FieldHelperText component which displays the helper text.
ErrorTextThe FieldErrorText component which displays the error text.
StartIndicatorThe StartIndicator component which displays an indicator of your choice at the start of the field.
StatusIndicatorThe StatusIndicator component which displays an indicator of your choice at the end of the field.
RequiredIndicatorThe RequiredIndicator component which displays an indicator of your choice when the field is marked required.

On this page

  • Edit this page on Github
Cerberus Design System | Docs