cloudscape-design · cansuaa · Nov 19, 2025 · Aug 29, 2025 · Sep 12, 2025 · Sep 12, 2025
@@ -42,6 +42,35 @@ const getItems = (firstChecked: boolean, secondChecked: boolean, thirdChecked: b
       id: 'id5',
       text: 'Option without checkbox',
     },
+    {
+      id: 'id6',
+      text: 'Disabled option with secondaryText',
+      secondaryText: 'This is a secondary text',
+      disabled: true,
+    },
+    {
+      id: 'id7',
+      text: 'Option with icon and secondaryText',
+      iconName: 'gen-ai',
+      secondaryText: 'This is a secondary text',
+    },
+    {
+      id: 'id8',
+      text: 'Option with checkbox, icon, and secondaryText',
+      iconName: 'gen-ai',
+      secondaryText: 'This is a secondary text',
+      checked: thirdChecked,
+      itemType: 'checkbox',
+    },
+    {
+      id: 'id8',
+      text: 'Option with checkbox, icon, labelTag, and secondaryText',
+      iconName: 'gen-ai',
+      secondaryText: 'This is a secondary text',
+      checked: thirdChecked,
+      itemType: 'checkbox',
+      labelTag: 'Ctrl + L',
+    },
   ];
   return items;
 };

@@ -7,8 +7,13 @@ import { ButtonDropdown, ButtonDropdownProps } from '~components';
 import ScreenshotArea from '../utils/screenshot-area';
 
 const actionsItems: ButtonDropdownProps.Items = [
-  { id: 'connect', text: 'Connect', disabledReason: 'Instance must be running.', disabled: true },
-  { id: 'details', text: 'View details', disabledReason: 'A single instance needs to be selected.', disabled: true },
+  { id: 'connect', text: 'Connect', disabledReason: 'Instance must be running.', disabled: true, labelTag: 'Disabled' },
+  {
+    id: 'details',
+    text: 'View details',
+    disabledReason: 'A single instance needs to be selected.',
+    disabled: true,
+  },
   {
     id: 'manage-state',
     text: 'Manage instance state',
@@ -22,6 +27,7 @@ const actionsItems: ButtonDropdownProps.Items = [
       {
         id: 'auto-scaling',
         text: 'Attach to Auto Scaling Group',
+        secondaryText: 'Manage the Instance to Auto Scaling Group',
         disabledReason: 'Instance must be running and not already be attached to an Auto Scaling Group.',
         disabled: true,
       },
@@ -38,6 +44,7 @@ const actionsItems: ButtonDropdownProps.Items = [
         text: 'Change shutdown behavior',
         disabledReason: "Instance can't be a spot instance.",
         disabled: true,
+        labelTag: 'Ctrl + D',
       },
     ],
   },

@@ -10,19 +10,32 @@ const dropdownItems = [
   {
     text: 'enabled category',
     items: [
-      { id: 'c1long1', text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown' },
-      { id: 'c1_disabled_item', text: 'disabled item', disabled: true },
+      {
+        id: 'c1long1',
+        text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown',
+        secondaryText: 'Very long option',
+      },
+      { id: 'c1_disabled_item', text: 'disabled item', disabled: true, secondaryText: 'Disabled option' },
       { id: 'c1_enabled_item', text: 'option2' },
-      { id: 'c1long2', text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown', disabled: true },
-      { id: 'c1i3', text: 'option3' },
-      { id: 'c1i4', text: 'option4' },
+      {
+        id: 'c1long2',
+        text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown',
+        disabled: true,
+        secondaryText: 'Very long option',
+      },
+      { id: 'c1i3', text: 'option3', secondaryText: 'option 3' },
+      { id: 'c1i4', text: 'option4', secondaryText: 'option 4' },
     ],
   },
   {
     text: 'disabled category',
     disabled: true,
     items: [
-      { id: 'dci1', text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown' },
+      {
+        id: 'dci1',
+        text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown',
+        secondaryText: 'Very long option',
+      },
       { id: 'item_in_disabled_category', text: 'option4' },
       { id: 'dci5', text: 'option5' },
     ],
@@ -35,11 +48,13 @@ const dropdownItems = [
     id: 'individual_disabled_item',
     text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown',
     disabled: true,
+    labelTag: 'Disabled',
   },
   {
     id: 'plain_href',
     text: 'option6',
     href: '#',
+    labelTag: 'Link',
   },
   {
     id: 'plain_href_prevented',

@@ -22,11 +22,13 @@ export const items: ButtonDropdownProps['items'] = [
     items: [...Array(50)].map((_, index) => ({
       id: 'category2Subitem' + index,
       text: 'Cat 2 Sub item ' + index,
+      secondaryText: `Option ${index}`,
     })),
   },
   ...[...Array(10)].map((_, index) => ({
     id: 'item' + index,
     text: 'Item ' + index,
+    secondaryText: `Option ${index}`,
   })),
   {
     id: 'category3',
@@ -45,6 +47,7 @@ export const items: ButtonDropdownProps['items'] = [
   {
     id: 'item10',
     text: 'Item 10',
+    secondaryText: 'This is the last option',
   },
 ];
 

@@ -19,6 +19,7 @@ export const items: ButtonDropdownProps['items'] = [
     items: [...Array(2)].map((_, index) => ({
       id: 'category1Subitem' + index,
       text: 'Sub item ' + index,
+      secondaryText: `Option ${index}`,
     })),
   },
   {
@@ -35,6 +36,7 @@ export const items: ButtonDropdownProps['items'] = [
     id: 'item1',
     text: 'Item 1',
     iconName: 'settings',
+    secondaryText: 'Option 1',
   },
   {
     id: 'category3',
@@ -50,6 +52,7 @@ export const items: ButtonDropdownProps['items'] = [
     items: [...Array(2)].map((_, index) => ({
       id: 'category3Subitem' + index,
       text: 'Sub item ' + index,
+      labelTag: ' Number ' + index,
     })),
   },
 ];

@@ -50,6 +50,33 @@ const permutations = createPermutations<ItemProps>([
     onItemActivate: [() => {}],
     highlightItem: [() => {}],
   },
+
+  // With secondaryText
+  {
+    item: [
+      { id: '1', text: 'Option', secondaryText: 'This is the first option' },
+      { id: '2', text: 'Option 2', secondaryText: 'This is the second option' },
+    ],
+    disabled: [false, true],
+    highlighted: [false, true],
+    hasCategoryHeader: [false],
+    showDivider: [false],
+    onItemActivate: [() => {}],
+    highlightItem: [() => {}],
+  },
+  // With labelTag
+  {
+    item: [
+      { id: '1', text: 'Option', labelTag: 'This is a label tag' },
+      { id: '2', text: 'Option 2', secondaryText: 'This is the second option', labelTag: 'This is a label tag' },
+    ],
+    disabled: [false, true],
+    highlighted: [false, true],
+    hasCategoryHeader: [false],
+    showDivider: [false],
+    onItemActivate: [() => {}],
+    highlightItem: [() => {}],
+  },
   // With icons
   {
     item: [

@@ -22,6 +22,7 @@ export default function ButtonDropdownPage() {
               {
                 text: 'Launch instance from template',
                 id: 'launch-instance-from-template',
+                secondaryText: 'Use the existing templates',
               },
             ]}
             onItemClick={() => setClickedButton('Launch instance from template')}

@@ -17,6 +17,7 @@ const launchInstanceItem = {
 const launchInstanceFromTemplateItem = {
   text: 'Launch instance from template',
   iconName: 'file',
+  secondaryText: 'Use an existing template',
 } as const;
 
 const viewInstancesItem = {

@@ -40,6 +40,22 @@ const items: ButtonDropdownProps['items'] = [
     text: 'Option 6',
     disabled: true,
   },
+  {
+    id: 'id7',
+    text: 'Option 7',
+    secondaryText: 'This is option 7',
+  },
+  {
+    id: 'id8',
+    text: 'Option 8',
+    labelTag: 'Ctrl + 8',
+  },
+  {
+    id: 'id9',
+    text: 'Option 9',
+    secondaryText: 'This is option 9',
+    labelTag: 'Ctrl + 9',
+  },
 ];
 
 const withNestedOptions: ButtonDropdownProps['items'] = [
@@ -49,10 +65,14 @@ const withNestedOptions: ButtonDropdownProps['items'] = [
       {
         id: '1',
         text: 'Destroy',
+        secondaryText: 'This is the Destroy option',
+        labelTag: 'Ctrl + D',
       },
       {
         id: '2',
         text: 'Restart',
+        secondaryText: 'This is the Restart option',
+        labelTag: 'Ctrl + R',
       },
     ],
   },
@@ -77,10 +97,13 @@ const withExpandedGroups: ButtonDropdownProps['items'] = [
   {
     id: 'connect',
     text: 'Connect',
+    secondaryText: 'This is the Connect option',
+    labelTag: 'Ctrl + C',
   },
   {
     id: 'password',
     text: 'Get password',
+    secondaryText: 'This is the Get password option',
   },
   {
     id: 'states',
@@ -103,15 +126,20 @@ const withExpandedGroups: ButtonDropdownProps['items'] = [
       {
         id: 'reboot',
         text: 'Reboot',
+        secondaryText: 'This is the Reboot Option',
+        labelTag: 'Ctrl + B',
         disabled: true,
       },
       {
         id: 'terminate',
         text: 'Terminate',
+        secondaryText: 'This is the Terminate Option',
       },
       {
         id: 'external',
         text: 'Root Page',
+        secondaryText: '',
+        labelTag: 'Ctrl + P',
         external: true,
         href: '/#/light/',
       },

@@ -11,10 +11,13 @@ const dropdownItems = [
     id: 'id7',
     text: 'option5',
     disabled: true,
+    secondaryText: 'This is a disabled option',
+    labelTag: 'Disabled',
   },
   {
     id: 'id8',
     text: 'VeryLongOptionTextValueHereToTestTheCaseWithThisDropdown',
+    secondaryText: 'This is the option with a long description, This is the option with a long description',
   },
   { id: 'id9', text: 'option6' },
 ];

@@ -14,6 +14,9 @@ const dropdownItems = [
       {
         id: 'id0',
         text: 'a very long text that may overflow horizontally as in this example that is unnecessarily longer just to exemplify a long text',
+        secondaryText:
+          'A very long text that may overflow horizontally as in this example that is unnecessarily longer just to exemplify a long text',
+        labelTag: 'Label',
       },
       { id: 'id1', text: 'option1', disabled: true },
       { id: 'id2', text: 'option2' },
@@ -28,6 +31,7 @@ const dropdownItems = [
       {
         id: 'id5',
         text: 'AVeryLongWordThatMayOverflowHorizontallyAsInThisExampleThatIsUnnecessarilyLongerJustToExemplifyALongWord',
+        labelTag: 'Label',
       },
       { id: 'id6', text: 'option4' },
     ],
@@ -44,6 +48,7 @@ const dropdownItems = [
   {
     id: 'id9',
     text: 'option9',
+    secondaryText: 'This is a disabled option',
     disabled: true,
   },
   {

@@ -5632,7 +5632,7 @@ The following properties are supported across all types:
 - \`lang\` (string) - (Optional) The language of the item, provided as a BCP 47 language tag.
 - \`disabled\` (boolean) - whether the item is disabled. Disabled items are not clickable, but they can be highlighted with the keyboard to make them accessible.
 - \`disabledReason\` (string) - (Optional) Displays text near the \`text\` property when item is disabled. Use to provide additional context.
-- \`description\` (string) - additional data that will be passed to a \`data-description\` attribute.
+- \`description\` (string) - additional data that will be passed to a \`data-description\` attribute. **Deprecated**, has no effect.
 - \`ariaLabel\` (string) - (Optional) - ARIA label of the item element.
 
 ### action
@@ -5645,6 +5645,8 @@ The following properties are supported across all types:
 - \`iconAlt\` (string) - (Optional) Specifies alternate text for the icon when using \`iconUrl\`.
 - \`iconUrl\` (string) - (Optional) Specifies the URL of a custom icon.
 - \`iconSvg\` (ReactNode) - (Optional) Custom SVG icon. Equivalent to the \`svg\` slot of the [icon component](/components/icon/).
+- \`secondaryText\` (string) - (Optional) Further information about the action that appears below the label.
+- \`labelTag\` (string) - (Optional) - A label tag that provides additional guidance, shown next to the label.
 
 ### checkbox
 
@@ -5655,6 +5657,8 @@ When \`type\` is set to "checkbox", the values set to \`href\`, \`external\` and
 - \`iconAlt\` (string) - (Optional) Specifies alternate text for the icon when using \`iconUrl\`.
 - \`iconUrl\` (string) - (Optional) Specifies the URL of a custom icon.
 - \`iconSvg\` (ReactNode) - (Optional) Custom SVG icon. Equivalent to the \`svg\` slot of the [icon component](/components/icon/).
+- \`secondaryText\` (string) - (Optional) Further information about the action that appears below the label.
+- \`labelTag\` (string) - (Optional) - A label tag that provides additional guidance, shown next to the label.
 
 ### group
 

@@ -167,7 +167,7 @@ describe.each([true, false])(
           await page.setWindowSize(mobileDimensions);
           await page.focusOnTheTrigger();
           await page.keys(['Enter', ...new Array(13).fill('ArrowDown'), 'Enter', 'ArrowDown']);
-          expect(await page.getFocusedElementText()).toBe('Item 10');
+          expect(await page.getFocusedElementText()).toBe('Item 10\nThis is the last option');
         })
       );
       test(
@@ -193,7 +193,7 @@ describe.each([true, false])(
           expect(await page.getFocusedElementText()).toBe('Sub item 1');
           // move to the next group, expand it, move one item down
           await page.keys(['ArrowDown', 'Enter', 'ArrowDown']);
-          expect(await page.getFocusedElementText()).toBe('Cat 2 Sub item 0');
+          expect(await page.getFocusedElementText()).toBe('Cat 2 Sub item 0\nOption 0');
           expect(await page.getItemCount('category1Subitem1')).toEqual(0);
         })
       );
@@ -251,7 +251,7 @@ describe.each([true, false])(
           expect(await page.getItemCount('category2Subitem1')).toEqual(1);
           await page.keys(['ArrowDown']);
           expect(await page.getItemCount('category2Subitem2')).toEqual(1);
-          expect(await page.getFocusedElementText()).toBe('Cat 2 Sub item 1');
+          expect(await page.getFocusedElementText()).toBe('Cat 2 Sub item 1\nOption 1');
         })
       );
       test(

@@ -73,7 +73,7 @@ test(
     await page.openDropdown();
     await page.keys('ArrowDown');
 
-    await expect(page.getFocusedElementText()).resolves.toBe('Restart');
-    await expect(page.getHighlightedElementText()).resolves.toBe('Restart');
+    await expect(page.getFocusedElementText()).resolves.toBe('Restart\nCtrl + R\nThis is the Restart option');
+    await expect(page.getHighlightedElementText()).resolves.toBe('Restart\nCtrl + R\nThis is the Restart option');
   })
 );