@bento/control

Control

The @bento/control package provides foundational building blocks for form controls such as radios and checkboxes. It delivers a consistent DOM structure and shared behaviors, making it easy to create custom form controls. The package exports the ControlGroup and Control primitives.

The ControlGroup is a container for a group of controls. It is used to group controls with a shared label and description. It also provides a standardized way to display error messages.

The Control consists of a label and an visually hidden input element. The label is used to describe the control and the input element is used to capture user input.

This package is intended primarily for internal use as a foundation for building other Bento primitives, rather than for direct use outside the Bento ecosystem.

Installation

npm install --save @bento/control

Props

The @bento/control package exports the ControlGroup and Control primitives:

import { ControlGroup, Control } from '@bento/control';

<ControlGroup label="Control label">
  <Control inputRef={inputRef} inputProps={inputProps} labelProps={labelProps} label="Control 1" />
  <Control inputRef={inputRef} inputProps={inputProps} labelProps={labelProps} label="Control 2" />
</ControlGroup>;

The following properties are available to be used on the Control and ControlGroup primitives:

ControlGroup

Prop	Type	Required	Description
children	ReactNode	Yes	The control elements to render within the group.
label	ReactNode	No	The label for the control group.
labelProps	DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>	No	Props to pass to the label element.
description	ReactNode	No	Additional description text for the control group.
descriptionProps	DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>	No	Props to pass to the description element.
errorMessage	ReactNode	No	Error message to display below the controls.
errorMessageProps	DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>	No	Props to pass to the error message element.
contentProps	DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>	No	The props passed to the content element.
slot	string	No	A named part of a component that can be customized. This is implemented by the consuming component.
The exposed slot names of a component are available in the components documentation.
slots	Record<string, object | Function>	No	An object that contains the customizations for the slots.
The main way you interact with the slot system as a consumer.

Control

Prop	Type	Required	Description
inputRef	Ref<HTMLInputElement>	No	A ref for the HTML input element.
inputProps	DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>	No	Props to pass to the underlying input element.
label	ReactNode	No	The label for the control.
labelProps	DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>	No	Props to pass to the label element.
children	ReactNode	No	Additional content for the control.
slot	string	No	A named part of a component that can be customized. This is implemented by the consuming component.
The exposed slot names of a component are available in the components documentation.
slots	Record<string, object | Function>	No	An object that contains the customizations for the slots.
The main way you interact with the slot system as a consumer.

Slot Map and Props

The slot map and props can be used to style and customize the Control and ControlGroup primitives.

Control Slot Map

Slot Name	Description
label	Label for the control

ControlGroup Slot Map

Slot Name	Description
label	Label for controlgroup
description	Description for controlgroup
error	Error message for controlgroup

Examples

Default

A simple usage of the ControlGroup primitive.

import { Control, ControlGroup } from '@bento/control';
/* v8 ignore next */
import React, { type ComponentProps } from 'react';

export function DefaultExample(props: {
  groupProps?: Partial<ComponentProps<typeof ControlGroup>>;
  controlProps?: Partial<ComponentProps<typeof Control>>;
}) {
  return (
    <ControlGroup
      label="Control label"
      description="Control description"
      errorMessage="Control error message"
      className="random-class-group"
      {...props.groupProps}
    >
      <Control label="Control 1" className="random-class-control" {...props.controlProps} />
      <Control label="Control 2" {...props.controlProps} />
    </ControlGroup>
  );
}

Input Ref

Passing a ref to the Control primitive allows you to access the underlying input element.

import { Control, ControlGroup } from '@bento/control';
/* v8 ignore next */
import React, { useRef } from 'react';

export function InputRefExample() {
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <ControlGroup label="Control label">
      <Control
        inputRef={inputRef}
        inputProps={{ id: 'dateId', type: 'date' }}
        labelProps={{ htmlFor: 'dateId' }}
        label="Control 1"
      />
      <Control
        inputRef={inputRef}
        inputProps={{ id: 'radioId', type: 'radio' }}
        labelProps={{ htmlFor: 'radioId' }}
        label="Control 2"
      />
    </ControlGroup>
  );
}