@coopdigital/react 0.46.0 → 0.48.0

package/dist/components/Tag/Tag.js

@@ -2,18 +2,15 @@ import clsx from 'clsx';
 import React from 'react';
 import { hasUserBg } from '../../utils/index.js';
 
-const Tag = ({ as, children, className, href, size = "md", ...props }) => {
-    let element = href ? "a" : "span";
+const Tag = ({ as, children, className, href, ref, size = "md", ...props }) => {
+    const element = as !== null && as !== void 0 ? as : (href ? "a" : "span");
     const componentProps = {
         className: clsx("coop-tag", !hasUserBg(className) && "bg-tint-grey", className),
         "data-size": size.length && size !== "md" ? size : undefined,
         href,
         ...props,
     };
-    if (as) {
-        element = as;
-    }
-    return React.createElement(element, { ...componentProps }, children);
+    return React.createElement(element, { ...componentProps, ref }, children);
 };
 
 export { Tag, Tag as default };

package/dist/components/TextInput/TextInput.d.ts

@@ -1,4 +1,4 @@
-import type { InputHTMLAttributes, JSX } from "react";
+import type { InputHTMLAttributes, JSX, Ref } from "react";
 import { StandardSizes } from "../../../src/types";
 export interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "prefix" | "size" | "type"> {
     /** **(Optional)** Specify additional CSS classes to be applied to the component. */
@@ -15,6 +15,8 @@ export interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElemen
     placeholder?: string;
     /** **(Optional)** Specify the prefix. It can be any valid JSX or string. */
     prefix?: React.ReactNode;
+    /** **(Optional)** Specify a custom React ref for this component. */
+    ref?: Ref<HTMLInputElement>;
     /** **(Optional)** Specify the TextInput size. */
     size?: StandardSizes;
     /** **(Optional)** Specify the suffix. It can be any valid JSX or string. */
@@ -22,5 +24,5 @@ export interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElemen
     /** **(Optional)** Specify the TextInput type. */
     type?: "text" | "email" | "number" | "password" | "search" | "tel" | "url" | "date" | "datetime-local" | "week" | "month" | "time";
 }
-export declare const TextInput: ({ "aria-placeholder": ariaPlaceholder, className, disabled, error, id, name, placeholder, prefix, size, suffix, type, ...props }: TextInputProps) => JSX.Element;
+export declare const TextInput: ({ "aria-placeholder": ariaPlaceholder, className, disabled, error, id, name, placeholder, prefix, ref, size, suffix, type, ...props }: TextInputProps) => JSX.Element;
 export default TextInput;

package/dist/components/TextInput/TextInput.js

@@ -2,12 +2,12 @@ import { jsxs, jsx } from 'react/jsx-runtime';
 import clsx from 'clsx';
 import { useId } from '../../hooks/useId.js';
 
-const TextInput = ({ "aria-placeholder": ariaPlaceholder, className, disabled, error = false, id, name, placeholder, prefix, size = "md", suffix, type = "text", ...props }) => {
+const TextInput = ({ "aria-placeholder": ariaPlaceholder, className, disabled, error = false, id, name, placeholder, prefix, ref, size = "md", suffix, type = "text", ...props }) => {
     var _a;
     const uid = useId(id);
     const componentProps = {
         "aria-placeholder": (_a = placeholder !== null && placeholder !== void 0 ? placeholder : ariaPlaceholder) !== null && _a !== void 0 ? _a : undefined,
-        className: clsx("coop-text-input", className),
+        className: clsx("coop-text-input", "coop-field-element", className),
         "data-error": error || undefined,
         "data-size": size.length && size !== "md" ? size : undefined,
         disabled,
@@ -18,7 +18,7 @@ const TextInput = ({ "aria-placeholder": ariaPlaceholder, className, disabled, e
         ...props,
     };
     //const formItemProps = { "aria-disabled": disabled ? true : undefined }
-    return (jsxs("div", { className: "coop-text-input-wrapper", children: [prefix && jsx("span", { className: "coop-text-input--prefix", children: prefix }), jsx("input", { ...componentProps }), suffix && jsx("span", { className: "coop-text-input--suffix", children: suffix })] }));
+    return (jsxs("div", { className: "coop-text-input-wrapper", children: [prefix && jsx("span", { className: "coop-text-input--prefix", children: prefix }), jsx("input", { ...componentProps, ref: ref }), suffix && jsx("span", { className: "coop-text-input--suffix", children: suffix })] }));
 };
 
 export { TextInput, TextInput as default };

package/dist/components/Textarea/Textarea.d.ts

@@ -1,4 +1,4 @@
-import type { JSX, TextareaHTMLAttributes } from "react";
+import type { JSX, Ref, TextareaHTMLAttributes } from "react";
 import { StandardSizes } from "../../types";
 export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
     /** **(Optional)** Specify additional CSS classes to be applied to the component. */
@@ -26,10 +26,12 @@ export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElemen
     name: string;
     /** **(Optional)** Specify the Textarea placeholder text. Do not use in place of a form label. */
     placeholder?: string;
+    /** **(Optional)** Specify a custom React ref for this component. */
+    ref?: Ref<HTMLTextAreaElement>;
     /** Specify the number of rows (lines of text) in the Textarea. Defaults to `4`. */
     rows?: number;
     /** **(Optional)** Specify the Textarea size. */
     size?: StandardSizes;
 }
-export declare const Textarea: ({ "aria-placeholder": ariaPlaceholder, className, cols, counter, cutoff, disabled, error, id, maxLength, name, onChange: userOnChange, placeholder, rows, size, ...props }: TextareaProps) => JSX.Element;
+export declare const Textarea: ({ "aria-placeholder": ariaPlaceholder, className, cols, counter, cutoff, disabled, error, id, maxLength, name, onChange: userOnChange, placeholder, ref, rows, size, ...props }: TextareaProps) => JSX.Element;
 export default Textarea;

package/dist/components/Textarea/Textarea.js

@@ -8,18 +8,17 @@ const DEBOUNCE_DELAY = 750;
 const charCountMessage = (remaining) => {
     return `You have ${Math.abs(remaining).toLocaleString()} ${Math.abs(remaining) === 1 ? "character" : "characters"} ${remaining < 0 ? "too many" : "remaining"}`;
 };
-const Textarea = ({ "aria-placeholder": ariaPlaceholder, className, cols = 30, counter = false, cutoff = false, disabled = false, error = false, id, maxLength, name, onChange: userOnChange = undefined, placeholder, rows = 4, size = "md", ...props }) => {
+const Textarea = ({ "aria-placeholder": ariaPlaceholder, className, cols = 30, counter = false, cutoff = false, disabled = false, error = false, id, maxLength, name, onChange: userOnChange = undefined, placeholder, ref, rows = 4, size = "md", ...props }) => {
     var _a;
-    const internalId = useId();
-    id = id !== null && id !== void 0 ? id : internalId;
+    const uid = useId(id);
     const componentProps = {
         "aria-placeholder": (_a = placeholder !== null && placeholder !== void 0 ? placeholder : ariaPlaceholder) !== null && _a !== void 0 ? _a : undefined,
-        className: clsx("coop-textarea", className),
+        className: clsx("coop-textarea", "coop-field-element", className),
         cols,
         "data-error": error !== null && error !== void 0 ? error : undefined,
         "data-size": size.length && size !== "md" ? size : undefined,
         disabled,
-        id,
+        id: uid,
         maxLength: cutoff ? maxLength : undefined,
         name,
         placeholder,
@@ -36,7 +35,7 @@ const Textarea = ({ "aria-placeholder": ariaPlaceholder, className, cols = 30, c
     return (jsxs("div", { className: "coop-textarea-wrapper", children: [jsx("textarea", { ...componentProps, onChange: (e) => {
                     userOnChange === null || userOnChange === void 0 ? void 0 : userOnChange(e);
                     handleChange(e);
-                } }), showCounter && (jsxs(Fragment, { children: [jsx("small", { "aria-hidden": "true", className: "coop-textarea-counter", ...(remaining < 0 && { "data-error": true }), children: charCountMessage(remaining) }), jsx("span", { "aria-live": "polite", className: "sr-only", children: charCountMessage(debouncedRemaining) })] }))] }));
+                }, ref: ref }), showCounter && (jsxs(Fragment, { children: [jsx("small", { "aria-hidden": "true", className: "coop-textarea-counter", ...(remaining < 0 && { "data-error": true }), children: charCountMessage(remaining) }), jsx("span", { "aria-live": "polite", className: "sr-only", children: charCountMessage(debouncedRemaining) })] }))] }));
 };
 
 export { Textarea, Textarea as default };

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from "./components/Pill";
 export * from "./components/Radio";
 export * from "./components/RootSVG";
 export * from "./components/Searchbox";
+export * from "./components/Select";
 export * from "./components/Signpost";
 export * from "./components/SkipNav";
 export * from "./components/Squircle";

package/dist/index.js

@@ -12,6 +12,7 @@ export { Pill } from './components/Pill/Pill.js';
 export { Radio } from './components/Radio/Radio.js';
 export { RootSVG } from './components/RootSVG/RootSVG.js';
 export { Searchbox } from './components/Searchbox/Searchbox.js';
+export { Select } from './components/Select/Select.js';
 export { Signpost } from './components/Signpost/Signpost.js';
 export { SkipNav } from './components/SkipNav/SkipNav.js';
 export { Squircle } from './components/Squircle/Squircle.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coopdigital/react",
   "type": "module",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -56,19 +56,19 @@
   "description": "",
   "devDependencies": {
     "@axe-core/playwright": "^4.11.0",
-    "@playwright/test": "^1.56.1",
-    "@storybook/addon-a11y": "^10.0.7",
-    "@storybook/addon-docs": "^10.0.7",
-    "@storybook/addon-onboarding": "^10.0.7",
-    "@storybook/react-vite": "^10.0.7",
+    "@playwright/test": "^1.57.0",
+    "@storybook/addon-a11y": "^10.1.0",
+    "@storybook/addon-docs": "^10.1.0",
+    "@storybook/addon-onboarding": "^10.1.0",
+    "@storybook/react-vite": "^10.1.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
-    "@types/react": "^19.2.4",
+    "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "serve": "^14.2.5",
-    "storybook": "^10.0.7"
+    "storybook": "^10.1.0"
   },
   "peerDependencies": {
     "react": "^19.1.0",
@@ -78,8 +78,8 @@
     "storybook": "$storybook"
   },
   "dependencies": {
-    "@coopdigital/styles": "^0.40.0",
+    "@coopdigital/styles": "^0.41.0",
     "clsx": "^2.1.1"
   },
-  "gitHead": "9020e79195ead8270e9a2c39209142a02160bae5"
+  "gitHead": "96d3459231c76b94984900894ac0ae2bac2f091b"
 }

package/src/components/AlertBanner/AlertBanner.tsx

@@ -1,4 +1,4 @@
-import type { HTMLAttributes, JSX, ReactNode } from "react"
+import type { HTMLAttributes, JSX, ReactNode, Ref } from "react"
 
 import clsx from "clsx"
 
@@ -7,16 +7,23 @@ export interface AlertBannerProps extends HTMLAttributes<HTMLDivElement> {
   children?: string | ReactNode
   /** **(Optional)** Specify additional CSS classes to be applied to the component. */
   className?: string
-  /** Specify the main title of the banner, rendered as a `h2`. */
-  heading: string
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLDivElement>
   /** **(Optional)** Specify the AlertBanner variant. */
   variant?: "black" | "default"
 }
 
+interface AlertBannerHeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+  /** **(Optional)** Content inside the Heading. */
+  children?: React.ReactNode
+  /** **(Optional)** Specify additional CSS classes to be applied to the Heading. */
+  className?: string
+}
+
 export const AlertBanner = ({
   children,
   className,
-  heading,
+  ref,
   variant = "default",
   ...props
 }: AlertBannerProps): JSX.Element => {
@@ -25,14 +32,20 @@ export const AlertBanner = ({
     "data-variant": variant,
     ...props,
   }
+
   return (
-    <aside {...componentProps}>
-      <div className="coop-alert-banner--inner">
-        <h2 id="coop-alert-banner--headline">{heading}</h2>
-        {children}
-      </div>
+    <aside {...componentProps} ref={ref}>
+      {children}
     </aside>
   )
 }
 
+const AlertBannerHeading = ({ children, className }: AlertBannerHeadingProps): JSX.Element => {
+  return <h2 className={className}>{children}</h2>
+}
+
+AlertBannerHeading.displayName = "AlertBanner.Heading"
+
+AlertBanner.Heading = AlertBannerHeading
+
 export default AlertBanner

package/src/components/Author/Author.tsx

@@ -1,4 +1,4 @@
-import type { HTMLAttributes, JSX } from "react"
+import type { HTMLAttributes, JSX, Ref } from "react"
 
 import clsx from "clsx"
 
@@ -15,6 +15,8 @@ export interface AuthorProps extends HTMLAttributes<HTMLDivElement> {
   datePrefix?: string
   /** **(Optional)** Specify properties of the Author Image. */
   image?: ImageProps
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLDivElement>
 }
 
 export const Author = ({
@@ -26,6 +28,7 @@ export const Author = ({
     alt: "",
     src: "https://s3.eu-west-1.amazonaws.com/assets.digital.coop.co.uk/oneweb/coop-logo-inverted.svg",
   },
+  ref,
   ...props
 }: AuthorProps): JSX.Element => {
   const imageProps: ImageProps = {
@@ -38,7 +41,7 @@ export const Author = ({
     ...props,
   }
   return (
-    <div {...componentProps}>
+    <div {...componentProps} ref={ref}>
       {image && <Image {...imageProps} />}
       <div className="coop-author--content">
         <span>

package/src/components/Button/Button.tsx

@@ -28,7 +28,7 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /** **(Optional)** Callback to run when the button is pressed. If this is an async function, it will be awaited and the button will be in a pending state until the promise is resolved. */
   onClick?: React.MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>
   /** **(Optional)** Specify a custom React ref for this component. */
-  ref?: Ref<HTMLButtonElement | HTMLAnchorElement>
+  ref?: Ref<HTMLElement>
   /** **(Optional)** Specify the Button size. */
   size?: "sm" | "md" | "lg"
   /** **(Optional)** Specify the Button variant. */
@@ -92,7 +92,6 @@ export const Button = ({
     "data-width": isFullWidth ? "full" : undefined,
     href,
     onClick: onClick ? handleClick : undefined,
-    ref,
     ...props,
   }
 
@@ -106,6 +105,6 @@ export const Button = ({
       children
     )
 
-  return React.createElement(element, { ...componentProps }, finalChildren)
+  return React.createElement(element, { ...componentProps, ref }, finalChildren)
 }
 export default Button

package/src/components/Card/Card.tsx

@@ -1,4 +1,4 @@
-import type { ForwardRefExoticComponent, HTMLAttributes, JSX } from "react"
+import type { ForwardRefExoticComponent, HTMLAttributes, JSX, Ref } from "react"
 
 import clsx from "clsx"
 import React from "react"
@@ -24,6 +24,8 @@ export interface CardProps extends HTMLAttributes<HTMLDivElement> {
   imagePosition?: "left" | "right"
   /** **(Optional)** Specify the orientation of the Card. */
   orientation?: "vertical" | "horizontal"
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLDivElement>
 }
 
 interface CardLabelProps extends HTMLAttributes<HTMLSpanElement> {
@@ -87,6 +89,7 @@ export const Card = ({
   hrefAs,
   imagePosition = "left",
   orientation = "vertical",
+  ref,
   ...props
 }: CardProps): JSX.Element => {
   const { element: linkElement, props: linkProps } = getCardLinkElement(hrefAs, href)
@@ -107,7 +110,7 @@ export const Card = ({
   }
 
   return (
-    <article {...componentProps}>
+    <article {...componentProps} ref={ref}>
       {slots.CardImage}
       {slots.CardBadge}
       {React.createElement(

package/src/components/Checkbox/Checkbox.tsx

@@ -1,12 +1,14 @@
-import type { InputHTMLAttributes, JSX } from "react"
+import type { InputHTMLAttributes, JSX, Ref } from "react"
 
 import clsx from "clsx"
 
 import { StandardSizes } from "../../../src/types"
 import { useId } from "../../hooks/useId"
 
-export interface CheckboxProps
-  extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
+export interface CheckboxProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  "size" | "type"
+> {
   /** **(Optional)** Specify additional CSS classes to be applied to the component. */
   className?: string
   /** **(Optional)** Specify whether the Checkbox should be disabled. Refer to Experience Library guidance on disabled form controls and accessibility. */
@@ -17,6 +19,8 @@ export interface CheckboxProps
   id?: string
   /** Specify the Checkbox name. */
   name: string
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLInputElement>
   /** **(Optional)** Specify the Checkbox size. */
   size?: StandardSizes
 }
@@ -27,12 +31,13 @@ export const Checkbox = ({
   error = false,
   id,
   name,
+  ref,
   size = "md",
   ...props
 }: CheckboxProps): JSX.Element => {
   const uid = useId(id)
   const componentProps = {
-    className: clsx("coop-checkbox", className),
+    className: clsx("coop-checkbox", "coop-field-element", className),
     "data-error": error || undefined,
     "data-size": size.length && size !== "md" ? size : undefined,
     disabled,
@@ -41,7 +46,8 @@ export const Checkbox = ({
     type: "checkbox",
     ...props,
   }
-  return <input {...componentProps} />
+
+  return <input {...componentProps} ref={ref} />
 }
 
 export default Checkbox

package/src/components/Expandable/Expandable.tsx

@@ -1,4 +1,4 @@
-import type { DetailsHTMLAttributes, HTMLAttributes, JSX } from "react"
+import type { DetailsHTMLAttributes, HTMLAttributes, JSX, Ref } from "react"
 
 import { clsx } from "clsx"
 
@@ -11,6 +11,8 @@ export interface ExpandableProps extends DetailsHTMLAttributes<HTMLDetailsElemen
   children: React.ReactNode
   /** **(Optional)** Specify additional CSS classes to be applied to the component. */
   className?: string
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLDetailsElement>
 }
 
 interface ExpandableSummaryProps extends HTMLAttributes<HTMLElement> {
@@ -25,7 +27,12 @@ const componentSlots = {
   ExpandableSummary: null,
 }
 
-export const Expandable = ({ children, className, ...props }: ExpandableProps): JSX.Element => {
+export const Expandable = ({
+  children,
+  className,
+  ref,
+  ...props
+}: ExpandableProps): JSX.Element => {
   const slots = useSlots(componentSlots, children)
 
   const componentProps = {
@@ -38,7 +45,7 @@ export const Expandable = ({ children, className, ...props }: ExpandableProps):
   }
 
   return (
-    <details {...componentProps}>
+    <details {...componentProps} ref={ref}>
       {slots.ExpandableSummary}
       <div className="coop-expandable--content">{slots.Children}</div>
     </details>

package/src/components/Field/Field.tsx

@@ -1,4 +1,4 @@
-import type { HTMLAttributes, HTMLProps, JSX } from "react"
+import type { HTMLAttributes, HTMLProps, JSX, Ref } from "react"
 
 import clsx from "clsx"
 import React from "react"
@@ -17,6 +17,7 @@ const componentSlots = {
   FieldHint: null,
   FieldLabel: null,
   Radio: null,
+  Select: null,
   Textarea: null,
   TextInput: null,
 }
@@ -37,6 +38,8 @@ interface FieldProps extends HTMLAttributes<HTMLDivElement> {
   error?: boolean
   /** **(Optional)** Specify whether the Field should show the left-hand error bar if it is in an error state. */
   hideErrorBar?: boolean
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLDivElement>
 }
 
 const Root = ({
@@ -45,19 +48,18 @@ const Root = ({
   className,
   error = false,
   hideErrorBar = false,
+  ref,
   ...props
 }: FieldProps) => {
   const slots = { ...useSlots(componentSlots, children) }
   const slotsArray = Object.entries(slots)
 
-  const uid = useId()
-
   const isInlineControl = slotsArray.some((s) => s[1] !== null && inlineFields.includes(s[0]))
   const hasFieldMarkers = !!(slots.FieldLabel ?? slots.FieldError ?? slots.FieldHint)
   const [, control] =
     slotsArray.find((s) => (!standardFields.includes(s[0]) && s[1] !== null ? s : null)) ?? []
 
-  let controlId = uid
+  let controlId = useId()
   let controlDisabled = false
 
   if (control) {
@@ -88,7 +90,7 @@ const Root = ({
   }
 
   return (
-    <div {...componentProps}>
+    <div {...componentProps} ref={ref}>
       {!isInlineControl && hasFieldMarkers && (
         <div className="coop-field-markers">
           {slots.FieldLabel}

package/src/components/FieldMarkers/Error.tsx

@@ -1,4 +1,4 @@
-import type { HTMLAttributes, JSX, ReactNode } from "react"
+import type { HTMLAttributes, JSX, ReactNode, Ref } from "react"
 
 import clsx from "clsx"
 
@@ -7,14 +7,20 @@ export interface ErrorProps extends HTMLAttributes<HTMLSpanElement> {
   children?: string | ReactNode
   /** **(Optional)** Specify additional CSS classes to be applied to the component. */
   className?: string
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLSpanElement>
 }
 
-export const Error = ({ children, className, ...props }: ErrorProps): JSX.Element => {
+export const Error = ({ children, className, ref, ...props }: ErrorProps): JSX.Element => {
   const componentProps = {
     className: clsx("coop-field-error ", className),
     ...props,
   }
-  return <span {...componentProps}>{children}</span>
+  return (
+    <span {...componentProps} ref={ref}>
+      {children}
+    </span>
+  )
 }
 
 export default Error

package/src/components/FieldMarkers/Hint.tsx

@@ -1,21 +1,27 @@
-import type { HTMLAttributes, JSX, ReactNode } from "react"
+import type { HTMLAttributes, JSX, ReactNode, Ref } from "react"
 
 import clsx from "clsx"
 
-export interface HintProps extends HTMLAttributes<HTMLParagraphElement> {
+export interface HintProps extends HTMLAttributes<HTMLDivElement> {
   /** **(Optional)** Hint text for the form element. Accepts any valid JSX or string. */
   children?: string | ReactNode
   /** **(Optional)** Specify additional CSS classes to be applied to the component. */
   className?: string
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLDivElement>
 }
 
-export const Hint = ({ children, className, ...props }: HintProps): JSX.Element | null => {
+export const Hint = ({ children, className, ref, ...props }: HintProps): JSX.Element | null => {
   const componentProps = {
     className: clsx("coop-field-hint ", className),
     ...props,
   }
 
-  return children ? <div {...componentProps}>{children}</div> : null
+  return (
+    <div {...componentProps} ref={ref}>
+      {children}
+    </div>
+  )
 }
 
 export default Hint

package/src/components/FieldMarkers/Label.tsx

@@ -1,5 +1,5 @@
 import clsx from "clsx"
-import { LabelHTMLAttributes } from "react"
+import { LabelHTMLAttributes, Ref } from "react"
 
 export interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
   /** **(Optional)** Main label for the form element. Accepts any valid JSX or string. */
@@ -8,11 +8,17 @@ export interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
   className?: string
   /** **(Optional)** Specify whether the label is visible for humans or only for screen readers. */
   isVisible?: boolean
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLLabelElement>
 }
 
-export const Label = ({ children, className, isVisible = true, ...props }: LabelProps) => {
+export const Label = ({ children, className, isVisible = true, ref, ...props }: LabelProps) => {
+  const componentProps = {
+    className: clsx("coop-field-label", !isVisible && "sr-only", className),
+    ...props,
+  }
   return (
-    <label {...props} className={clsx("coop-field-label", !isVisible && "sr-only", className)}>
+    <label {...componentProps} ref={ref}>
       <span>{children}</span>
     </label>
   )

package/src/components/FieldMarkers/Legend.tsx

@@ -1,5 +1,5 @@
 import clsx from "clsx"
-import { HTMLAttributes } from "react"
+import { HTMLAttributes, Ref } from "react"
 
 export interface LegendProps extends HTMLAttributes<HTMLLegendElement> {
   /** **(Optional)** Main legend for the fieldset. Accepts any valid JSX or string. */
@@ -8,9 +8,11 @@ export interface LegendProps extends HTMLAttributes<HTMLLegendElement> {
   className?: string
   /** **(Optional)** Specify whether the legend should be visible to humans or screen readers. */
   isVisible?: boolean
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLLegendElement>
 }
 
-export const Legend = ({ children, className, isVisible = true, ...props }: LegendProps) => {
+export const Legend = ({ children, className, isVisible = true, ref, ...props }: LegendProps) => {
   const componentProps = {
     "aria-hidden": true,
     className: clsx("coop-field-label", !isVisible && "sr-only", className),
@@ -20,7 +22,11 @@ export const Legend = ({ children, className, isVisible = true, ...props }: Lege
   return (
     <>
       <legend className="sr-only">{children}</legend>
-      {isVisible && <div {...componentProps}>{children}</div>}
+      {isVisible && (
+        <div {...componentProps} ref={ref}>
+          {children}
+        </div>
+      )}
     </>
   )
 }

package/src/components/Fieldset/Fieldset.tsx

@@ -1,5 +1,5 @@
 import clsx from "clsx"
-import { type FieldsetHTMLAttributes, type JSX } from "react"
+import { type FieldsetHTMLAttributes, type JSX, Ref } from "react"
 
 import { StandardSizes } from "../../../src/types"
 import { Error as BaseError, type ErrorProps } from "../FieldMarkers/Error"
@@ -19,6 +19,8 @@ export interface FieldsetProps extends FieldsetHTMLAttributes<HTMLFieldSetElemen
   error?: boolean
   /** **(Optional)** Specify whether the Fieldset should show the left-hand error bar if it is in an error state. */
   hideErrorBar?: boolean
+  /** **(Optional)** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLFieldSetElement>
   /** **(Optional)** Specify the size of the Fieldset and all its descendents. */
   size?: StandardSizes
 }
@@ -28,6 +30,7 @@ const Root = ({
   disabled,
   error = false,
   hideErrorBar = false,
+  ref,
   size = "md",
   ...props
 }: FieldsetProps): JSX.Element => {
@@ -35,15 +38,17 @@ const Root = ({
     "aria-disabled": disabled,
     className: clsx("coop-fieldset", className),
     "data-error": error || undefined,
-    //"data-variant": variant !== "default" ? variant : undefined,
     "data-hide-error": hideErrorBar || undefined,
-    // "data-orientation": orientation !== "vertical" ? orientation : undefined,
     "data-size": size.length && size !== "md" ? size : undefined,
     disabled,
     ...props,
   }
 
-  return <fieldset {...componentProps}>{children}</fieldset>
+  return (
+    <fieldset {...componentProps} ref={ref}>
+      {children}
+    </fieldset>
+  )
 }
 
 interface FieldsetFieldsProps {