[labs] 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 to @blueprintjs/labs. These components provide 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

packages/labs/src/components/box/box.md

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.

packages/labs/src/components/box/box.md

packages/core/src/common/_variables.scss

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

packages/labs/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/labs/src/components/box/boxProps.ts

packages/core/test/box/boxTests.tsx

packages/labs/src/components/slot/slot.test.tsx

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

packages/labs/src/components/flex/flex.test.tsx

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

packages/labs/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.

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.

svc-palantir-github · 2025-10-31T16:41:39Z

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.

This reverts commit cf1d575.

svc-palantir-github · 2025-11-05T04:27:38Z

Move components to labs

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

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

ggdouglas · 2025-11-05T16:16:56Z

packages/labs/package.json

        "lint-fix": "es-lint --fix && sass-lint --fix",
        "start": "pnpm dev",
        "test": "vitest run",
+        "test:watch": "vitest watch",


Added this as a convenience helper when writing/running tests locally.

ggdouglas · 2025-11-05T16:26:33Z

packages/labs/src/common/classes.ts


-// declare let BLUEPRINT_NAMESPACE: string | undefined;
-// declare let REACT_APP_BLUEPRINT_NAMESPACE: string | undefined;
+const NS = Classes.getClassNamespace();


FYSA @mm-wang, I ended up pulling the namespace from the core package for a few reasons:

We need to pull in core anyways for the use of the $pt-spacing variable that the Box component uses

We need to use the $ns namespace in the _box.scss also, and this was proving to be more complicated with us redeclaring a new namespace in labs

The other packages (datetime, select, and table) all follow this same pattern, so there is precedent

We end up with less duplication overall by reusing the namespace already declared in core

We discussed further and decided to combine both approaches. The namespace will now be .bp6-labs-*.

Implemented in e4aa04c

ggdouglas · 2025-11-05T16:37:15Z

packages/labs/src/vitest-env.d.ts


-// Empty for no components right now
-// Example: @use "./sampleComponent/sample-component";
+/// <reference types="@testing-library/jest-dom/vitest" />


The diff here is a bit confusing. A new file, packages/labs/src/vitest-env.d.ts, was added. This was done to pick up the types from @testing-library/jest-dom / fix compilation in the labs package.

svc-palantir-github · 2025-11-05T20:44:55Z

Add `-labs` to namespace prefix inside of labs components

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-11-05T21:32:02Z

Add back labs-scoped `DISPLAYNAME_PREFIX`

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

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

mm-wang

LGTM! 🚀

mm-wang · 2025-11-05T21:49:47Z

packages/labs/src/common/props.ts

+
+import { DISPLAYNAME_PREFIX as CORE_DISPLAYNAME_PREFIX } from "@blueprintjs/core";
+
+export const DISPLAYNAME_PREFIX = `${CORE_DISPLAYNAME_PREFIX}Labs`;


Invalidated by push of 12c2cf2

svc-palantir-github · 2025-11-05T22:18:57Z

Address docs feedback

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-11-05T22:39:25Z

Add Flex props interface for posterity

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 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

mm-wang reviewed Oct 17, 2025

View reviewed changes

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

ggdouglas force-pushed the gdouglas/box-and-flex-components branch from 0a0e02e to b2ccddd Compare October 31, 2025 13:49

ggdouglas and others added 13 commits November 4, 2025 12:53

Expose pt-spacing as CSS variable on root

6ebcf29

Add <Box> and <Slot> components

7db86e9

Add <Flex> component based on Box

054a6aa

Add docs for Box and Flex components

3ac9af1

Add Box demo and update demo-app components

cf993f6

Export FlexProps

4ca055d

Prefix utility classes with bp6 namespace

5f04a8c

Revert inclusion of pt-spacing CSS variable at root

c7bb484

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

0c6a7c9

Modify box tests to explicitly test for data attributes

0d2e22e

Add TODO for multiple children in Slot test

ff4b127

Remove displayName from Slot

5a24e0f

Expose SpacingRange constant and type

10ba05b

Revert "Expose SpacingRange constant and type"

27cdd77

This reverts commit cf1d575.

ggdouglas force-pushed the gdouglas/box-and-flex-components branch from b2ccddd to 78c1ed8 Compare November 5, 2025 02:19

Move components to labs

01345dd

ggdouglas force-pushed the gdouglas/box-and-flex-components branch from 78c1ed8 to 01345dd Compare November 5, 2025 04:16

ggdouglas changed the title ~~[core] Introduce <Box>and <Flex> components~~ [labs] Introduce <Box>and <Flex> components Nov 5, 2025

ggdouglas added Package: labs and removed Package: core labels Nov 5, 2025

ggdouglas commented Nov 5, 2025

View reviewed changes

ggdouglas added 3 commits November 5, 2025 12:11

Change ExampleCard to use Flex

311f74e

Add blueprint-labs.css to demo-app styles

b105f43

Add -labs to namespace prefix inside of labs components

e4aa04c

ggdouglas added 2 commits November 5, 2025 16:10

Additional tweaks to $ns in labs

841eb6e

Add back labs-scoped DISPLAYNAME_PREFIX

67a09b7

mm-wang reviewed Nov 5, 2025

View reviewed changes

mm-wang previously approved these changes Nov 5, 2025

View reviewed changes

Address docs feedback

12c2cf2

Add Flex props interface for posterity

5f13449

mm-wang approved these changes Nov 5, 2025

View reviewed changes

ggdouglas merged commit f88e977 into develop Nov 6, 2025
14 checks passed

ggdouglas deleted the gdouglas/box-and-flex-components branch November 6, 2025 00:42

ggdouglas mentioned this pull request Dec 2, 2025

[Draft] Box Component #6980

Closed


		import { DISPLAYNAME_PREFIX as CORE_DISPLAYNAME_PREFIX } from "@blueprintjs/core";

		export const DISPLAYNAME_PREFIX = `${CORE_DISPLAYNAME_PREFIX}Labs`;

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

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

Uh oh!

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!

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!

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!

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!

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!

svc-palantir-github commented Oct 22, 2025

Revert "Expose SpacingRange constant and type"

Uh oh!

svc-palantir-github commented Oct 31, 2025

Revert "Expose SpacingRange constant and type"

Uh oh!

svc-palantir-github commented Nov 5, 2025

Move components to labs

Uh oh!

Choose a reason for hiding this comment

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

[labs] 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

ggdouglas Nov 5, 2025 •

edited

Loading

ggdouglas Nov 5, 2025 •

edited

Loading