From 4f653ddceac466302b587830089c4cd5ffd7eff6 Mon Sep 17 00:00:00 2001
From: Yuki Ishii <keryuuki0418@gmail.com>
Date: Thu, 2 Oct 2025 00:56:32 +0900
Subject: [PATCH] fix: update  error message to clarify usage with radio inputs
 (#16874)

* fix: update  error message to clarify usage with radio inputs

* show an extra bind checked error when a radio type

* typo

* replace 'group' binding with , drive-by fix some other messages

---------

Co-authored-by: Rich Harris <rich.harris@vercel.com>
---
 .changeset/slow-nails-push.md                      |  5 +++++
 documentation/docs/03-template-syntax/12-bind.md   |  4 +++-
 .../phases/2-analyze/visitors/BindDirective.js     | 12 ++++++++----
 .../dynamic-element-binding-invalid/_config.js     |  2 +-
 .../samples/binding-dimensions-svg/errors.json     |  2 +-
 .../samples/binding-input-checked/errors.json      |  2 +-
 .../binding-invalid-on-element-2/errors.json       |  2 +-
 .../samples/binding-invalid-on-element/errors.json |  2 +-
 .../binding-radio-input-checked/errors.json        | 14 ++++++++++++++
 .../binding-radio-input-checked/input.svelte       |  5 +++++
 10 files changed, 40 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/slow-nails-push.md
 create mode 100644 packages/svelte/tests/validator/samples/binding-radio-input-checked/errors.json
 create mode 100644 packages/svelte/tests/validator/samples/binding-radio-input-checked/input.svelte

diff --git a/.changeset/slow-nails-push.md b/.changeset/slow-nails-push.md
new file mode 100644
index 0000000000..8dedf35593
--- /dev/null
+++ b/.changeset/slow-nails-push.md
@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+fix: update `bind:checked` error message to clarify usage with radio inputs
diff --git a/documentation/docs/03-template-syntax/12-bind.md b/documentation/docs/03-template-syntax/12-bind.md
index de57815687..c21ed35919 100644
--- a/documentation/docs/03-template-syntax/12-bind.md
+++ b/documentation/docs/03-template-syntax/12-bind.md
@@ -95,7 +95,7 @@ Since 5.6.0, if an `<input>` has a `defaultValue` and is part of a form, it will
 
 ## `<input bind:checked>`
 
-Checkbox and radio inputs can be bound with `bind:checked`:
+Checkbox inputs can be bound with `bind:checked`:
 
 ```svelte
 <label>
@@ -117,6 +117,8 @@ Since 5.6.0, if an `<input>` has a `defaultChecked` attribute and is part of a f
 </form>
 ```
 
+> [!NOTE] Use `bind:group` for radio inputs instead of `bind:checked`.
+
 ## `<input bind:indeterminate>`
 
 Checkboxes can be in an [indeterminate](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/indeterminate) state, independently of whether they are checked or unchecked:
diff --git a/packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js b/packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js
index 9f02e7fa5a..995d251a2e 100644
--- a/packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js
+++ b/packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js
@@ -33,7 +33,7 @@ export function BindDirective(node, context) {
 				e.bind_invalid_target(
 					node,
 					node.name,
-					property.valid_elements.map((valid_element) => `<${valid_element}>`).join(', ')
+					property.valid_elements.map((valid_element) => `\`<${valid_element}>\``).join(', ')
 				);
 			}
 
@@ -67,11 +67,15 @@ export function BindDirective(node, context) {
 					}
 				} else {
 					if (node.name === 'checked' && type?.value[0].data !== 'checkbox') {
-						e.bind_invalid_target(node, node.name, '<input type="checkbox">');
+						e.bind_invalid_target(
+							node,
+							node.name,
+							`\`<input type="checkbox">\`${type?.value[0].data === 'radio' ? ` — for \`<input type="radio">\`, use \`bind:group\`` : ''}`
+						);
 					}
 
 					if (node.name === 'files' && type?.value[0].data !== 'file') {
-						e.bind_invalid_target(node, node.name, '<input type="file">');
+						e.bind_invalid_target(node, node.name, '`<input type="file">`');
 					}
 				}
 			}
@@ -94,7 +98,7 @@ export function BindDirective(node, context) {
 				e.bind_invalid_target(
 					node,
 					node.name,
-					`non-<svg> elements. Use 'clientWidth' for <svg> instead`
+					`non-\`<svg>\` elements. Use \`bind:clientWidth\` for \`<svg>\` instead`
 				);
 			}
 
diff --git a/packages/svelte/tests/compiler-errors/samples/dynamic-element-binding-invalid/_config.js b/packages/svelte/tests/compiler-errors/samples/dynamic-element-binding-invalid/_config.js
index 4bb3edc27b..25b0827765 100644
--- a/packages/svelte/tests/compiler-errors/samples/dynamic-element-binding-invalid/_config.js
+++ b/packages/svelte/tests/compiler-errors/samples/dynamic-element-binding-invalid/_config.js
@@ -3,6 +3,6 @@ import { test } from '../../test';
 export default test({
 	error: {
 		code: 'bind_invalid_target',
-		message: '`bind:value` can only be used with <input>, <textarea>, <select>'
+		message: '`bind:value` can only be used with `<input>`, `<textarea>`, `<select>`'
 	}
 });
diff --git a/packages/svelte/tests/validator/samples/binding-dimensions-svg/errors.json b/packages/svelte/tests/validator/samples/binding-dimensions-svg/errors.json
index 4d3819453c..61e6ca6355 100644
--- a/packages/svelte/tests/validator/samples/binding-dimensions-svg/errors.json
+++ b/packages/svelte/tests/validator/samples/binding-dimensions-svg/errors.json
@@ -1,7 +1,7 @@
 [
 	{
 		"code": "bind_invalid_target",
-		"message": "`bind:offsetWidth` can only be used with non-<svg> elements. Use 'clientWidth' for <svg> instead",
+		"message": "`bind:offsetWidth` can only be used with non-`<svg>` elements. Use `bind:clientWidth` for `<svg>` instead",
 		"start": {
 			"line": 5,
 			"column": 5
diff --git a/packages/svelte/tests/validator/samples/binding-input-checked/errors.json b/packages/svelte/tests/validator/samples/binding-input-checked/errors.json
index 574b25e06f..d7e8e48c95 100644
--- a/packages/svelte/tests/validator/samples/binding-input-checked/errors.json
+++ b/packages/svelte/tests/validator/samples/binding-input-checked/errors.json
@@ -1,7 +1,7 @@
 [
 	{
 		"code": "bind_invalid_target",
-		"message": "`bind:checked` can only be used with <input type=\"checkbox\">",
+		"message": "`bind:checked` can only be used with `<input type=\"checkbox\">`",
 		"start": {
 			"line": 5,
 			"column": 7
diff --git a/packages/svelte/tests/validator/samples/binding-invalid-on-element-2/errors.json b/packages/svelte/tests/validator/samples/binding-invalid-on-element-2/errors.json
index 92111a4ec2..19d0cd0ce1 100644
--- a/packages/svelte/tests/validator/samples/binding-invalid-on-element-2/errors.json
+++ b/packages/svelte/tests/validator/samples/binding-invalid-on-element-2/errors.json
@@ -1,7 +1,7 @@
 [
 	{
 		"code": "bind_invalid_target",
-		"message": "`bind:open` can only be used with <details>",
+		"message": "`bind:open` can only be used with `<details>`",
 		"start": {
 			"line": 5,
 			"column": 5
diff --git a/packages/svelte/tests/validator/samples/binding-invalid-on-element/errors.json b/packages/svelte/tests/validator/samples/binding-invalid-on-element/errors.json
index 6626afc1d0..781a8301ea 100644
--- a/packages/svelte/tests/validator/samples/binding-invalid-on-element/errors.json
+++ b/packages/svelte/tests/validator/samples/binding-invalid-on-element/errors.json
@@ -1,7 +1,7 @@
 [
 	{
 		"code": "bind_invalid_target",
-		"message": "`bind:value` can only be used with <input>, <textarea>, <select>",
+		"message": "`bind:value` can only be used with `<input>`, `<textarea>`, `<select>`",
 		"start": {
 			"line": 5,
 			"column": 5
diff --git a/packages/svelte/tests/validator/samples/binding-radio-input-checked/errors.json b/packages/svelte/tests/validator/samples/binding-radio-input-checked/errors.json
new file mode 100644
index 0000000000..beb46affc5
--- /dev/null
+++ b/packages/svelte/tests/validator/samples/binding-radio-input-checked/errors.json
@@ -0,0 +1,14 @@
+[
+	{
+		"code": "bind_invalid_target",
+		"message": "`bind:checked` can only be used with `<input type=\"checkbox\">` — for `<input type=\"radio\">`, use `bind:group`",
+		"start": {
+			"line": 5,
+			"column": 20
+		},
+		"end": {
+			"line": 5,
+			"column": 38
+		}
+	}
+]
diff --git a/packages/svelte/tests/validator/samples/binding-radio-input-checked/input.svelte b/packages/svelte/tests/validator/samples/binding-radio-input-checked/input.svelte
new file mode 100644
index 0000000000..67e7b77a3a
--- /dev/null
+++ b/packages/svelte/tests/validator/samples/binding-radio-input-checked/input.svelte
@@ -0,0 +1,5 @@
+<script>
+	let foo;
+</script>
+
+<input type="radio" bind:checked={foo}>
\ No newline at end of file