diff --git a/packages/checkbox-group/README.md b/packages/checkbox-group/README.md
index aca7da590..91bcb07ce 100644
--- a/packages/checkbox-group/README.md
+++ b/packages/checkbox-group/README.md
@@ -35,3 +35,23 @@ import '@lion/checkbox-group/lion-checkbox-group.js';
```
+
+### Model value
+
+The `modelValue` of a `lion-checkbox-group` is an array containing the `choiceValues` of the `lion-checkbox` elements that have been checked.
+
+Given the scientists example above, say that we were to select the first and last options (Archimedes & Marie Curie).
+
+Then the `modelValue` of the `lion-checkbox-group` will look as follows:
+
+```js
+const groupElement = [parent].querySelector('lion-checkbox-group');
+groupElement.modelValue;
+ => ["Archimedes", "Marie Curie"];
+```
+
+### The `name` attribute
+
+The `name` attribute of a `lion-checkbox-group` automatically gets assigned to its `lion-checkbox` children. You can also specify names for the `lion-checkbox` elements, but if this name is different from the name assigned to `lion-checkbox-group`, then an exception will be thrown.
+
+Our recommendation would be to set the `name` attribute only on the `lion-checkbox-group` and not on the `lion-checkbox` elements.
diff --git a/packages/checkbox-group/src/LionCheckboxGroup.js b/packages/checkbox-group/src/LionCheckboxGroup.js
index a388a03fc..e13ad3142 100644
--- a/packages/checkbox-group/src/LionCheckboxGroup.js
+++ b/packages/checkbox-group/src/LionCheckboxGroup.js
@@ -6,4 +6,11 @@ export class LionCheckboxGroup extends ChoiceGroupMixin(LionFieldset) {
super();
this.multipleChoice = true;
}
+
+ updated(changedProperties) {
+ super.updated(changedProperties);
+ if (changedProperties.has('name') && !String(this.name).match(/\[\]$/)) {
+ throw new Error('Names should end in "[]".');
+ }
+ }
}
diff --git a/packages/checkbox-group/test/lion-checkbox-group.test.js b/packages/checkbox-group/test/lion-checkbox-group.test.js
index 48b804e89..90e526e82 100644
--- a/packages/checkbox-group/test/lion-checkbox-group.test.js
+++ b/packages/checkbox-group/test/lion-checkbox-group.test.js
@@ -53,4 +53,21 @@ describe('', () => {
`);
await expect(el).to.be.accessible();
});
+
+ it("should throw exception if name doesn't end in []", async () => {
+ const el = await fixture(
+ html`
+
+ `,
+ );
+ el.name = 'woof';
+ let err;
+ try {
+ await el.updateComplete;
+ } catch (e) {
+ err = e;
+ }
+ expect(err).to.be.an.instanceof(Error);
+ expect(err.message).to.equal('Names should end in "[]".');
+ });
});
diff --git a/packages/form-system/stories/15-features-overview.stories.mdx b/packages/form-system/stories/15-features-overview.stories.mdx
index e1352a8e6..10fed8d19 100644
--- a/packages/form-system/stories/15-features-overview.stories.mdx
+++ b/packages/form-system/stories/15-features-overview.stories.mdx
@@ -1,5 +1,4 @@
-import { Story, Preview, Meta, html } from '@open-wc/demoing-storybook';
-import '@lion/checkbox-group/lion-checkbox-group.js';
+import { Story, Meta, html } from '@open-wc/demoing-storybook';
import '@lion/checkbox/lion-checkbox.js';
import '@lion/fieldset/lion-fieldset.js';
import '@lion/form/lion-form.js';
@@ -59,7 +58,7 @@ For usage and installation please see the appropriate packages.
diff --git a/packages/radio-group/README.md b/packages/radio-group/README.md
index 78cc2cd8e..e8bd615db 100644
--- a/packages/radio-group/README.md
+++ b/packages/radio-group/README.md
@@ -35,3 +35,23 @@ import '@lion/radio-group/lion-radio-group.js';
- Make sure that to use a name attribute as it is necessary for the [lion-form](../form)'s serialization result.
- If you have many options for a user to pick from, consider using [`lion-select`](../select) instead
+
+### Model value
+
+The `modelValue` of a `lion-radio-group` is string equal to the `choiceValue` of the `lion-radio` element that has been checked.
+
+Given the dinosaur example above, say that we were to select the last option (diplodocus).
+
+Then the `modelValue` of the `lion-radio-group` will look as follows:
+
+```js
+const groupElement = [parent].querySelector('lion-radio-group');
+groupElement.modelValue;
+ => "diplodocus";
+```
+
+### The `name` attribute
+
+The `name` attribute of a `lion-radio-group` automatically gets assigned to its `lion-radio` children. You can also specify names for the `lion-radio` elements, but if this name is different from the name assigned to `lion-radio-group`, then an exception will be thrown.
+
+Our recommendation would be to set the `name` attribute only on the `lion-radio-group` and not on the `lion-checkbox` elements.