patternfly · srambach · Oct 9, 2025 · Oct 10, 2025 · Oct 10, 2025 · Oct 10, 2025
diff --git a/src/patternfly/components/Toolbar/examples/Toolbar.md b/src/patternfly/components/Toolbar/examples/Toolbar.md
@@ -557,6 +557,126 @@ Several components in the following examples do not include functional and/or ac
 {{/toolbar}}
 ```
 
+## Toolbars responsive to their container
+### Toolbar with container query support
+This example shows how the toolbar responds to its container size rather than viewport size. Add the `.pf-m-container` modifier to enable container-based responsive behavior.
+<br/><br/>
+*Debugging note: View this example in full screen. These two toolbars should change color at the same time. Light blue is the media query, and lavender is the container query. This is meant to demonstrate that switching to the default container query behaves the same way as the media query, i.e. container breakpoints are adjusted to account for the sidebar. In page example is showing blue for both because the media query is triggering - should not have media query if it's got the modifier.*
+
+```hbs
+{{#> toolbar toolbar--id="toolbar-no-container-example" toolbar-expandable-content--IsExpanded=true}}
+  {{#> toolbar-content}}
+    {{#> toolbar-content-section}}
+      {{> toolbar-toggle-group toolbar-toggle-group--IsHidden=true}}
+    {{/toolbar-content-section}}
+    {{#> toolbar-expandable-content}}
+      {{> toolbar-group-search}}
+      {{> toolbar-group-filter}}
+      {{> toolbar-group-label-group}}
+      {{> toolbar-group-action-inline}}
+    {{/toolbar-expandable-content}}
+  {{/toolbar-content}}
+{{/toolbar}}
+<br/>
+<div style="display: flex;">
+  <div style="width: 290px; background: var(--pf-t--global--background--color--secondary--default); padding: 1rem;">Sidebar (290px)</div>
+  <div style="flex: 1;">
+    {{#> toolbar toolbar--modifier="pf-m-container" toolbar--id="toolbar-container-example" toolbar-expandable-content--IsExpanded=true}}
+      {{#> toolbar-content}}
+        {{#> toolbar-content-section}}
+          {{> toolbar-toggle-group toolbar-toggle-group--IsHidden=true}}
+        {{/toolbar-content-section}}
+        {{#> toolbar-expandable-content}}
+          {{> toolbar-group-search}}
+          {{> toolbar-group-filter}}
+          {{> toolbar-group-label-group}}
+          {{> toolbar-group-action-inline}}
+        {{/toolbar-expandable-content}}
+      {{/toolbar-content}}
+    {{/toolbar}}
+  </div>
+</div>
+```
+
+The container query breakpoints are 290px less than viewport breakpoints:
+- `.pf-m-container-sm` - Adjust at 286px (vs viewport 576px)
+- `.pf-m-container-md` - Adjust at 478px (vs viewport 768px)
+- `.pf-m-container-lg` - Adjust at 702px (vs viewport 992px) - **default for `.pf-m-container`**
+- `.pf-m-container-xl` - Adjust at 910px (vs viewport 1200px)
+- `.pf-m-container-2xl` - Adjust at 1160px (vs viewport 1450px)
+
+**Note**: `.pf-m-container` without a breakpoint suffix defaults to `lg` behavior for backward compatibility.
+
+This is particularly useful when the toolbar is placed in:
+- Sidebar panels
+- Drawer components
+- Modal dialogs
+- Grid cells with constrained widths
+- Any nested layout container
+
+### Toolbar with container query support (custom breakpoint)
+You can specify which container width triggers the responsive behavior using breakpoint modifiers.
+<br/><br/>
+*Debugging note: XL and 2XL can't trigger when confined by the content area (view in full screen)*
+```hbs
+{{#> toolbar toolbar--modifier="pf-m-container-md" toolbar--id="toolbar-container-md-example" toolbar-expandable-content--IsExpanded=true}}
+  {{#> toolbar-content}}
+    {{#> toolbar-content-section}}
+      {{> toolbar-toggle-group toolbar-toggle-group--IsHidden=true}}
+    {{/toolbar-content-section}}
+    {{#> toolbar-expandable-content}}
+      {{> toolbar-group-search}}
+      {{> toolbar-group-filter}}
+      {{> toolbar-group-label-group}}
+      {{> toolbar-group-action-inline}}
+    {{/toolbar-expandable-content}}
+  {{/toolbar-content}}
+{{/toolbar}}
+```
+
+This toolbar will expand at the `md` container breakpoint (478px) instead of the default `lg` (702px).
+
+### Comparing container breakpoints
+This example shows how different breakpoint modifiers affect when the toolbar expands.
+
+```hbs
+<div style="display: flex; gap: 1rem; flex-direction: column;">
+  <div>
+    <h4>Container md (478px breakpoint)</h4>
+    {{#> toolbar toolbar--modifier="pf-m-container-md" toolbar--id="toolbar-container-md" toolbar-expandable-content--IsExpanded=true}}
+      {{#> toolbar-content}}
+        {{#> toolbar-content-section}}
+          {{> toolbar-toggle-group toolbar-toggle-group--IsHidden=true}}
+        {{/toolbar-content-section}}
+        {{#> toolbar-expandable-content}}
+          {{> toolbar-group-search}}
+          {{> toolbar-group-filter}}
+          {{> toolbar-group-label-group}}
+          {{> toolbar-group-action-inline}}
+        {{/toolbar-expandable-content}}
+      {{/toolbar-content}}
+    {{/toolbar}}
+  </div>
+
+  <div>
+    <h4>Container lg (702px breakpoint - default)</h4>
+    {{#> toolbar toolbar--modifier="pf-m-container-lg" toolbar--id="toolbar-container-lg" toolbar-expandable-content--IsExpanded=true}}
+      {{#> toolbar-content}}
+        {{#> toolbar-content-section}}
+          {{> toolbar-toggle-group toolbar-toggle-group--IsHidden=true}}
+        {{/toolbar-content-section}}
+        {{#> toolbar-expandable-content}}
+          {{> toolbar-group-search}}
+          {{> toolbar-group-filter}}
+          {{> toolbar-group-label-group}}
+          {{> toolbar-group-action-inline}}
+        {{/toolbar-expandable-content}}
+      {{/toolbar-content}}
+    {{/toolbar}}
+  </div>
+</div>
+```
+
 ### Sticky toolbar
 ```hbs
 {{#> toolbar toolbar--modifier="pf-m-sticky" toolbar--id="toolbar-sticky-example"}}
@@ -640,6 +760,12 @@ As the toolbar component is a hybrid layout and component, some of its elements
 | `.pf-m-secondary` | `.pf-v6-c-toolbar` | Modifies toolbar to have secondary background color. |
 | `.pf-m-no-padding` | `.pf-v6-c-toolbar` | Modifies toolbar to have no padding. |
 | `.pf-m-no-background` | `.pf-v6-c-toolbar` | Modifies toolbar to have no background color. |
+| `.pf-m-container` | `.pf-v6-c-toolbar` | Enables container query support at the `lg` breakpoint (702px). |
+| `.pf-m-container-sm` | `.pf-v6-c-toolbar` | Enables container query support at the `sm` breakpoint (286px). |
+| `.pf-m-container-md` | `.pf-v6-c-toolbar` | Enables container query support at the `md` breakpoint (478px). |
+| `.pf-m-container-lg` | `.pf-v6-c-toolbar` | Enables container query support at the `lg` breakpoint (702px). |
+| `.pf-m-container-xl` | `.pf-v6-c-toolbar` | Enables container query support at the `xl` breakpoint (910px). |
+| `.pf-m-container-2xl` | `.pf-v6-c-toolbar` | Enables container query support at the `2xl` breakpoint (1160px). |
 | `.pf-m-expanded` | `.pf-v6-c-toolbar__expandable-content` | Modifies expandable content section for the expanded state. |
 | `.pf-m-expanded` | `.pf-v6-c-toolbar__item.pf-m-expand-all` | Modifies an expand all button for the expanded state. |
 | `.pf-m-action-group` | `.pf-v6-c-toolbar__group` | Initiates action group spacing. |

diff --git a/src/patternfly/components/Toolbar/toolbar.scss b/src/patternfly/components/Toolbar/toolbar.scss
@@ -193,6 +193,14 @@ $pf-v6--include-toolbar-breakpoints: true !default;
     --#{$toolbar}--BackgroundColor: var(--#{$toolbar}--m-no-background--BackgroundColor);
   }
 
+  // Container query support (opt-in)
+  // Establishes container context for all container modifiers
+  &.pf-m-container,
+  &[class*="pf-m-container-"] {
+    container-type: inline-size;
+    container-name: toolbar;
+  }
+
   // @include resize-observer-placeholder('md') {
   //   do resize observer things here
   // }
@@ -288,12 +296,81 @@ $pf-v6--include-toolbar-breakpoints: true !default;
   border-block-end: var(--#{$toolbar}__expandable-content--BorderBlockEndWidth) solid var(--#{$toolbar}__expandable-content--BorderBlockEndColor);
   box-shadow: var(--#{$toolbar}__expandable-content--BoxShadow);
 
+  // stylelint-disable 
+
   @media screen and (min-width: $pf-v6-global--breakpoint--lg) {
-    position: static;
-    padding: 0;
-    border-block-end: 0;
-    box-shadow: none;
+    // Only apply viewport-based behavior if no container modifier is present
+    @at-root .#{$toolbar}:not([class*="pf-m-container"]) & {
+      position: static;
+      padding: 0;
+      border-block-end: 0;
+      box-shadow: none;
+      background-color: lightblue !important;
+    }
+  }
+
+  // Default container behavior (lg breakpoint) when using .pf-m-container
+  @at-root .#{$toolbar}.pf-m-container:not([class*="pf-m-container-"]) & {
+    @include pf-v6-container-query("lg", "toolbar") {
+      position: static;
+      padding: 0;
+      border-block-end: 0;
+      box-shadow: none;
+      background-color: lavender !important;
+    }
+  }
+
+  // Container query behavior with explicit breakpoint modifiers
+  @at-root .#{$toolbar}.pf-m-container-sm & {
+    @include pf-v6-container-query("sm", "toolbar") {
+      position: static;
+      padding: 0;
+      border-block-end: 0;
+      box-shadow: none;
+      background-color: lightgreen !important;
+    }
+  }
+
+  @at-root .#{$toolbar}.pf-m-container-md & {
+    @include pf-v6-container-query("md", "toolbar") {
+      position: static;
+      padding: 0;
+      border-block-end: 0;
+      box-shadow: none;
+      background-color: lightcoral !important;
+    }
+  }
+
+  @at-root .#{$toolbar}.pf-m-container-lg & {
+    @include pf-v6-container-query("lg", "toolbar") {
+      position: static;
+      padding: 0;
+      border-block-end: 0;
+      box-shadow: none;
+      background-color: yellow !important;
+    }
+  }
+
+  @at-root .#{$toolbar}.pf-m-container-xl & {
+    @include pf-v6-container-query("xl", "toolbar") {
+      position: static;
+      padding: 0;
+      border-block-end: 0;
+      box-shadow: none;
+      background-color: violet !important;
+    }
+  }
+
+  @at-root .#{$toolbar}.pf-m-container-2xl & {
+    @include pf-v6-container-query("2xl", "toolbar") {
+      position: static;
+      padding: 0;
+      border-block-end: 0;
+      box-shadow: none;
+      background-color: orange !important;
+    }
   }
+//stylelint-enable 
 
   &.pf-m-expanded,
   .#{$toolbar}__group {

diff --git a/src/patternfly/sass-utilities/mixins.scss b/src/patternfly/sass-utilities/mixins.scss
@@ -57,6 +57,64 @@
   }
 }
 
+// Container query mixin for responsive classes based on container size
+// Usage: @include pf-v6-container-query("md", "toolbar") { ... }
+@mixin pf-v6-container-query($point, $container-name: null) {
+  @if $point == "" or not $point or $point == "base" {
+    @content;
+  } @else if $point == "sm" {
+    @if $container-name {
+      @container #{$container-name} (min-width: #{$pf-v6-global--container-breakpoint--sm}) {
+        @content;
+      }
+    } @else {
+      @container (min-width: #{$pf-v6-global--container-breakpoint--sm}) {
+        @content;
+      }
+    }
+  } @else if $point == "md" {
+    @if $container-name {
+      @container #{$container-name} (min-width: #{$pf-v6-global--container-breakpoint--md}) {
+        @content;
+      }
+    } @else {
+      @container (min-width: #{$pf-v6-global--container-breakpoint--md}) {
+        @content;
+      }
+    }
+  } @else if $point == "lg" {
+    @if $container-name {
+      @container #{$container-name} (min-width: #{$pf-v6-global--container-breakpoint--lg}) {
+        @content;
+      }
+    } @else {
+      @container (min-width: #{$pf-v6-global--container-breakpoint--lg}) {
+        @content;
+      }
+    }
+  } @else if $point == "xl" {
+    @if $container-name {
+      @container #{$container-name} (min-width: #{$pf-v6-global--container-breakpoint--xl}) {
+        @content;
+      }
+    } @else {
+      @container (min-width: #{$pf-v6-global--container-breakpoint--xl}) {
+        @content;
+      }
+    }
+  } @else if $point == "2xl" {
+    @if $container-name {
+      @container #{$container-name} (min-width: #{$pf-v6-global--container-breakpoint--2xl}) {
+        @content;
+      }
+    } @else {
+      @container (min-width: #{$pf-v6-global--container-breakpoint--2xl}) {
+        @content;
+      }
+    }
+  }
+}
+
 // Create single prop / value classes, optionally add responsive suffix
 // @group mixins
 // @moduleType mixin

diff --git a/src/patternfly/sass-utilities/scss-variables.scss b/src/patternfly/sass-utilities/scss-variables.scss
@@ -78,6 +78,23 @@ $pf-v6-global--height-breakpoint-name-map: (
   "2xl": $pf-v6-global--height-breakpoint--2xl
 );
 
+// Container query breakpoints (290px less than viewport breakpoints)
+// Used when components opt into container-based responsive behavior
+$pf-v6-global--container-breakpoint--sm: 17.875rem !default; // 286px (576px - 290px)
+$pf-v6-global--container-breakpoint--md: 29.875rem !default; // 478px (768px - 290px)
+$pf-v6-global--container-breakpoint--lg: 43.875rem !default; // 702px (992px - 290px)
+$pf-v6-global--container-breakpoint--xl: 56.875rem !default; // 910px (1200px - 290px)
+$pf-v6-global--container-breakpoint--2xl: 72.5rem !default; // 1160px (1450px - 290px)
+
+// Global container breakpoint name map
+$pf-v6-global--container-breakpoint-name-map: (
+  "sm": $pf-v6-global--container-breakpoint--sm,
+  "md": $pf-v6-global--container-breakpoint--md,
+  "lg": $pf-v6-global--container-breakpoint--lg,
+  "xl": $pf-v6-global--container-breakpoint--xl,
+  "2xl": $pf-v6-global--container-breakpoint--2xl
+);
+
 // Spacer properties
 $pf-v6-global--spacer-properties-map: (
   "m":  "margin",