[core] Introduce `<Box>`and `<Flex>` components #7595

ggdouglas · 2025-10-16T18:10:14Z

Proposed Changes

Original draft proposal: #6980

This PR introduces new <Box>, <Flex>, and <Slot> components providing flexible layout utilities for margin, padding, gap, alignment, and positioning.

Components:

<Box> is the foundational layout primitive with utility props that generate CSS classes
<Flex> is a specialized Box component pre-configured with display="flex"
<Slot> is used by Box for polymorphic composition via asChild

Examples

Arranging multiple Buttons horizontally:

<Box display="flex" gap={2}>
  <Button intent="primary">Button</Button>
  <Button intent="success">Button</Button>
  <Button intent="warning">Button</Button>
  <Button intent="danger">Button</Button>
</Box>

Or stacked vertically:

<Box display="flex" flexDirection="column" alignItems="center" gap={2}>
  <Button intent="primary">Button</Button>
  <Button intent="success">Button</Button>
  <Button intent="warning">Button</Button>
  <Button intent="danger">Button</Button>
</Box>

Creating more molecular components (such as EntityTitle):

<Box display="flex" gap={2}>
    <Icon className={Classes.TEXT_MUTED} icon="shop" />
    Buy groceries on my way home
    <Box asChild={true} marginXStart="auto">
        <Tag intent="danger" minimal={true}>
            Due today
        </Tag>
    </Box>
</Box>

svc-palantir-github · 2025-10-16T18:52:09Z

Add Box demo and update demo-app components

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

ericjeney

🎉 🎉 🎉

I'll let @mm-wang do the full review, but left a few preliminary comments on the things that jumped out 🙂

ericjeney · 2025-10-16T21:27:17Z

packages/core/src/components/box/_box.scss

+
+.#{$ns}-box {
+  @each $i, $value in $sizes {
+    &.gap-#{$i} {


Should we add #{$ns}- on all of the classes in this file to avoid conflicting with classes that may be defined in consuming apps?

I think that nesting it all under .#{$ns}-box is sufficient to avoid us polluting an application's CSS, but doesn't do anything to prevent the app's CSS from polluting Blueprint's components.

Hm, I'll take the point about app CSS potentially polluting these utlity classes under consideration. 🤔

I'm hesitant to add the namespace to all utility classes mainly because of verbosity. Like, we'd end up with something like this:

<div class="bp6-box bp6-flex bp6-gap-2 bp6-padding-4 bp6-margin-2">

That would make DOM inspection pretty cluttered and harder to scan at a glance. On the flip side, the main downside of not adding the prefix is the risk of conflicts with other app-level utility frameworks that could potentially collide with Blueprint's utility classes.

My thinking is that many modern apps already use CSS Modules, CSS-in-JS, or scoped styling approaches, which naturally reduce global namespace pollution. Plus, the .bp6-box parent class already provides some scoping since you have to explicitly apply it to use these utilities. And honestly, users who want comprehensive utility classes are probably already reaching for Tailwind or similar frameworks anyway.

Also worth noting that users primarily interact with <Box> via React props (like <Box gap={2} />), so the actual class names are somewhat of an implementation detail.

We should definitely keep the prefix here, mainly for the reason Eric mentioned, but also for consistency. All of our CSS classes have the prefix, and we shouldn't just change that here. I don't think the additional prefix causes any issues in practice, because like you mentioned people don't write them directly; they either use the Box component, or the Classes constants.

I don't think we should rely on consumers having certain build environments or using certain libraries that may make not having the prefix a non-issue. We can almost guarantee it by just having the namespace, at basically no cost to us.

Prefix added in 6beb43b

ericjeney · 2025-10-16T21:35:02Z

packages/core/src/components/box/box.md

@@ -0,0 +1,59 @@
+---
+tag: new


Should we mark these as experimental in some form initially?

Yeah, probably a good idea initially if we're including them in core. Perhaps something like a "beta" or "experimental" tag with a callout at the top of each docs page explaining.

develop...gdouglas/docs-beta-tag

+1, and I do want to figure out the testing strategy for this, which will help determine how we roll it out

packages/core/src/components/index.ts

svc-palantir-github · 2025-10-17T19:24:39Z

Export `FlexProps`

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

mm-wang

I would like to test it out, but wanted to leave these comments here first. I like how this is shaping up though!
I'm curious your thoughts on a Grid layout component as well - I know it doesn't have many properties, but it makes sense to me to have an "alternative" to Flex that has its own set of typical properties.

mm-wang · 2025-10-17T19:22:05Z

packages/core/src/components/box/box.md

@@ -0,0 +1,59 @@
+---
+tag: new


+1, and I do want to figure out the testing strategy for this, which will help determine how we roll it out

packages/core/src/common/_variables.scss

mm-wang · 2025-10-17T22:25:02Z

packages/core/src/components/slot/slot.tsx

+/**
+ * Slot component.
+ */
+export const Slot = forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement> & { children?: React.ReactNode }>(


question/nit: As far as I understand, Slot is a placeholder for either Box or Flex type of layout component. I see we're not exposing it by exporting, but I would maybe make it a bit clearer in terms of naming - perhaps LayoutPlaceholder or something to make it clear it's not intended to be a component that will eventually be used. Definitely a nit though! I don't feel super strongly about this.

The primary reason for this being called Slot is that it mirrors/is inspired by the Radix primitive of the same name. I'm open to calling it something else, but I'm not sure if LayoutPlaceholder really conveys the meaning to me more vs. Slot.

packages/core/src/components/box/boxProps.ts

packages/core/test/box/boxTests.tsx

mm-wang · 2025-10-17T23:10:59Z

packages/core/test/slot/slotTests.tsx

+
+import { Slot } from "../../src/components/slot/slot";
+
+describe("<Slot>", () => {


suggestion: Add a test for multiple children inside of Slot throwing an error.

Hm, having trouble writing a test here that's compatible with Karma + RTL. I've tried multiple variations around the following:

it("throws an error when multiple children are provided", () => { const consoleErrorStub = sinon.stub(console, "error"); try { expect(() => { render( <Slot> <button>First</button> <button>Second</button> </Slot>, ); }).to.throw(TypeError); } finally { consoleErrorStub.restore(); } });

But I can't seem to prevent the TypeError from being caught by Karma's global error catcher and failing the test:

<Slot> throws an error when multiple children are provided 1) Error: Uncaught TypeError: Only single element child is allowed in Slot (/var/folders/n1/whj_5mt92t10sltc2xkhhhwx08g4by/T/_karma_webpack_337031/commons.js:306) ...

mm-wang · 2025-10-17T23:19:00Z

packages/docs-app/src/examples/core-examples/boxPaddingExample.tsx

+} from "@blueprintjs/core";
+import { Example, type ExampleProps } from "@blueprintjs/docs-theme";
+
+const SPACING_VALUES: Array<BoxProps["padding"]> = [0, 0.5, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];


suggestion: This seems to be used a lot in your examples, should it be an exported constant? I'm not sure - if we add to it/change it in the future, then we run into issues. Would love your thoughts.

I'm personally ok with leaving a bit of duplication (esp. in examples/docs) for now until we find a reason for Blueprint consumers to ask for/need the exported constant. I can't think of a great reason for including it from the inception of these components, but I could be persuaded later / we could always add it later.

I was convinced that we can add this now. Implementation: cf1d575

mm-wang · 2025-10-17T23:21:13Z

packages/core/test/flex/flexTests.tsx

+        expect(classes).to.include("gap-2");
+    });
+
+    it("should support all flex-related props", () => {


nit: Do you want more tests for the other props? And for a nested set of Flex components?

mm-wang · 2025-10-17T23:23:34Z

packages/core/src/components/box/boxProps.ts

+/**
+ * The range of values for size as a percentage.
+ */
+type SizeRange = 25 | 50 | 75 | 100;


question: From the draft, I'd also wondered - why only quarters here? Why not thirds?

Linking to your original comment: #6980 (comment)

Not opposed to adding more options here, but I'm worried that this potentially doesn't scale well to individual classes. How many fractional values do we want to support?

Widths/heights seem like they're perhaps better suited to dynamic computation/inline styles. Something I've toyed around with, but is not formally implemented in this layout components proposal.

svc-palantir-github · 2025-10-21T01:19:54Z

Prefix utility classes with `bp6` namespace

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-21T15:57:49Z

Revert inclusion of `pt-spacing` CSS variable at root

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-21T16:32:51Z

Modify options for align/justify content for closer parity with CSS

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-21T20:08:04Z

Modify box tests to explicitly test for data attributes

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-21T21:58:41Z

Expose SpacingRange constant and type

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

This reverts commit cf1d575.

svc-palantir-github · 2025-10-22T01:51:19Z

Revert "Expose SpacingRange constant and type"

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

ggdouglas added Package: core no changelog labels Oct 16, 2025

ggdouglas marked this pull request as ready for review October 16, 2025 18:26

ggdouglas added 5 commits October 16, 2025 14:37

Expose pt-spacing as CSS variable on root

f1e7c0f

Add <Box> and <Slot> components

3270a59

Add <Flex> component based on Box

dba8f47

Add docs for Box and Flex components

b273d8f

Add Box demo and update demo-app components

88435ea

ggdouglas force-pushed the gdouglas/box-and-flex-components branch from 95b2da7 to 88435ea Compare October 16, 2025 18:38

ericjeney reviewed Oct 16, 2025

View reviewed changes

Export FlexProps

af6fbd3

mm-wang reviewed Oct 17, 2025

View reviewed changes

Prefix utility classes with bp6 namespace

6beb43b

Revert inclusion of pt-spacing CSS variable at root

340e944

Modify options for align/justify content for closer parity with CSS

784a7cb

ggdouglas force-pushed the gdouglas/box-and-flex-components branch from 28c66ce to 784a7cb Compare October 21, 2025 16:20

Modify box tests to explicitly test for data attributes

0763cab

ggdouglas added 3 commits October 21, 2025 17:27

Add TODO for multiple children in Slot test

526677e

Remove displayName from Slot

773cda7

Expose SpacingRange constant and type

cf1d575

Revert "Expose SpacingRange constant and type"

0a0e02e

This reverts commit cf1d575.


		import { Slot } from "../../src/components/slot/slot";

		describe("<Slot>", () => {

[core] Introduce <Box>and <Flex> components #7595

Are you sure you want to change the base?

[core] Introduce <Box>and <Flex> components #7595

Conversation

ggdouglas commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed Changes

Examples

Uh oh!

svc-palantir-github commented Oct 16, 2025

Add Box demo and update demo-app components

Uh oh!

ericjeney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

invliD Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

svc-palantir-github commented Oct 17, 2025

Export `FlexProps`

Uh oh!

mm-wang left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

svc-palantir-github commented Oct 21, 2025

Prefix utility classes with `bp6` namespace

Uh oh!

svc-palantir-github commented Oct 21, 2025

Revert inclusion of `pt-spacing` CSS variable at root

Uh oh!

svc-palantir-github commented Oct 21, 2025

Modify options for align/justify content for closer parity with CSS

Uh oh!

svc-palantir-github commented Oct 21, 2025

Modify box tests to explicitly test for data attributes

Uh oh!

svc-palantir-github commented Oct 21, 2025

Expose SpacingRange constant and type

Uh oh!

[core] Introduce `<Box>`and `<Flex>` components #7595

[core] Introduce `<Box>`and `<Flex>` components #7595

ggdouglas commented Oct 16, 2025 •

edited

Loading

invliD Oct 17, 2025 •

edited

Loading

mm-wang left a comment •

edited

Loading