@ariakit/react-core 0.3.12 → 0.3.13

package/cjs/menu/menu-button-arrow.d.cts

@@ -20,12 +20,17 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuButtonArrow: import("../utils/types.js").Hook<MenuButtonArrowOptions<"span">>;
 /**
- * Renders an arrow pointing to the menu position, usually inside a
- * `MenuButton`.
+ * Displays an arrow within a
+ * [`MenuButton`](https://ariakit.org/reference/menu-button), pointing to the
+ * [`Menu`](https://ariakit.org/reference/menu) position. It's typically based
+ * on the [`placement`](https://ariakit.org/reference/menu-provider#placement)
+ * state from the menu store, but this can be overridden with the
+ * [`placement`](https://ariakit.org/reference/menu-button-arrow#placement)
+ * prop.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
- * <MenuProvider>
+ * ```jsx {4}
+ * <MenuProvider placement="bottom-start">
  *   <MenuButton>
  *     Edit
  *     <MenuButtonArrow />

package/cjs/menu/menu-button-arrow.d.ts

@@ -20,12 +20,17 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuButtonArrow: import("../utils/types.js").Hook<MenuButtonArrowOptions<"span">>;
 /**
- * Renders an arrow pointing to the menu position, usually inside a
- * `MenuButton`.
+ * Displays an arrow within a
+ * [`MenuButton`](https://ariakit.org/reference/menu-button), pointing to the
+ * [`Menu`](https://ariakit.org/reference/menu) position. It's typically based
+ * on the [`placement`](https://ariakit.org/reference/menu-provider#placement)
+ * state from the menu store, but this can be overridden with the
+ * [`placement`](https://ariakit.org/reference/menu-button-arrow#placement)
+ * prop.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
- * <MenuProvider>
+ * ```jsx {4}
+ * <MenuProvider placement="bottom-start">
  *   <MenuButton>
  *     Edit
  *     <MenuButtonArrow />

package/cjs/menu/menu-button.cjs

@@ -6,18 +6,18 @@ var _NGEKJJDHcjs = require('../__chunks/NGEKJJDH.cjs');
 require('../__chunks/7LBZXSLY.cjs');
 
 
-var _LICANQTIcjs = require('../__chunks/LICANQTI.cjs');
-require('../__chunks/QCG6J6X5.cjs');
-require('../__chunks/LFHNPG2L.cjs');
+var _25ZFPUHHcjs = require('../__chunks/25ZFPUHH.cjs');
+require('../__chunks/NLVGDNPE.cjs');
+require('../__chunks/2FTVUUOK.cjs');
 require('../__chunks/3QW6ELTG.cjs');
-require('../__chunks/5UTRYT6E.cjs');
+require('../__chunks/REJALU3P.cjs');
 
 
 var _6PUZ4NWRcjs = require('../__chunks/6PUZ4NWR.cjs');
-require('../__chunks/DAJUUBUI.cjs');
+require('../__chunks/OSTQZD2E.cjs');
 
 
-var _TGTVGYEZcjs = require('../__chunks/TGTVGYEZ.cjs');
+var _4KFTI2WWcjs = require('../__chunks/4KFTI2WW.cjs');
 require('../__chunks/6ZZYUFPW.cjs');
 require('../__chunks/UZNYSPKP.cjs');
 require('../__chunks/BZTDJIVT.cjs');
@@ -28,7 +28,7 @@ require('../__chunks/3W6FH6JK.cjs');
 require('../__chunks/UVBBMANL.cjs');
 require('../__chunks/F2A2ZQDB.cjs');
 require('../__chunks/S6UU7NA4.cjs');
-require('../__chunks/Z3GCTNW4.cjs');
+require('../__chunks/VUEWHLYH.cjs');
 require('../__chunks/75KXQZJX.cjs');
 
 
@@ -179,7 +179,7 @@ var useMenuButton = _RNZNGEL4cjs.createHook.call(void 0,
       onKeyDown,
       onClick
     });
-    props = _TGTVGYEZcjs.useHovercardAnchor.call(void 0, _AV6KTKLEcjs.__spreadProps.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
+    props = _4KFTI2WWcjs.useHovercardAnchor.call(void 0, _AV6KTKLEcjs.__spreadProps.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
       store,
       focusable,
       accessibleWhenDisabled
@@ -207,7 +207,7 @@ var useMenuButton = _RNZNGEL4cjs.createHook.call(void 0,
         return true;
       }
     }));
-    props = _LICANQTIcjs.usePopoverDisclosure.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
+    props = _25ZFPUHHcjs.usePopoverDisclosure.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
       store,
       toggleOnClick: !hasParentMenu,
       focusable,

package/cjs/menu/menu-button.d.cts

@@ -19,13 +19,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuButton: import("../utils/types.js").Hook<MenuButtonOptions<"button" | "div">>;
 /**
- * Renders a menu button that triggers a
- * [`Menu`](https://ariakit.org/reference/menu) component. Usually, this is
- * rendered as a native `button` element, but if it's a submenu button rendered
- * as a menu item inside another menu, it'll be rendered as a `div`.
+ * Renders a menu button that toggles the visibility of a
+ * [`Menu`](https://ariakit.org/reference/menu) component when clicked or when
+ * using arrow keys.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {2}
  * <MenuProvider>
  *   <MenuButton>Edit</MenuButton>
  *   <Menu>
@@ -49,8 +48,10 @@ export interface MenuButtonOptions<T extends As = "button" | "div"> extends Hove
      * Determines whether pressing a character key while focusing on the
      * [`MenuButton`](https://ariakit.org/reference/menu-button) should move focus
      * to the [`MenuItem`](https://ariakit.org/reference/menu-item) starting with
-     * that character. By default, it's `true` for menu buttons in a
-     * [Menubar](https://ariakit.org/components/menubar), but `false` for other
+     * that character.
+     *
+     * By default, it's `true` for menu buttons in a
+     * [`Menubar`](https://ariakit.org/reference/menubar), but `false` for other
      * menu buttons.
      */
     typeahead?: boolean;

package/cjs/menu/menu-button.d.ts

@@ -19,13 +19,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuButton: import("../utils/types.js").Hook<MenuButtonOptions<"button" | "div">>;
 /**
- * Renders a menu button that triggers a
- * [`Menu`](https://ariakit.org/reference/menu) component. Usually, this is
- * rendered as a native `button` element, but if it's a submenu button rendered
- * as a menu item inside another menu, it'll be rendered as a `div`.
+ * Renders a menu button that toggles the visibility of a
+ * [`Menu`](https://ariakit.org/reference/menu) component when clicked or when
+ * using arrow keys.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {2}
  * <MenuProvider>
  *   <MenuButton>Edit</MenuButton>
  *   <Menu>
@@ -49,8 +48,10 @@ export interface MenuButtonOptions<T extends As = "button" | "div"> extends Hove
      * Determines whether pressing a character key while focusing on the
      * [`MenuButton`](https://ariakit.org/reference/menu-button) should move focus
      * to the [`MenuItem`](https://ariakit.org/reference/menu-item) starting with
-     * that character. By default, it's `true` for menu buttons in a
-     * [Menubar](https://ariakit.org/components/menubar), but `false` for other
+     * that character.
+     *
+     * By default, it's `true` for menu buttons in a
+     * [`Menubar`](https://ariakit.org/reference/menubar), but `false` for other
      * menu buttons.
      */
     typeahead?: boolean;

package/cjs/menu/menu-description.d.cts

@@ -15,12 +15,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuDescription: import("../utils/types.js").Hook<MenuDescriptionOptions<"p">>;
 /**
- * Renders a description in a menu. This component must be wrapped with
+ * Renders a description in a menu. This component must be wrapped with a
  * [`Menu`](https://ariakit.org/reference/menu) component so the
  * `aria-describedby` prop is properly set on the menu element.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3}
  * <MenuProvider>
  *   <Menu>
  *     <MenuDescription>Description</MenuDescription>

package/cjs/menu/menu-description.d.ts

@@ -15,12 +15,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuDescription: import("../utils/types.js").Hook<MenuDescriptionOptions<"p">>;
 /**
- * Renders a description in a menu. This component must be wrapped with
+ * Renders a description in a menu. This component must be wrapped with a
  * [`Menu`](https://ariakit.org/reference/menu) component so the
  * `aria-describedby` prop is properly set on the menu element.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3}
  * <MenuProvider>
  *   <Menu>
  *     <MenuDescription>Description</MenuDescription>

package/cjs/menu/menu-dismiss.cjs

@@ -1,22 +1,22 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
 
 
-var _NY3D6JQTcjs = require('../__chunks/NY3D6JQT.cjs');
+var _JFNPRZX3cjs = require('../__chunks/JFNPRZX3.cjs');
 
 
 var _NGEKJJDHcjs = require('../__chunks/NGEKJJDH.cjs');
 require('../__chunks/7LBZXSLY.cjs');
-require('../__chunks/UXFBTIBY.cjs');
-require('../__chunks/7ZVTEFD7.cjs');
-require('../__chunks/5UTRYT6E.cjs');
-require('../__chunks/DAJUUBUI.cjs');
+require('../__chunks/ER5DEJFH.cjs');
+require('../__chunks/2IMEEJHG.cjs');
+require('../__chunks/REJALU3P.cjs');
+require('../__chunks/OSTQZD2E.cjs');
 require('../__chunks/UZNYSPKP.cjs');
 require('../__chunks/BZTDJIVT.cjs');
 require('../__chunks/3W6FH6JK.cjs');
 require('../__chunks/UVBBMANL.cjs');
 require('../__chunks/F2A2ZQDB.cjs');
 require('../__chunks/S6UU7NA4.cjs');
-require('../__chunks/Z3GCTNW4.cjs');
+require('../__chunks/VUEWHLYH.cjs');
 require('../__chunks/75KXQZJX.cjs');
 
 
@@ -36,7 +36,7 @@ var useMenuDismiss = _RNZNGEL4cjs.createHook.call(void 0,
     var _b = _a, { store } = _b, props = _AV6KTKLEcjs.__objRest.call(void 0, _b, ["store"]);
     const context = _NGEKJJDHcjs.useMenuScopedContext.call(void 0, );
     store = store || context;
-    props = _NY3D6JQTcjs.useHovercardDismiss.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, { store }, props));
+    props = _JFNPRZX3cjs.useHovercardDismiss.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, { store }, props));
     return props;
   }
 );

package/cjs/menu/menu-dismiss.d.cts

@@ -15,10 +15,11 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuDismiss: import("../utils/types.js").Hook<MenuDismissOptions<"button">>;
 /**
- * Renders a button that hides a menu.
+ * Renders a button that hides a [`Menu`](https://ariakit.org/reference/menu)
+ * when clicked.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3}
  * <MenuProvider>
  *   <Menu>
  *     <MenuDismiss />

package/cjs/menu/menu-dismiss.d.ts

@@ -15,10 +15,11 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuDismiss: import("../utils/types.js").Hook<MenuDismissOptions<"button">>;
 /**
- * Renders a button that hides a menu.
+ * Renders a button that hides a [`Menu`](https://ariakit.org/reference/menu)
+ * when clicked.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3}
  * <MenuProvider>
  *   <Menu>
  *     <MenuDismiss />

package/cjs/menu/menu-group-label.d.cts

@@ -15,12 +15,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuGroupLabel: import("../utils/types.js").Hook<MenuGroupLabelOptions<"div">>;
 /**
- * Renders a label in a menu group. This component must be wrapped with
- * `MenuGroup` so the `aria-labelledby` prop is properly set on the menu group
- * element.
+ * Renders a label in a menu group. This component should be wrapped with
+ * [`MenuGroup`](https://ariakit.org/reference/menu-group) so the
+ * `aria-labelledby` is correctly set on the group element.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {5}
  * <MenuProvider>
  *   <MenuButton>Recent Items</MenuButton>
  *   <Menu>

package/cjs/menu/menu-group-label.d.ts

@@ -15,12 +15,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuGroupLabel: import("../utils/types.js").Hook<MenuGroupLabelOptions<"div">>;
 /**
- * Renders a label in a menu group. This component must be wrapped with
- * `MenuGroup` so the `aria-labelledby` prop is properly set on the menu group
- * element.
+ * Renders a label in a menu group. This component should be wrapped with
+ * [`MenuGroup`](https://ariakit.org/reference/menu-group) so the
+ * `aria-labelledby` is correctly set on the group element.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {5}
  * <MenuProvider>
  *   <MenuButton>Recent Items</MenuButton>
  *   <Menu>

package/cjs/menu/menu-group.d.cts

@@ -20,10 +20,13 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuGroup: import("../utils/types.js").Hook<MenuGroupOptions<"div">>;
 /**
- * Renders a menu group inside a menu.
+ * Renders a group for [`MenuItem`](https://ariakit.org/reference/menu-item)
+ * elements. Optionally, a
+ * [`MenuGroupLabel`](https://ariakit.org/reference/menu-group-label) can be
+ * rendered as a child to provide a label for the group.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {4-8}
  * <MenuProvider>
  *   <MenuButton>Recent Items</MenuButton>
  *   <Menu>

package/cjs/menu/menu-group.d.ts

@@ -20,10 +20,13 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuGroup: import("../utils/types.js").Hook<MenuGroupOptions<"div">>;
 /**
- * Renders a menu group inside a menu.
+ * Renders a group for [`MenuItem`](https://ariakit.org/reference/menu-item)
+ * elements. Optionally, a
+ * [`MenuGroupLabel`](https://ariakit.org/reference/menu-group-label) can be
+ * rendered as a child to provide a label for the group.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {4-8}
  * <MenuProvider>
  *   <MenuButton>Recent Items</MenuButton>
  *   <Menu>

package/cjs/menu/menu-heading.d.cts

@@ -15,8 +15,9 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuHeading: import("../utils/types.js").Hook<MenuHeadingOptions<"h1">>;
 /**
- * Renders a heading in a menu. This component must be wrapped with `Menu` so
- * the `aria-labelledby` prop is properly set on the menu element.
+ * Renders a heading in a menu. This component must be wrapped within
+ * [`Menu`](https://ariakit.org/reference/menu) so the `aria-labelledby` prop is
+ * properly set on the content element.
  * @see https://ariakit.org/components/menu
  * @example
  * ```jsx

package/cjs/menu/menu-heading.d.ts

@@ -15,8 +15,9 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuHeading: import("../utils/types.js").Hook<MenuHeadingOptions<"h1">>;
 /**
- * Renders a heading in a menu. This component must be wrapped with `Menu` so
- * the `aria-labelledby` prop is properly set on the menu element.
+ * Renders a heading in a menu. This component must be wrapped within
+ * [`Menu`](https://ariakit.org/reference/menu) so the `aria-labelledby` prop is
+ * properly set on the content element.
  * @see https://ariakit.org/components/menu
  * @example
  * ```jsx

package/cjs/menu/menu-item-check.d.cts

@@ -12,12 +12,18 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItemCheck: import("../utils/types.js").Hook<MenuItemCheckOptions<"span">>;
 /**
- * Renders a checkmark inside a `MenuItemCheckbox` or `MenuItemRadio`
- * components. This component must be wrapped with one of those components or
- * the `checked` prop must be explicitly passed to the component.
+ * Renders a checkmark icon when the
+ * [`checked`](https://ariakit.org/reference/menu-item-check#checked) prop is
+ * `true`. The icon can be overridden by providing a different one as children.
+ *
+ * When rendered inside
+ * [`MenuItemCheckbox`](https://ariakit.org/reference/menu-item-checkbox) or
+ * [`MenuItemRadio`](https://ariakit.org/reference/menu-item-radio) components,
+ * the [`checked`](https://ariakit.org/reference/menu-item-check#checked) prop
+ * is automatically derived from the context.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {5,9}
  * <MenuProvider defaultValues={{ apple: true, orange: false }}>
  *   <MenuButton>Fruits</MenuButton>
  *   <Menu>
@@ -40,19 +46,5 @@ export interface MenuItemCheckOptions<T extends As = "span"> extends Omit<Checkb
      * [`useMenuStore`](https://ariakit.org/reference/use-menu-store) hook.
      */
     store?: MenuStore;
-    /**
-     * Determines if the check mark should be displayed. This value is automatically
-     * derived from the parent
-     * [`MenuItemRadio`](https://ariakit.org/reference/menu-item-radio) or
-     * [`MenuItemCheckbox`](https://ariakit.org/reference/menu-item-checkbox)
-     * component.
-     *
-     * Manually setting this prop will supersede the derived value.
-     *
-     * Live examples:
-     * - [Submenu with
-     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
-     */
-    checked?: CheckboxCheckOptions<T>["checked"];
 }
 export type MenuItemCheckProps<T extends As = "span"> = Props<MenuItemCheckOptions<T>>;

package/cjs/menu/menu-item-check.d.ts

@@ -12,12 +12,18 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItemCheck: import("../utils/types.js").Hook<MenuItemCheckOptions<"span">>;
 /**
- * Renders a checkmark inside a `MenuItemCheckbox` or `MenuItemRadio`
- * components. This component must be wrapped with one of those components or
- * the `checked` prop must be explicitly passed to the component.
+ * Renders a checkmark icon when the
+ * [`checked`](https://ariakit.org/reference/menu-item-check#checked) prop is
+ * `true`. The icon can be overridden by providing a different one as children.
+ *
+ * When rendered inside
+ * [`MenuItemCheckbox`](https://ariakit.org/reference/menu-item-checkbox) or
+ * [`MenuItemRadio`](https://ariakit.org/reference/menu-item-radio) components,
+ * the [`checked`](https://ariakit.org/reference/menu-item-check#checked) prop
+ * is automatically derived from the context.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {5,9}
  * <MenuProvider defaultValues={{ apple: true, orange: false }}>
  *   <MenuButton>Fruits</MenuButton>
  *   <Menu>
@@ -40,19 +46,5 @@ export interface MenuItemCheckOptions<T extends As = "span"> extends Omit<Checkb
      * [`useMenuStore`](https://ariakit.org/reference/use-menu-store) hook.
      */
     store?: MenuStore;
-    /**
-     * Determines if the check mark should be displayed. This value is automatically
-     * derived from the parent
-     * [`MenuItemRadio`](https://ariakit.org/reference/menu-item-radio) or
-     * [`MenuItemCheckbox`](https://ariakit.org/reference/menu-item-checkbox)
-     * component.
-     *
-     * Manually setting this prop will supersede the derived value.
-     *
-     * Live examples:
-     * - [Submenu with
-     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
-     */
-    checked?: CheckboxCheckOptions<T>["checked"];
 }
 export type MenuItemCheckProps<T extends As = "span"> = Props<MenuItemCheckOptions<T>>;

package/cjs/menu/menu-item-checkbox.cjs

@@ -1,22 +1,22 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
 
 
-var _BBS4RP44cjs = require('../__chunks/BBS4RP44.cjs');
-require('../__chunks/63UPRTFZ.cjs');
+var _VPQQSYH7cjs = require('../__chunks/VPQQSYH7.cjs');
 
 
-var _VPQQSYH7cjs = require('../__chunks/VPQQSYH7.cjs');
+var _2UEWAQWGcjs = require('../__chunks/2UEWAQWG.cjs');
+require('../__chunks/63UPRTFZ.cjs');
 
 
-var _NNINKJTTcjs = require('../__chunks/NNINKJTT.cjs');
+var _QSU3WKMWcjs = require('../__chunks/QSU3WKMW.cjs');
 
 
 var _NGEKJJDHcjs = require('../__chunks/NGEKJJDH.cjs');
 require('../__chunks/7LBZXSLY.cjs');
 require('../__chunks/IPYAEPOT.cjs');
 require('../__chunks/ERFHNHON.cjs');
-require('../__chunks/IO6J4PAN.cjs');
-require('../__chunks/DAJUUBUI.cjs');
+require('../__chunks/GSETTLOU.cjs');
+require('../__chunks/OSTQZD2E.cjs');
 require('../__chunks/R5A2WTWB.cjs');
 require('../__chunks/6ZZYUFPW.cjs');
 require('../__chunks/UZNYSPKP.cjs');
@@ -25,7 +25,7 @@ require('../__chunks/3W6FH6JK.cjs');
 require('../__chunks/UVBBMANL.cjs');
 require('../__chunks/F2A2ZQDB.cjs');
 require('../__chunks/S6UU7NA4.cjs');
-require('../__chunks/Z3GCTNW4.cjs');
+require('../__chunks/VUEWHLYH.cjs');
 require('../__chunks/75KXQZJX.cjs');
 
 
@@ -130,13 +130,13 @@ var useMenuItemCheckbox = _RNZNGEL4cjs.createHook.call(void 0,
     props = _AV6KTKLEcjs.__spreadValues.call(void 0, {
       role: "menuitemcheckbox"
     }, props);
-    props = _BBS4RP44cjs.useCheckbox.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
+    props = _2UEWAQWGcjs.useCheckbox.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
       store: checkboxStore,
       name,
       value,
       checked
     }, props));
-    props = _NNINKJTTcjs.useMenuItem.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, { store, hideOnClick }, props));
+    props = _QSU3WKMWcjs.useMenuItem.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, { store, hideOnClick }, props));
     return props;
   }
 );

package/cjs/menu/menu-item-checkbox.d.cts

@@ -17,14 +17,43 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItemCheckbox: import("../utils/types.js").Hook<MenuItemCheckboxOptions<"div">>;
 /**
- * Renders a menu item checkbox inside a menu.
+ * Renders a [`menuitemcheckbox`](https://w3c.github.io/aria/#menuitemcheckbox)
+ * element within a [`Menu`](https://ariakit.org/reference/menu) component. The
+ * [`name`](https://ariakit.org/reference/menu-item-checkbox#name) prop must be
+ * provided to identify the field in the
+ * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+ *
+ * A [`MenuItemCheck`](https://ariakit.org/reference/menu-item-check) can be
+ * used to render a checkmark inside this component.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
- * <MenuProvider defaultValues={{ apple: false }}>
- *   <MenuButton>Fruits</MenuButton>
+ * The [`name`](https://ariakit.org/reference/menu-item-checkbox#name) prop can
+ * refer to a single value in the state:
+ * ```jsx {4-7}
+ * <MenuProvider defaultValues={{ warnBeforeQuitting: true }}>
+ *   <MenuButton>Chrome</MenuButton>
+ *   <Menu>
+ *     <MenuItemCheckbox name="warnBeforeQuitting">
+ *       <MenuItemCheck />
+ *       Warn Before Quitting
+ *     </MenuItemCheckbox>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ * @example
+ * Or it can refer to an array of values, in which case the
+ * [`value`](https://ariakit.org/reference/menu-item-checkbox#value) prop must
+ * be provided:
+ * ```jsx {4-9}
+ * <MenuProvider defaultValues={{ watching: ["issues"] }}>
+ *   <MenuButton>Watch</MenuButton>
  *   <Menu>
- *     <MenuItemCheckbox name="apple">Apple</MenuItemCheckbox>
+ *     <MenuItemCheckbox name="watching" value="issues">
+ *       Issues
+ *     </MenuItemCheckbox>
+ *     <MenuItemCheckbox name="watching" value="pull-requests">
+ *       Pull Requests
+ *     </MenuItemCheckbox>
  *   </Menu>
  * </MenuProvider>
  * ```
@@ -40,8 +69,11 @@ export interface MenuItemCheckboxOptions<T extends As = "div"> extends MenuItemO
      */
     store?: MenuStore;
     /**
-     * MenuItemCheckbox's name as specified in the
+     * The name of the field in the
      * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+     *
+     * Live examples:
+     * - [MenuItemCheckbox](https://ariakit.org/examples/menu-item-checkbox)
      */
     name: string;
     /**

package/cjs/menu/menu-item-checkbox.d.ts

@@ -17,14 +17,43 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItemCheckbox: import("../utils/types.js").Hook<MenuItemCheckboxOptions<"div">>;
 /**
- * Renders a menu item checkbox inside a menu.
+ * Renders a [`menuitemcheckbox`](https://w3c.github.io/aria/#menuitemcheckbox)
+ * element within a [`Menu`](https://ariakit.org/reference/menu) component. The
+ * [`name`](https://ariakit.org/reference/menu-item-checkbox#name) prop must be
+ * provided to identify the field in the
+ * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+ *
+ * A [`MenuItemCheck`](https://ariakit.org/reference/menu-item-check) can be
+ * used to render a checkmark inside this component.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
- * <MenuProvider defaultValues={{ apple: false }}>
- *   <MenuButton>Fruits</MenuButton>
+ * The [`name`](https://ariakit.org/reference/menu-item-checkbox#name) prop can
+ * refer to a single value in the state:
+ * ```jsx {4-7}
+ * <MenuProvider defaultValues={{ warnBeforeQuitting: true }}>
+ *   <MenuButton>Chrome</MenuButton>
+ *   <Menu>
+ *     <MenuItemCheckbox name="warnBeforeQuitting">
+ *       <MenuItemCheck />
+ *       Warn Before Quitting
+ *     </MenuItemCheckbox>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ * @example
+ * Or it can refer to an array of values, in which case the
+ * [`value`](https://ariakit.org/reference/menu-item-checkbox#value) prop must
+ * be provided:
+ * ```jsx {4-9}
+ * <MenuProvider defaultValues={{ watching: ["issues"] }}>
+ *   <MenuButton>Watch</MenuButton>
  *   <Menu>
- *     <MenuItemCheckbox name="apple">Apple</MenuItemCheckbox>
+ *     <MenuItemCheckbox name="watching" value="issues">
+ *       Issues
+ *     </MenuItemCheckbox>
+ *     <MenuItemCheckbox name="watching" value="pull-requests">
+ *       Pull Requests
+ *     </MenuItemCheckbox>
  *   </Menu>
  * </MenuProvider>
  * ```
@@ -40,8 +69,11 @@ export interface MenuItemCheckboxOptions<T extends As = "div"> extends MenuItemO
      */
     store?: MenuStore;
     /**
-     * MenuItemCheckbox's name as specified in the
+     * The name of the field in the
      * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+     *
+     * Live examples:
+     * - [MenuItemCheckbox](https://ariakit.org/examples/menu-item-checkbox)
      */
     name: string;
     /**