Have you tried using Spectrum Web Components yet to build your plugin UI?


Spectrum is Adobe’s design system. It’s pretty ubiquitous in Photoshop and building plugins aligning to this system ensures that your plugin UI seems at home within Photoshop. Web Components are a modern feature introduced in the Web standards allowing the creation of custom, reusable UI components that can be used on Web pages. The open-source Spectrum Web Components (SWC) project is an implementation of Adobe’s Spectrum design system allowing you to leverage existing UI components. UXP has now added support for some SWC components which can be used in any UXP plugin. Do head over to the Photoshop documentation that delves into more detail and walks through the various uses and applications of Spectrum within UXP.

UXP had added support for Web Components some time back with v7.0 in Photoshop. Building atop that with v7.2 in Photoshop, you can now incorporate 30 Spectrum Web Components in your Photoshop plugins.


To make the onboarding easier, we’ve added starter templates for both vanilla JS

npx @swc-uxp-wrappers/create-swc-uxp-ap <name-of-the-app>

cd <name-of-the-app>

and React JS

npx @swc-uxp-wrappers/create-swc-uxp-react-app <name-of-the-app>

cd <name-of-the-app>

A few pertinent questions that might arise:

Wait, I see these templates rely on packages under the scope @swc-uxp-wrappers. What are these?

The open-source Spectrum Web Components UI library targets a modern web browser. As you would be aware, UXP is not a browser (and never intends to be one either!), and with that comes limitations in supporting all the CSS properties and layouts that a modern browser supports. These wrappers are mostly the overrides of the styles to get these components to show up properly in a UXP environment. Don’t worry as your actual code need not use these wrappers directly. With some bundler configuration, the aliasing of the components is taken care of internally and you can just use regular code like

import '@spectrum-web-components/banner/sp-banner.js';

as one would while using the regular SWC components to consume them.

… And what about the @swc-react/* packages in the React template?

Well, these are the React wrappers developed by the open-source SWC team that enable consuming Spectrum Web Components in a React context.

I see a plethora of versions being used in the package.json of the starter template. Why aren’t you using the usual caret version (^) instead?

There are explicit versions of the underlying SWC components that the UXP team has locked onto to release this first batch of components as the later versions of these components had even more disparities concerning CSS etc. in the context of UXP. The team is working on moving to a more recent version of these components to help align with the current available SWC component versions. Using the ^ notation for specifying package dependencies is thus not possible since it would automatically bring in the latest package versions and lead to a break in the plugin UI.

OK but what about those sp-* elements that UXP has already been supporting until now?

Those are called Spectrum UXP Widgets and they aren’t going away anytime soon and in most cases can co-exist with SWC components with the obvious caveat that an sp-button imported from the SWC package can’t co-exist with the Spectrum UXP widget sp-button. Once any sp-* component is imported from the SWC package it supersedes the native Spectrum UXP widget. If you don’t import any sp-button but directly consume sp-button in either the HTML or in the JS code, you’ll get the natively supported Spectrum UXP button sp-button.

Why then should I go the route of using SWC and not using the existing Spectrum UXP widgets?

With simplicity comes the tradeoff that you hardly have any control over the native Spectrum UXP widget’s styling and they offer very limited APIs as opposed to SWC components. Think of the analogy of the standard <video> component on a browser. What if you’d like to inspect the elements in that Video element? You can’t. What if you wanted to extend from that Video element and override a few of its characteristics or behavior? You can’t! These limitations are pretty much similar to what you’d encounter with the native Spectrum UXP widgets which are essentially opaque elements. With SWC components, which are built atop Web Components, you can inspect the Shadow DOM of the component and if required, even extend from the SWC wrapper class to further customize the element as per your need. UXP comes with rich debugging support for Web Components.

When do we get to see more components in the list?

The UXP team is working on adding support for missing components and/or variants. Please stay tuned for further updates! Have more questions? Post on this forum!


Icons-workflow and Icons-ui :heart_eyes:

It took me few hours to configure that for Alchemist.

I think most important documentation should not only be in starter project readme but also in the documentation website. Therefore I missed some important steps.

In the end I made it work with ESBuild (instead of Webpack) and I upgraded from yarn 1 to 4… not sure how that would work with npm.

In the end I made it to work. But then I realized there is no “S” size for components. Only “M” and “L” so I abandoned that branch. Will try again in a few months once it is more refined.

Having text inputs in SWC would be big deal because I could finally style them a bit. It would not have infinity and beyond z-index and textarea could have finally scrollbar on windows.

Also, I really think the installation should be as easy as possible. Simply type one package name in npm cli instead of knowing some esoteric version numbers of base spectrum package and then add one package on top of that and add wrappers.

I think instead there should be some automated server-side workflow to combine and automatically publish spectrum-base-package@esoteric.version + uxp-wrapper = simple-package So nobody would need to care about exact version, yarn version, resolutions forgetting wrappers.

Would something like that be possible?

Sorry if this sounds harsh… you are doing great job in right direction… this is just part of the process on the way to the goal.


Do you mean you couldn’t make it work with Webpack at all? :astonished: If so, I won’t even try then. For now at least

It works with Webpack as shown in starter plugin. The thing about ESBuild is that is like 10× faster and I would like to migrate to it. When Webpack is ready to start… ESBuild is already finished :smiley:


I haven’t run any benchmarks or anything but I don’t find Webpack with React/SWC build times to be bad.
Initial build: ≈1300ms
Reload: ≈100ms
(rough estimates based on 10 reloads)

I agree about the documentation treasure hunt and the generally annoying installation process.

The lack of small sized components means that I’m often reverting back to sp- elements, and also flies in the face of those green indicators in the docs that suggest a component is fully compliant with SWC.

Ditto Field-label - it doesn’t respect text colour. I’m sure there are more but I’ve not had much opportunity to test anything beyond the buttons.

If you get interested I’ll show you my Webpack config

1 Like

I am still a completely vanilla guy, so I got lost as soon as it says “install dependencies”. I was hoping it would just be a file I needed to include. One day I will have time to try and explore more and figure these things out.

1 Like

But then I realized there is no “S” size for components. Only “M” and “L” so I abandoned that branch.

That’s exactly the same reason why I didn’t use it. The elements are far too big.


@Jarda @tomzag

I realized there is no “S” size for components.

Are you referring to the scale property on <sp-theme> here? Some components like <sp-button> do have the size property which is supported in UXP.

1 Like

I’d like to understand where you got lost following the steps on the vanilla JS starter template. Are any of the steps outlined there unclear? We would want to enhance the documentation based on your feedback. Also, installing dependencies is not specific to UXP. Even the regular usage of Spectrum Web Components on the web has a similar workflow.

I don’t see “S” size in <sp-theme> and I could not find proper import for checkbox. Am I supposed to use M size in theme and S size in individual SWC components? Is there some overview to show what components are supporting S size? And how do I import them? Should I import them with medium size in the filepath?

1 Like

My experience was this: I wanted to use sp-menu for a context menu. After about an hour of trying to install all the necessary modules and setting setting up in my project I was successfull doing it but I realized sp-theme only supports the scales “M” and “L” and there was also no size option for sp-menu itself.
It didn’t work with my layout because the element was far too big. It looked totally out of place. I am also pretty sure that beginners will most likely fail at the set up of Spectrum Web Components. It’s too complicated. Especially with React.

CSS transform scale would probably be a workaround but it’s not available in UXP so I went back to menuitem for my context menu. The big advantage here is that it is also displayed outside the panel. Spectrum components are limited to the size of the panel. However, icons do not work with the HTML menuitem tag.

At the moment, the layout of my plugins probably needs the most work or workarounds.


I’m dying for those color wheel, sliders, and other related tools to work. With CEP I used to use iro.js to create color wheels and related color tools. It worked fantastically well! But with UXP the library doesn’t seem to work anymore, and I can’t find one that is compatible and let me create a color wheel or even a color picker. Having native Adobe tools would be a great alternative.

I think that if @Jarda is confused then the documentation is definitely lacking! :rofl:

It took me a while to notice that not all components listed as compliant in the UXP SWC docs actually reference size (I’d post a screenshot but my phone’s being a bastard, but for example, checkbox does, switch does but not fully working, and button doesn’t).
As far as I’m aware there is nothing in the docs that suggests the small variant is only available under a particular theme.

I think that considering the limited screen real estate available to plugin developers, not having small variants on release is a massive oversight in the rollout of SWC in UXP.

A short while ago I posted a bit of a whine about a lack of clarity re: CSS, which I’ll note nobody from Adobe addressed, even just to diplomatically clarify things (weirdly there was a massive uptick in engagement from Adobe staff on all other posts, lol), anyway, off the back of that I followed Adobe’s carrot and stick and waded into SWC.
Firstly, I’ll say that actually I can see how SWC solves a lot of the CSS issues (even if it means a homogeneity of design), and I’m here for that, totally onboard.
Having then banged my head against a wall for exactly the same reasons I was before - never knowing if it’s me that’s wrong or the component - I’ve concluded that SWC has been released in a state that’s semi-functional and not quite fit for purpose. Lots of it is great and a huge improvement on sp- elements, but it’s so inconsistent and unpredictable in a way that sp- elements are not. But yet we’ve been told that we need to migrate to SWC as sp- elements will be deprecated!

As 3rd party developers we’re left in a liminal state where we lack clear and explicit enough documentation and timeframes to make informed choices.

To be completely honest, at the moment I feel this lack of a consistent, stable, and transparent framework for UI under UXP is hurting my business - it’s one thing to do due diligence and explain to a client that APIs change and that might incur future spend, it’s very different having that conversation about a basic and foundational UI element like a button.
The feedback I’ve received from prospective and ongoing clients is that they don’t feel fully confident in investing in UXP yet but also don’t want to use CEP due to its unknown lifespan, and in my opinion that’s mostly down to UI.

TL; DR: SWC is a massive step towards a consistent and functional UI framework for UXP, but IMO it’s been delivered premature

1 Like

I hate to reveal my ignorance here, but I strictly use vanilla and do everything with just text. I don’t use (or know how to use) node or yarn or any of those things.
If I need to include another file/library, with something like adding “script src=” that is fine…but as soon as I see something like “npx @swc-uxp-wrappers/create-swc-uxp-ap ” I am lost.
I am sure one day, if I ever get spare time, I will expand my horizons.

Thanks for the clarification. We are evaluating the CDN route wherein you can add a <script> tag and get all the SWC definitions for use. Hopefully, that should be more palatable to you for consumption but this shall take some time before it’s available.

1 Like

What?? They will be deprecated?? When and where was this announced?

@JasonM You are not alone… author of Photopea is not using node_modules as well. Yet his high-quality online image editor made him $1.000.000 a year :smiley: esm version · Issue #122 · photopea/UTIF.js · GitHub

So I wouldn’t exactly say it is a necessary requirement for success and wonder whether those tools supposed to make my work easier are actually making it harder :smiley: (probably not but I can’t say for 100%)

1 Like