@base-ui-components/react/cjs/checkbox/root/useCheckboxRoot.d.ts

Base UI is a library of headless ('unstyled') React components and low-level hooks. You gain complete control over your app's CSS and accessibility features.

import * as React from 'react';
export declare function useCheckboxRoot(params: UseCheckboxRoot.Parameters): UseCheckboxRoot.ReturnValue;
export declare namespace UseCheckboxRoot {
    interface Parameters {
        /**
         * The id of the input element.
         */
        id?: string;
        /**
         * Identifies the field when a form is submitted.
         * @default undefined
         */
        name?: string;
        /**
         * Whether the checkbox is currently ticked.
         *
         * To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
         * @default undefined
         */
        checked?: boolean;
        /**
         * Whether the checkbox is initially ticked.
         *
         * To render a controlled checkbox, use the `checked` prop instead.
         * @default false
         */
        defaultChecked?: boolean;
        /**
         * Whether the component should ignore user interaction.
         * @default false
         */
        disabled?: boolean;
        /**
         * Event handler called when the checkbox is ticked or unticked.
         *
         * @param {boolean} checked The new checked state.
         * @param {Event} event The corresponding event that initiated the change.
         */
        onCheckedChange?: (checked: boolean, event: Event) => void;
        /**
         * Whether the user should be unable to tick or untick the checkbox.
         * @default false
         */
        readOnly?: boolean;
        /**
         * Whether the user must tick the checkbox before submitting a form.
         * @default false
         */
        required?: boolean;
        /**
         * Whether to focus the element on page load.
         * @default false
         */
        autoFocus?: boolean;
        /**
         * Whether the checkbox is in a mixed state: neither ticked, nor unticked.
         * @default false
         */
        indeterminate?: boolean;
        /**
         * A React ref to access the hidden `<input>` element.
         */
        inputRef?: React.Ref<HTMLInputElement>;
        /**
         * Whether the checkbox controls a group of child checkboxes.
         *
         * Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
         * @default false
         */
        parent?: boolean;
        /**
         * The value of the selected checkbox.
         */
        value?: string | number;
    }
    interface ReturnValue {
        /**
         * Whether the checkbox is currently ticked.
         */
        checked: boolean;
        /**
         * Resolver for the input element's props.
         * @param externalProps custom props for the input element
         * @returns props that should be spread on the input element
         */
        getInputProps: (externalProps?: React.ComponentPropsWithRef<'input'>) => React.ComponentPropsWithRef<'input'>;
        /**
         * Resolver for the button element's props.
         * @param externalProps custom props for the button element
         * @returns props that should be spread on the button element
         */
        getButtonProps: (externalProps?: React.ComponentPropsWithRef<'button'>) => React.ComponentPropsWithRef<'button'>;
    }
}