Client-side UIKit: encountered unknown component Box

I’m using the template repo in bitbucket that is linked from the documentation.

I’ve changed nothing except the app id. The page has a big fat error message when I open it.

Hey Ryan, we’ve removed those new layout components for now as we’re getting ready to release the preview version in June.

It’s likely we’ll tweak the implementation of those components based on EAP feedback and some exciting work happening in the Atlassian Design System. They won’t be included in the initial Preview release but we hope to bring them back in soon.


Without the layout components what is going to be in the preview release in June? Client side events?

I’m struggling to see the reasoning behind this decision. I found the Box component to be damn near perfect because it mirrored an actual div with a subset of allowed styles. Every React dev can immediately understand and work with this concept. The only thing I would change would be to keep the standard css names, ie. flex-start instead start.

The “exciting” work being done in ADS means there is another strategic dependency that will need to be “tweaked” based on feedback. Fast forward 1-2 years from now, when it’s finally released, we will have a Box/Layout component that will likely be almost indiscernable from the original version that is in the documentation now.

1 Like

Hey @ryan

Thanks for the feedback - I’d be particularly keen to hear more about how you’ve used the layout components (I’m assuming you’re referring to VerticalLayout and HorizontalLayout) as well as the Box component.

We are looking to get more feedback on these components to make sure that they’re correct. To help understand I can share some of the reasoning…

There are similar components coming out of Design System (which are not yet ready for 3rd party consumption, but you can get an idea of them here: Atlaskit by Atlassian ) and we want to make sure that we are either reusing the implementation or aligning on API and nomenclature (for example the Design System equivalent of HorizontalLayout is Inline and the equivalent of VerticalLayout is Stack and there are pros and cons to each name, but consistency could be important). Consistency of components in Client-side UI Kit and Custom UI (which would use Design System components) is important to reduce the cognitive load on developers.

With respect to Box there are concerns over how many styles we should provide and whether or not the accepted values should support (encourage or mandate) Design Tokens (see as this would guarantee that Client-side UI Kit Forge applications are themed (i.e. automatically support dark mode).

Additionally we’re looking at things like support for an as prop in the API to allow additional HTML elements other than just div to be rendered. This would potentially unlock more accessible applications with semantic elements that are automatically styled to match ADS by the CSS reset. Good examples of this might be table and list composition.

We’re definitely hoping to be able to build on the platform provided by the client-side rendering which as you suggest will initially provide much faster user interaction and have a frequent release cadence of new capabilities as we respond to feedback. Unfortunately we didn’t really get enough feedback in the EAP phase to validate the hypotheses we had.

It would be great to understand in more detail how you’ve used the styling and components that were initially in the EAP to help us make sure we’re on the right track!


1 Like

The layout piece is a single facet of Box. The value of the Box component is a generic styled div. This allows developers to fill in the blanks and add the missing pieces that is literally taking years (or never) for Atlassian to put into UIKit. For example, a card component.

The hand-wringing over getting layouts right is the perfect illustration of why the Box component is needed. The Box component empowers Forge developers while Atlassian builds more opinionated components and systems. To your specific points

  • Atlassian could release a Box component and then later on release opinionated Layout components that are consistent with ADS (Stack and Inline) without breaking existing usage of Box.
  • “as” could be backwards compatible (assume it’s a div if the prop is missing)
  • Design token support could be released at a later date. For example, at some point in the future, you could ignore color values in the style prop that isn’t a design token value.

I wasn’t a part of the EAP. There was no announcement here or any comm channel I’m a part of. There was a recent blog post that discussed dev days that pointed to the client-side UI Kit documentation and said it was in open EAP now. Apparently, this documentation is out of date. I’m gathering that the EAP was originally invite only or you had to be at the dev conference to be invited.

edit: btw, I’m the original poster but didn’t realize I’m logged into some other community account on a different computer.


Thanks for this feedback, it’s really helpful.

I’m interested to understand more about filling in the blanks / missing pieces - for example to understand what specific needs you’d be looking to address and whether or not a better solution would be to provide additional components or improve the ones we have.

I’m also keen to understand if it would be possible to effectively fill those gaps with just a div element that you are only able to use style with. The concern is that whilst a capable developer could most likely achieve the visual appearance of something the question is whether or not that would meet accessibility standards we’d like to meet in order to provide an adequate experience for all of our end users.

I’m also interested to understand if you would prefer to do this in UI Kit rather than in Custom UI (where you’d have considerably more flexibility)?

I apologize and regret that you weren’t able to participate in the EAP, but the feedback you’re providing here is exactly the sort of thing that we were looking for.

Many thanks again for taking the time to provide this feedback,


Some of the things off the top of my head:

  • Card component
  • Inline images
  • Inline buttons
  • List component

Here is a thought exercise, pick several Atlassian developed plugins that ship with the products. A perfect example would be the Jira integration in Confluence. Can you re-build that interface and experience in UIKit? Probably not. Deconstruct what needs to be added to UIKit to build that. Then pick another one and repeat that exercise. In my opinion, that’s how the original version of UIKit should have been designed. I would imagine Atlassian designed plugins meet the accessibility and design standards you are aiming for.

Of course, it would be awesome if there was a steady release cadence that provided a constant drip feed of more/better components but it’s just not happened. I’m sure I’m missing the full picture of complexity here because from the outside, it appears that the work involves simply adding/editing custom React components. However, it feels like you guys are treating meaningful improvements to UIKit like manned missions to space.

I would prefer to use UIKit for the project I’m working on because I do see the potential it has. It’s just incredibly limiting in it’s current state. It’s challenging to build interesting things. It’s not clear to me what the original goals were and why it hasn’t been invested in much.


I think that you’re right on the first part (missing the full picture of complexity) but wrong on the second (treating improvements like manned missions to space) :smiley:

I can’t really share all the details but there are complexities, and I can imagine that there is a perception that we’ve spent years agonising over decisions and been stuck in analysis paralysis since the initial release of UI Kit but that’s really not the case.

What’s interesting is that the examples you’ve shown (with the exception of inline images and buttons - which I wonder if HorizontalLayout easily remedies?) are all things that go back to either the changes coming out of Design System (card especially here which will be unlocked through tokens and primitives) or semantic HTML (list being something better done with the appropriate HTML elements rather than a styled div).

There is definitely a need to strike a balance, and we would like to get to a point where we are able to iterate much faster. I sadly can’t make any promises and wish I could share more - but I can’t overstate how important and valuable feedback like this is.


Hello @ddraper !

Found the post so I’m adding my feedback here since we’ve been using the Box Component and we are quite surprised it disappeared between @forge/react@7 and @forge/react@8.

We are using the Box component based on a misunderstanding :wink:
We’ve been designing our Forge app using the Atlassian Design System (ADS) Components in Figma.

We initially thought that Atlassian would provide a way to use Atlaskit components in Forge apps.
Unfortunately, it is not possible right now in Forge Client-side UI kit apps.

So, for example, we have implemented the ADS Progress tracker using the Box component.

A good solution for us would be:

1 Like

Hello @FabienLydoire ,

Thanks for joining the discussion, very happy to get your feedback on this! I’m actually on paid-time off from today until next Tuesday, so will be able to reply to this and other comments in more detail then.

Very quickly though - yes, I agree that we should be bringing all the Design System components (but not all Atlaskit components, that’s a very different thing) to Client-side UI Kit in the future. There are some technical challenges around maintenance / support for Forge applications that I can’t get into here (but relate to the hidden complexities I alluded to in my response to Ryan).

Those Design System components would include primitives like Box - but worth noting that the Design System Box and the Client-side UI Kit Box are different implementations with different APIs and neither are ready for use in 3rd party production apps. So there will be a degree of patience required here.

I’d be particularly interested in your re-implementation of the progress tracker using just Box and style. Especially with respect to accessibility - what level of compliance do you feel it would meet? Would it fall below the Design System version in terms of accessibility and UX quality? Do you see that as being a problem?


Thanks for the reply.
I did not consider accessibility, but I would be happy to have links to study the matter.
As for the Progress Tracker implementation with Box, we can have an in-deep discussion.

Ping me after your time-off :slight_smile: .

1 Like

Thanks @FabienLydoire - I’ll follow up with you on your Progress Tracker implementation directly as I’d be keen to see it if you’re able to share it with me.

I still get the error that box is an unknown component in “@forge/react”: “^10.1.0”, it still appears in the UI KIT 2 documentation though. Do i need to change to Custom UI to get something like a box component?