From 6c224ead1347cc5738082dd12637814491faab41 Mon Sep 17 00:00:00 2001
From: Robert Snow <snowystinger@gmail.com>
Date: Wed, 30 Jul 2025 14:32:09 +1000
Subject: [PATCH 1/3] chore: s2 docs taggroup

---
 packages/@react-spectrum/s2/src/TagGroup.tsx | 110 ++++++++----
 packages/dev/s2-docs/pages/s2/TagGroup.mdx   | 170 +++++++++++++++++++
 2 files changed, 244 insertions(+), 36 deletions(-)
 create mode 100644 packages/dev/s2-docs/pages/s2/TagGroup.mdx

diff --git a/packages/@react-spectrum/s2/src/TagGroup.tsx b/packages/@react-spectrum/s2/src/TagGroup.tsx
index b1616897b39..353e2224bf1 100644
--- a/packages/@react-spectrum/s2/src/TagGroup.tsx
+++ b/packages/@react-spectrum/s2/src/TagGroup.tsx
@@ -323,7 +323,45 @@ function TagGroupInner<T>({
                       style={item.props.UNSAFE_style}
                       key={item.key}
                       className={item.props.className({size, allowsRemoving: Boolean(onRemove)})}>
-                      {item.props.children({size, allowsRemoving: Boolean(onRemove), isInCtx: true})}
+                      <div
+                        className={style({
+                          display: 'flex',
+                          minWidth: 0,
+                          alignItems: 'center',
+                          gap: 'text-to-visual',
+                          forcedColorAdjust: 'none',
+                          backgroundColor: 'transparent'
+                        })}>
+                        <Provider
+                          values={[
+                            [TextContext, {styles: style({order: 1, truncate: true})}],
+                            [IconContext, {
+                              render: centerBaseline({slot: 'icon', styles: style({order: 0})}),
+                              styles: style({size: fontRelative(20), marginStart: '--iconMargin', flexShrink: 0})
+                            }],
+                            [AvatarContext, {
+                              size: avatarSize[size],
+                              styles: style({order: 0})
+                            }],
+                            [ImageContext, {
+                              styles: style({
+                                size: fontRelative(20),
+                                flexShrink: 0,
+                                order: 0,
+                                aspectRatio: 'square',
+                                objectFit: 'contain',
+                                borderRadius: 'sm'
+                              })
+                            }]
+                          ]}>
+                          {item.props.children({size, allowsRemoving: Boolean(onRemove), isInCtx: true})}
+                        </Provider>
+                      </div>
+                      {Boolean(onRemove) && (
+                        <ClearButton
+                          slot="remove"
+                          size={size} />
+                      )}
                     </div>
                   );
                 })}
@@ -516,41 +554,41 @@ function TagWrapper({children, isDisabled, allowsRemoving, isInRealDOM, isEmphas
   return (
     <>
       {isInRealDOM && (
-      <div
-        className={style({
-          display: 'flex',
-          minWidth: 0,
-          alignItems: 'center',
-          gap: 'text-to-visual',
-          forcedColorAdjust: 'none',
-          backgroundColor: 'transparent'
-        })}>
-        <Provider
-          values={[
-            [TextContext, {styles: style({order: 1, truncate: true})}],
-            [IconContext, {
-              render: centerBaseline({slot: 'icon', styles: style({order: 0})}),
-              styles: style({size: fontRelative(20), marginStart: '--iconMargin', flexShrink: 0})
-            }],
-            [AvatarContext, {
-              size: avatarSize[size],
-              styles: style({order: 0})
-            }],
-            [ImageContext, {
-              styles: style({
-                size: fontRelative(20),
-                flexShrink: 0,
-                order: 0,
-                aspectRatio: 'square',
-                objectFit: 'contain',
-                borderRadius: 'sm'
-              })
-            }]
-          ]}>
-          {children}
-        </Provider>
-      </div>
-        )}
+        <div
+          className={style({
+            display: 'flex',
+            minWidth: 0,
+            alignItems: 'center',
+            gap: 'text-to-visual',
+            forcedColorAdjust: 'none',
+            backgroundColor: 'transparent'
+          })}>
+          <Provider
+            values={[
+              [TextContext, {styles: style({order: 1, truncate: true})}],
+              [IconContext, {
+                render: centerBaseline({slot: 'icon', styles: style({order: 0})}),
+                styles: style({size: fontRelative(20), marginStart: '--iconMargin', flexShrink: 0})
+              }],
+              [AvatarContext, {
+                size: avatarSize[size],
+                styles: style({order: 0})
+              }],
+              [ImageContext, {
+                styles: style({
+                  size: fontRelative(20),
+                  flexShrink: 0,
+                  order: 0,
+                  aspectRatio: 'square',
+                  objectFit: 'contain',
+                  borderRadius: 'sm'
+                })
+              }]
+            ]}>
+            {children}
+          </Provider>
+        </div>
+      )}
       {!isInRealDOM && children}
       {allowsRemoving && isInRealDOM && (
         <ClearButton
diff --git a/packages/dev/s2-docs/pages/s2/TagGroup.mdx b/packages/dev/s2-docs/pages/s2/TagGroup.mdx
new file mode 100644
index 00000000000..6cc59ce4fdf
--- /dev/null
+++ b/packages/dev/s2-docs/pages/s2/TagGroup.mdx
@@ -0,0 +1,170 @@
+import {Layout} from '../../src/Layout';
+export default Layout;
+
+import docs from 'docs:@react-spectrum/s2';
+
+# TagGroup
+
+<PageDescription>{docs.exports.TagGroup.description}</PageDescription>
+
+```tsx render docs={docs.exports.TagGroup} links={docs.links} props={['size', 'labelPosition', 'labelAlign', 'errorMessage', 'maxRows', 'selectionMode', 'description', 'label', 'disallowEmptySelection', 'selectionBehavior', 'isEmphasized', 'isInvalid', ]} initialProps={{label: 'Ice cream flavors', selectionMode: 'multiple', maxRows: 2}} type="s2"
+import {TagGroup, Tag} from '@react-spectrum/s2';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<TagGroup/* PROPS */ styles={style({width: 320})}>
+  <Tag>Chocolate</Tag>
+  <Tag>Mint</Tag>
+  <Tag>Strawberry</Tag>
+  <Tag>Vanilla</Tag>
+  <Tag>Chocolate Chip Cookie Dough</Tag>
+  <Tag>Rocky Road</Tag>
+  <Tag>Butter Pecan</Tag>
+  <Tag>Neapolitan</Tag>
+  <Tag>Salted Caramel</Tag>
+  <Tag>Mint Chocolate Chip</Tag>
+  <Tag>Tonight Dough</Tag>
+  <Tag>Lemon Cookie</Tag>
+  <Tag>Cookies and Cream</Tag>
+  <Tag>Phish Food</Tag>
+  <Tag>Peanut Butter Cup</Tag>
+  <Tag>Coffee</Tag>
+  <Tag>Pistachio</Tag>
+  <Tag>Cherry</Tag>
+</TagGroup>
+```
+
+## Content
+
+`TagGroup` follows the **Collection Components API**, accepting both static and dynamic collections.
+In this example, both the tags and the rows are provided to the table via a render function, enabling the user to hide and show columns and add additional rows.
+
+```tsx render type="s2"
+"use client";
+import {TagGroup, Tag} from '@react-spectrum/s2';
+import {useState} from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+///- begin collapse -///
+const initialTags = [
+  {name: 'Landscape', id: 'landscape'},
+  {name: 'Portrait', id: 'portrait'},
+  {name: 'Macro', id: 'macro'},
+  {name: 'Night', id: 'night'},
+  {name: 'Dual', id: 'dual'},
+  {name: 'Golden Hour', id: 'golden-hour'},
+  {name: 'Animal', id: 'animal'},
+  {name: 'Plant', id: 'plant'},
+  {name: 'Travel', id: 'travel'}
+];
+///- end collapse -///
+
+function PhotoCategories() {
+  let [tags, setTags] = useState(initialTags);
+
+  return (
+    <TagGroup label="Photo categories" selectionMode="multiple" maxRows={2} items={tags} styles={style({width: 320})}>
+      {tag => <Tag>{tag.name}</Tag>}
+    </TagGroup>
+  );
+}
+```
+
+### Removing tags
+
+To show a remove button on the tag, you can use the `onRemove` prop.
+
+```tsx render type="s2"
+"use client";
+import {Button, TagGroup, Tag, TextField} from '@react-spectrum/s2';
+import {useState} from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+///- begin collapse -///
+const initialTags = [
+  {name: 'Landscape', id: 'landscape'},
+  {name: 'Portrait', id: 'portrait'},
+  {name: 'Macro', id: 'macro'},
+  {name: 'Night', id: 'night'},
+  {name: 'Dual', id: 'dual'},
+  {name: 'Golden Hour', id: 'golden-hour'},
+  {name: 'Animal', id: 'animal'},
+  {name: 'Plant', id: 'plant'},
+  {name: 'Travel', id: 'travel'}
+];
+///- end collapse -///
+
+function PhotoCategories() {
+  let [tags, setTags] = useState(initialTags);
+  let [newTag, setNewTag] = useState('');
+
+  return (
+    <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
+      <div style={{display: 'flex', gap: 8}}>
+        <TextField label="Add a category" value={newTag} onChange={setNewTag} />
+        <Button
+          styles={style({alignSelf: 'end'})}
+          onPress={() => {
+            setTags([...tags, {name: newTag, id: newTag}]);
+            setNewTag('');
+          }}>Add</Button>
+      </div>
+      <TagGroup
+        onRemove={keys => setTags((prev) => prev.filter(t => !keys.has(t.id)))}
+        label="Photo categories"
+        selectionMode="multiple"
+        maxRows={2}
+        items={tags}
+        styles={style({width: 320})}
+        isEmphasized
+      >
+        {tag => <Tag>{tag.name}</Tag>}
+      </TagGroup>
+    </div>
+  );
+}
+```
+
+### Links
+
+Use the `href` prop on a `<Tag>` to create a link. See the **client side routing guide** to learn how to integrate with your framework. Link interactions vary depending on the selection behavior.  See the [selection guide](selection.html) for more details.
+
+```tsx render type="s2"
+"use client";
+import {TagGroup, Tag} from '@react-spectrum/s2';
+import {useState} from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<TagGroup label="Types of photos" maxRows={2} styles={style({width: 320})}>
+  <Tag href="https://en.wikipedia.org/wiki/Landscape_photography">Landscape</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Portrait_photography">Portrait</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Macro_photography">Macro</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Night_photography">Night</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Dualphotography">Dual</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Golden_hour_(photography)">Golden Hour</Tag>
+</TagGroup>
+```
+
+### Empty state
+
+If the collection is empty, the `renderEmptyState` prop will be called.
+
+```tsx render type="s2"
+"use client";
+import {TagGroup, Tag} from '@react-spectrum/s2';
+import {useState} from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<TagGroup renderEmptyState={() => 'No categories'} label="Photo categories" styles={style({width: 320})}>
+  {[]}
+</TagGroup>
+```
+
+## Props
+
+### TagGroup
+
+<PropTable component={docs.exports.TagGroup} links={docs.links} />
+
+### Tag
+
+<PropTable component={docs.exports.Tag} links={docs.links} />

From d4e7d437ca28f78aa5515eda3ad1d494a9d662ff Mon Sep 17 00:00:00 2001
From: Robert Snow <snowystinger@gmail.com>
Date: Wed, 30 Jul 2025 17:13:37 +1000
Subject: [PATCH 2/3] make examples better and add group actions

---
 packages/dev/s2-docs/pages/s2/TagGroup.mdx | 78 +++++++++++++++++-----
 1 file changed, 61 insertions(+), 17 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/TagGroup.mdx b/packages/dev/s2-docs/pages/s2/TagGroup.mdx
index 6cc59ce4fdf..f0e86a15e04 100644
--- a/packages/dev/s2-docs/pages/s2/TagGroup.mdx
+++ b/packages/dev/s2-docs/pages/s2/TagGroup.mdx
@@ -40,21 +40,23 @@ In this example, both the tags and the rows are provided to the table via a rend
 
 ```tsx render type="s2"
 "use client";
-import {TagGroup, Tag} from '@react-spectrum/s2';
+import {TagGroup, Tag, Text} from '@react-spectrum/s2';
 import {useState} from 'react';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+import OrientationLandscape from '@react-spectrum/s2/icons/OrientationLandscape';
+import OrientationPortrait from '@react-spectrum/s2/icons/OrientationPortrait';
+import Star from '@react-spectrum/s2/icons/Star';
+import CameraProperties from '@react-spectrum/s2/icons/CameraProperties';
+import Lighten from '@react-spectrum/s2/icons/Lighten';
+import Cloud from '@react-spectrum/s2/icons/Cloud';
 
 ///- begin collapse -///
 const initialTags = [
-  {name: 'Landscape', id: 'landscape'},
-  {name: 'Portrait', id: 'portrait'},
-  {name: 'Macro', id: 'macro'},
-  {name: 'Night', id: 'night'},
-  {name: 'Dual', id: 'dual'},
-  {name: 'Golden Hour', id: 'golden-hour'},
-  {name: 'Animal', id: 'animal'},
-  {name: 'Plant', id: 'plant'},
-  {name: 'Travel', id: 'travel'}
+  {name: 'Landscape', id: 'landscape', Icon: OrientationLandscape},
+  {name: 'Portrait', id: 'portrait', Icon: OrientationPortrait},
+  {name: 'Night', id: 'night', Icon: Star},
+  {name: 'Dual', id: 'dual', Icon: CameraProperties},
+  {name: 'Golden Hour', id: 'golden-hour', Icon: Lighten}
 ];
 ///- end collapse -///
 
@@ -63,7 +65,7 @@ function PhotoCategories() {
 
   return (
     <TagGroup label="Photo categories" selectionMode="multiple" maxRows={2} items={tags} styles={style({width: 320})}>
-      {tag => <Tag>{tag.name}</Tag>}
+      {({name, Icon}) => <Tag><Icon /><Text>{name}</Text></Tag>}
     </TagGroup>
   );
 }
@@ -135,12 +137,12 @@ import {useState} from 'react';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
 <TagGroup label="Types of photos" maxRows={2} styles={style({width: 320})}>
-  <Tag href="https://en.wikipedia.org/wiki/Landscape_photography">Landscape</Tag>
-  <Tag href="https://en.wikipedia.org/wiki/Portrait_photography">Portrait</Tag>
-  <Tag href="https://en.wikipedia.org/wiki/Macro_photography">Macro</Tag>
-  <Tag href="https://en.wikipedia.org/wiki/Night_photography">Night</Tag>
-  <Tag href="https://en.wikipedia.org/wiki/Dualphotography">Dual</Tag>
-  <Tag href="https://en.wikipedia.org/wiki/Golden_hour_(photography)">Golden Hour</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Landscape_photography" target="_blank">Landscape</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Portrait_photography" target="_blank">Portrait</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Macro_photography" target="_blank">Macro</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Night_photography" target="_blank">Night</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Dualphotography" target="_blank">Dual</Tag>
+  <Tag href="https://en.wikipedia.org/wiki/Golden_hour_(photography)" target="_blank">Golden Hour</Tag>
 </TagGroup>
 ```
 
@@ -159,6 +161,48 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 </TagGroup>
 ```
 
+### Group actions
+
+You can add a group action to the tag group by providing a `groupActionLabel` and `onGroupAction` prop.
+
+```tsx render type="s2"
+"use client";
+import {TagGroup, Tag} from '@react-spectrum/s2';
+import {useState} from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+///- begin collapse -///
+const initialTags = [
+  {name: 'Landscape', id: 'landscape'},
+  {name: 'Portrait', id: 'portrait'},
+  {name: 'Macro', id: 'macro'},
+  {name: 'Night', id: 'night'},
+  {name: 'Dual', id: 'dual'},
+  {name: 'Golden Hour', id: 'golden-hour'},
+];
+///- end collapse -///
+
+function CopyAll() {
+  let [tags, setTags] = useState(initialTags);
+  let [selectedTags, setSelectedTags] = useState<string[]>([]);
+  return (
+    <TagGroup
+      groupActionLabel="Alert"
+      onGroupAction={() => {
+        alert([...selectedTags].map(tag => tags.find(t => t.id === tag)?.name).join(', '));
+      }}
+      selectionMode="multiple"
+      selectedKeys={selectedTags}
+      onSelectionChange={setSelectedTags}
+      items={tags}
+      label="Photo categories"
+      styles={style({width: 320})}>
+      {tag => <Tag>{tag.name}</Tag>}
+    </TagGroup>
+  )
+}
+```
+
 ## Props
 
 ### TagGroup

From 66d992226af8cb8c4378651f14aeb46e7153b9bd Mon Sep 17 00:00:00 2001
From: Robert Snow <snowystinger@gmail.com>
Date: Fri, 1 Aug 2025 12:48:25 +1000
Subject: [PATCH 3/3] cleanup examples

---
 .../dev/s2-docs/pages/react-aria/TagGroup.mdx |   5 +-
 packages/dev/s2-docs/pages/s2/TagGroup.mdx    | 130 +++++++++---------
 2 files changed, 70 insertions(+), 65 deletions(-)

diff --git a/packages/dev/s2-docs/pages/react-aria/TagGroup.mdx b/packages/dev/s2-docs/pages/react-aria/TagGroup.mdx
index 5e877c90ac7..fed5c973b9d 100644
--- a/packages/dev/s2-docs/pages/react-aria/TagGroup.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/TagGroup.mdx
@@ -65,7 +65,9 @@ import {TagGroup, TagList, Tag, Label, Button, Text} from 'react-aria-components
 
 ## Content
 
-`TagGroup` follows the **Collection Components API**, accepting both static and dynamic collections. This example shows a dynamic collection, passing a list of objects to the `items` prop, and a function to render the children. Items can be removed via the `onRemove` event.
+`TagGroup` follows the **Collection Components API**, accepting both static and dynamic collections.
+This example shows a dynamic collection, passing a list of objects to the `items` prop, and a function to render the children.
+Items can be removed via the `onRemove` event.
 
 ```tsx render
 "use client";
@@ -91,7 +93,6 @@ function Example() {
       {/*- end highlight -*/}
       {(item) => <Tag>{item.name}</Tag>}
     </TagGroup>
-    /*- end highlight -*/
   );
 }
 ```
diff --git a/packages/dev/s2-docs/pages/s2/TagGroup.mdx b/packages/dev/s2-docs/pages/s2/TagGroup.mdx
index f0e86a15e04..c60e068740f 100644
--- a/packages/dev/s2-docs/pages/s2/TagGroup.mdx
+++ b/packages/dev/s2-docs/pages/s2/TagGroup.mdx
@@ -7,7 +7,7 @@ import docs from 'docs:@react-spectrum/s2';
 
 <PageDescription>{docs.exports.TagGroup.description}</PageDescription>
 
-```tsx render docs={docs.exports.TagGroup} links={docs.links} props={['size', 'labelPosition', 'labelAlign', 'errorMessage', 'maxRows', 'selectionMode', 'description', 'label', 'disallowEmptySelection', 'selectionBehavior', 'isEmphasized', 'isInvalid', ]} initialProps={{label: 'Ice cream flavors', selectionMode: 'multiple', maxRows: 2}} type="s2"
+```tsx render docs={docs.exports.TagGroup} links={docs.links} props={['size', 'labelPosition', 'labelAlign', 'errorMessage', 'maxRows', 'description', 'label', 'isEmphasized', 'isInvalid']} initialProps={{label: 'Ice cream flavors', selectionMode: 'multiple', maxRows: 2}} type="s2"
 import {TagGroup, Tag} from '@react-spectrum/s2';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
@@ -36,90 +36,52 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 ## Content
 
 `TagGroup` follows the **Collection Components API**, accepting both static and dynamic collections.
-In this example, both the tags and the rows are provided to the table via a render function, enabling the user to hide and show columns and add additional rows.
+This example shows a dynamic collection, passing a list of objects to the `items` prop, and a function to render the children.
+Items can be removed via the `onRemove` event.
 
 ```tsx render type="s2"
 "use client";
-import {TagGroup, Tag, Text} from '@react-spectrum/s2';
+import {TagGroup, Tag, TextField, Button} from '@react-spectrum/s2';
+import {useListData} from 'react-stately';
 import {useState} from 'react';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
-import OrientationLandscape from '@react-spectrum/s2/icons/OrientationLandscape';
-import OrientationPortrait from '@react-spectrum/s2/icons/OrientationPortrait';
-import Star from '@react-spectrum/s2/icons/Star';
-import CameraProperties from '@react-spectrum/s2/icons/CameraProperties';
-import Lighten from '@react-spectrum/s2/icons/Lighten';
-import Cloud from '@react-spectrum/s2/icons/Cloud';
 
 ///- begin collapse -///
-const initialTags = [
-  {name: 'Landscape', id: 'landscape', Icon: OrientationLandscape},
-  {name: 'Portrait', id: 'portrait', Icon: OrientationPortrait},
-  {name: 'Night', id: 'night', Icon: Star},
-  {name: 'Dual', id: 'dual', Icon: CameraProperties},
-  {name: 'Golden Hour', id: 'golden-hour', Icon: Lighten}
-];
-///- end collapse -///
-
-function PhotoCategories() {
-  let [tags, setTags] = useState(initialTags);
-
-  return (
-    <TagGroup label="Photo categories" selectionMode="multiple" maxRows={2} items={tags} styles={style({width: 320})}>
-      {({name, Icon}) => <Tag><Icon /><Text>{name}</Text></Tag>}
-    </TagGroup>
-  );
-}
-```
-
-### Removing tags
-
-To show a remove button on the tag, you can use the `onRemove` prop.
-
-```tsx render type="s2"
-"use client";
-import {Button, TagGroup, Tag, TextField} from '@react-spectrum/s2';
-import {useState} from 'react';
-import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
-
-///- begin collapse -///
-const initialTags = [
+const initialItems = [
   {name: 'Landscape', id: 'landscape'},
   {name: 'Portrait', id: 'portrait'},
-  {name: 'Macro', id: 'macro'},
   {name: 'Night', id: 'night'},
   {name: 'Dual', id: 'dual'},
-  {name: 'Golden Hour', id: 'golden-hour'},
-  {name: 'Animal', id: 'animal'},
-  {name: 'Plant', id: 'plant'},
-  {name: 'Travel', id: 'travel'}
+  {name: 'Golden Hour', id: 'golden-hour'}
 ];
 ///- end collapse -///
 
 function PhotoCategories() {
-  let [tags, setTags] = useState(initialTags);
+  let list = useListData({initialItems});
   let [newTag, setNewTag] = useState('');
 
   return (
-    <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
-      <div style={{display: 'flex', gap: 8}}>
+    <div className={style({display: 'flex', flexDirection: 'column', gap: 8})}>
+      {/*- begin collapse -*/}
+      <div className={style({display: 'flex', gap: 8})}>
         <TextField label="Add a category" value={newTag} onChange={setNewTag} />
         <Button
           styles={style({alignSelf: 'end'})}
           onPress={() => {
-            setTags([...tags, {name: newTag, id: newTag}]);
+            list.append({name: newTag, id: newTag});
             setNewTag('');
           }}>Add</Button>
       </div>
+      {/*- end collapse -*/}
       <TagGroup
-        onRemove={keys => setTags((prev) => prev.filter(t => !keys.has(t.id)))}
         label="Photo categories"
-        selectionMode="multiple"
-        maxRows={2}
-        items={tags}
         styles={style({width: 320})}
-        isEmphasized
+        ///- begin highlight -///
+        items={list.items}
+        onRemove={(keys) => list.remove(...keys)}
+        ///- end highlight -///
       >
-        {tag => <Tag>{tag.name}</Tag>}
+        {(item) => <Tag>{item.name}</Tag>}
       </TagGroup>
     </div>
   );
@@ -133,11 +95,12 @@ Use the `href` prop on a `<Tag>` to create a link. See the **client side routing
 ```tsx render type="s2"
 "use client";
 import {TagGroup, Tag} from '@react-spectrum/s2';
-import {useState} from 'react';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
 <TagGroup label="Types of photos" maxRows={2} styles={style({width: 320})}>
+  {/*- begin highlight -*/}
   <Tag href="https://en.wikipedia.org/wiki/Landscape_photography" target="_blank">Landscape</Tag>
+  {/*- end highlight -*/}
   <Tag href="https://en.wikipedia.org/wiki/Portrait_photography" target="_blank">Portrait</Tag>
   <Tag href="https://en.wikipedia.org/wiki/Macro_photography" target="_blank">Macro</Tag>
   <Tag href="https://en.wikipedia.org/wiki/Night_photography" target="_blank">Night</Tag>
@@ -152,15 +115,53 @@ If the collection is empty, the `renderEmptyState` prop will be called.
 
 ```tsx render type="s2"
 "use client";
+import {TagGroup} from '@react-spectrum/s2';
+
+<TagGroup
+  label="Photo categories"
+  renderEmptyState={() => 'No categories'}>
+  {[]}
+</TagGroup>
+```
+
+### Selection
+
+Use the `selectionMode` prop to enable single or multiple selection.
+The selected items can be controlled via the `selectedKeys` prop, matching the `id` prop of the items.
+Items can be disabled with the `isDisabled` prop. See the [selection guide](selection.html) for more details.
+
+```tsx render docs={docs.exports.TagGroup} links={docs.links} props={['selectionMode', 'selectionBehavior', 'disallowEmptySelection']} initialProps={{selectionMode: 'multiple'}} wide
+"use client";
 import {TagGroup, Tag} from '@react-spectrum/s2';
 import {useState} from 'react';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
-<TagGroup renderEmptyState={() => 'No categories'} label="Photo categories" styles={style({width: 320})}>
-  {[]}
-</TagGroup>
+function Example(props) {
+  let [selected, setSelected] = useState<Selection>(new Set());
+
+  return (
+    <div>
+      <TagGroup
+        {...props}
+        label="Amenities"
+        ///- begin highlight -///
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+        ///- end highlight -///
+      >
+        <Tag id="laundry">Laundry</Tag>
+        <Tag id="fitness">Fitness center</Tag>
+        <Tag id="parking" isDisabled>Parking</Tag>
+        <Tag id="pool">Swimming pool</Tag>
+        <Tag id="breakfast">Breakfast</Tag>
+      </TagGroup>
+      <p>Current selection: {selected === 'all' ? 'all' : [...selected].join(', ')}</p>
+    </div>
+  );
+}
 ```
 
+
 ### Group actions
 
 You can add a group action to the tag group by providing a `groupActionLabel` and `onGroupAction` prop.
@@ -182,15 +183,18 @@ const initialTags = [
 ];
 ///- end collapse -///
 
-function CopyAll() {
+function CopyAll(props) {
   let [tags, setTags] = useState(initialTags);
   let [selectedTags, setSelectedTags] = useState<string[]>([]);
   return (
     <TagGroup
+      {...props}
+      ///- begin highlight -///
       groupActionLabel="Alert"
       onGroupAction={() => {
         alert([...selectedTags].map(tag => tags.find(t => t.id === tag)?.name).join(', '));
       }}
+      ///- end highlight -///
       selectionMode="multiple"
       selectedKeys={selectedTags}
       onSelectionChange={setSelectedTags}
@@ -207,8 +211,8 @@ function CopyAll() {
 
 ### TagGroup
 
-<PropTable component={docs.exports.TagGroup} links={docs.links} />
+<PropTable component={docs.exports.TagGroup} links={docs.links} showDescription />
 
 ### Tag
 
-<PropTable component={docs.exports.Tag} links={docs.links} />
+<PropTable component={docs.exports.Tag} links={docs.links} showDescription />