From c25fcf09573d4885d59dd23cc7ecca2a95b1ded4 Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Thu, 16 Oct 2025 10:27:20 -0700
Subject: [PATCH 1/2] fix(radio-button): allow standalone usage with `checked`
 prop

Fixes #1879
---
 src/RadioButton/RadioButton.svelte            | 11 ++++-
 .../RadioButtonStandalone.test.svelte         | 14 ++++++
 .../RadioButton/RadioButtonStandalone.test.ts | 48 +++++++++++++++++++
 3 files changed, 71 insertions(+), 2 deletions(-)
 create mode 100644 tests/RadioButton/RadioButtonStandalone.test.svelte
 create mode 100644 tests/RadioButton/RadioButtonStandalone.test.ts

diff --git a/src/RadioButton/RadioButton.svelte b/src/RadioButton/RadioButton.svelte
index 3ce9aa220b..dfcdf67a2c 100644
--- a/src/RadioButton/RadioButton.svelte
+++ b/src/RadioButton/RadioButton.svelte
@@ -53,7 +53,11 @@
     add({ id, checked, disabled, value });
   }
 
-  $: checked = $selectedValue === value;
+  // Only sync checked when inside RadioButtonGroup.
+  // This allows standalone `RadioButton` usage.
+  $: if (add) {
+    checked = $selectedValue === value;
+  }
 </script>
 
 <div
@@ -74,9 +78,12 @@
     on:focus
     on:blur
     on:change
-    on:change={() => {
+    on:change={(e) => {
       if (update) {
         update(value);
+      } else {
+        // Update `checked` for standalone `RadioButton` usage.
+        checked = e.currentTarget.checked;
       }
     }}
   />
diff --git a/tests/RadioButton/RadioButtonStandalone.test.svelte b/tests/RadioButton/RadioButtonStandalone.test.svelte
new file mode 100644
index 0000000000..f3a3c17fb6
--- /dev/null
+++ b/tests/RadioButton/RadioButtonStandalone.test.svelte
@@ -0,0 +1,14 @@
+<svelte:options accessors />
+
+<script lang="ts">
+  import { RadioButton } from "carbon-components-svelte";
+
+  export let checked = false;
+</script>
+
+<RadioButton
+  bind:checked
+  value="standalone"
+  labelText="Standalone Option"
+  name="standalone-radio"
+/>
diff --git a/tests/RadioButton/RadioButtonStandalone.test.ts b/tests/RadioButton/RadioButtonStandalone.test.ts
new file mode 100644
index 0000000000..fcf44fc536
--- /dev/null
+++ b/tests/RadioButton/RadioButtonStandalone.test.ts
@@ -0,0 +1,48 @@
+import { render, screen } from "@testing-library/svelte";
+import { user } from "../setup-tests";
+import RadioButtonStandalone from "./RadioButtonStandalone.test.svelte";
+
+describe("RadioButton (Standalone)", () => {
+  it("should allow checked prop to be updated programmatically when standalone", async () => {
+    const { component } = render(RadioButtonStandalone, {
+      props: { checked: false },
+    });
+
+    const input = screen.getByRole("radio") as HTMLInputElement;
+    expect(input).not.toBeChecked();
+
+    component.checked = true;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(input).toBeChecked();
+
+    component.checked = false;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(input).not.toBeChecked();
+  });
+
+  it("should bind checked state when user clicks standalone radio button", async () => {
+    const { component } = render(RadioButtonStandalone, {
+      props: { checked: false },
+    });
+
+    const input = screen.getByRole("radio");
+    expect(component.checked).toBe(false);
+
+    await user.click(input);
+
+    expect(component.checked).toBe(true);
+    expect(input).toBeChecked();
+  });
+
+  it("should support initial checked state for standalone radio button", () => {
+    const { component } = render(RadioButtonStandalone, {
+      props: { checked: true },
+    });
+
+    const input = screen.getByRole("radio");
+    expect(input).toBeChecked();
+    expect(component.checked).toBe(true);
+  });
+});

From 2cea055236781659266f20f291034d7e91f919fe Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Thu, 16 Oct 2025 10:39:52 -0700
Subject: [PATCH 2/2] docs(radio-button): add standalone example

---
 docs/src/pages/components/RadioButton.svx     |  8 ++++++
 .../RadioButton/RadioButtonStandalone.svelte  | 25 +++++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 docs/src/pages/framed/RadioButton/RadioButtonStandalone.svelte

diff --git a/docs/src/pages/components/RadioButton.svx b/docs/src/pages/components/RadioButton.svx
index 9b24026e33..fa04623159 100644
--- a/docs/src/pages/components/RadioButton.svx
+++ b/docs/src/pages/components/RadioButton.svx
@@ -11,6 +11,8 @@ components: ["RadioButtonGroup", "RadioButton", "RadioButtonSkeleton"]
 
 ## Default
 
+`RadioButton` is intended to be used within a `RadioButtonGroup`. See [Standalone usage](#standalone-usage) for individual usage.
+
 Create a group of radio buttons with a shared name and legend.
 
 <RadioButtonGroup legendText="Storage tier (disk)" name="plan" selected="standard">
@@ -19,6 +21,12 @@ Create a group of radio buttons with a shared name and legend.
   <RadioButton labelText="Pro (128 GB)" value="pro" />
 </RadioButtonGroup>
 
+## Standalone usage
+
+Use `RadioButton` individually with a bindable `checked` prop for simple use cases.
+
+<FileSource src="/framed/RadioButton/RadioButtonStandalone" />
+
 ## Hidden legend
 
 Visually hide the legend while maintaining accessibility.
diff --git a/docs/src/pages/framed/RadioButton/RadioButtonStandalone.svelte b/docs/src/pages/framed/RadioButton/RadioButtonStandalone.svelte
new file mode 100644
index 0000000000..97c7d2f15a
--- /dev/null
+++ b/docs/src/pages/framed/RadioButton/RadioButtonStandalone.svelte
@@ -0,0 +1,25 @@
+<script>
+  import { RadioButton, Button } from "carbon-components-svelte";
+
+  let agreedToTerms = false;
+</script>
+
+<div style:display="flex">
+  <RadioButton
+    bind:checked={agreedToTerms}
+    labelText="I agree to the terms and conditions"
+    name="terms"
+    value="agreed"
+  />
+</div>
+
+<div style:margin="var(--cds-layout-02) 0">
+  <Button
+    size="small"
+    kind="secondary"
+    disabled={!agreedToTerms}
+    on:click={() => (agreedToTerms = !agreedToTerms)}
+  >
+    Reset
+  </Button>
+</div>