` element.
+
+
+
+### Description
+
+A paragraph with additional information about the field. Renders a `
` element.
+
+
+
+### Validity
+
+Provides field validity state to a render function. Use for custom validity-based rendering.
+
+## Examples
+
+### With InputField
+
+Use Field to add label, helper text, and error to an InputField.
+
+
+
+### With TextArea
+
+Field works with TextArea the same way.
+
+
+
+### With Select
+
+Base UI-based components like Select auto-connect with Field for accessibility.
+
+
+
+### Error State
+
+Shows an error message and sets the invalid state on the field.
+
+
+
+### Helper Text
+
+Displays additional context below the control.
+
+
+
+### Required Field
+
+Shows a required indicator next to the label.
+
+
+
+### Optional Field
+
+Shows an optional indicator next to the label.
+
+
+
+### Sub-component API
+
+Use sub-components for Base UI native validation and custom error matching.
+
+
+
+## Accessibility
+
+- `Field.Label` automatically associates with the field control via `aria-labelledby`
+- `Field.Description` automatically associates via `aria-describedby`
+- `Field.Error` automatically associates error messages with the control
+- Data attributes (`data-invalid`, `data-dirty`, `data-touched`, `data-filled`, `data-focused`) propagate to all sub-components
diff --git a/apps/www/src/content/docs/components/field/props.ts b/apps/www/src/content/docs/components/field/props.ts
new file mode 100644
index 000000000..c25d6e6cb
--- /dev/null
+++ b/apps/www/src/content/docs/components/field/props.ts
@@ -0,0 +1,80 @@
+export interface FieldProps {
+ /** Text or node to render as the field label. */
+ label?: React.ReactNode;
+
+ /** Helper text displayed below the control. Hidden when error is present. */
+ helperText?: React.ReactNode;
+
+ /** Error message displayed below the control. Sets the field to invalid state. */
+ error?: React.ReactNode;
+
+ /**
+ * Shows a required indicator (*) next to the label.
+ * @defaultValue false
+ */
+ required?: boolean;
+
+ /**
+ * Shows an (optional) indicator next to the label.
+ * @defaultValue false
+ */
+ optional?: boolean;
+
+ /** Custom width for the field container. */
+ width?: string | number;
+
+ /** Identifies the field during form submission. */
+ name?: string;
+
+ /** Custom validation function. Return an error string or null. */
+ validate?: (
+ value: unknown
+ ) => string | string[] | null | Promise;
+
+ /**
+ * When to validate the field.
+ * @defaultValue "onSubmit"
+ */
+ validationMode?: 'onSubmit' | 'onBlur' | 'onChange';
+
+ /**
+ * Whether the field is in an invalid state.
+ * @defaultValue false
+ */
+ invalid?: boolean;
+
+ /**
+ * Whether the field is disabled.
+ * @defaultValue false
+ */
+ disabled?: boolean;
+
+ /** Additional CSS class names. */
+ className?: string;
+}
+
+export interface FieldLabelProps {
+ /** Additional CSS class names. */
+ className?: string;
+}
+
+export interface FieldControlProps {
+ /** Additional CSS class names. */
+ className?: string;
+}
+
+export interface FieldErrorProps {
+ /**
+ * Match a specific ValidityState property (e.g., "valueMissing", "typeMismatch", "customError")
+ * or pass `true` to match any error.
+ */
+ match?: string | boolean;
+
+ /** Additional CSS class names. */
+ className?: string;
+}
+
+export interface FieldDescriptionProps {
+ /** Additional CSS class names. */
+ className?: string;
+}
diff --git a/apps/www/src/content/docs/components/fieldset/demo.ts b/apps/www/src/content/docs/components/fieldset/demo.ts
new file mode 100644
index 000000000..af6dfe7c5
--- /dev/null
+++ b/apps/www/src/content/docs/components/fieldset/demo.ts
@@ -0,0 +1,73 @@
+'use client';
+
+export const playground = {
+ type: 'code',
+ code: ``
+};
+
+export const basicDemo = {
+ type: 'code',
+ code: ``
+};
+
+export const subComponentDemo = {
+ type: 'code',
+ code: ``
+};
+
+export const disabledDemo = {
+ type: 'code',
+ code: ``
+};
+
+export const nestedDemo = {
+ type: 'code',
+ code: ``
+};
diff --git a/apps/www/src/content/docs/components/fieldset/index.mdx b/apps/www/src/content/docs/components/fieldset/index.mdx
new file mode 100644
index 000000000..9601683d8
--- /dev/null
+++ b/apps/www/src/content/docs/components/fieldset/index.mdx
@@ -0,0 +1,94 @@
+---
+title: Fieldset
+description: Groups related form fields with an accessible legend.
+source: packages/raystack/components/fieldset
+tag: new
+---
+
+import {
+ playground,
+ basicDemo,
+ subComponentDemo,
+ disabledDemo,
+ nestedDemo,
+} from "./demo.ts";
+
+
+
+## Anatomy
+
+Fieldset supports a **simple props API** and a **sub-component API**.
+
+### Simple API
+
+```tsx
+import { Fieldset, Field, InputField } from "@raystack/apsara";
+
+
+```
+
+### Sub-component API
+
+```tsx
+import { Fieldset, Field, InputField } from "@raystack/apsara";
+
+
+```
+
+## API Reference
+
+### Root
+
+Groups related fields with a shared legend. Renders a `