Deprecated components `Frame`, `Loading`, `Modal`, `Navigation`, `Toast` and `ContextualSaveBar`

[SinXie]

Issue summary

I have a project that uses shopify/polaris as the base component framework, Deprecating these components would have a huge impact on me.

So, whether there is a major release that supports these components and keeps them updated or If I want to continue using these components, What do I need to do?

[yuvrajharod]

+1

Missing documentation even before a major release is a problem, looking at the docs, I can't find any references, and I don't even have an idea if there are some substitute components being created for this? also some of the components like Modal will effect hugely when it comes to state management.

Looking forward to the complete release so we can be sure of what to expect from this point and what components do we need to upgrade.

[kyledurand]

If I want to continue using these components, What do I need to do?

Sorry about the abruptness of this change. These components were always meant for internal use only, and the documentation should have been removed with the inception of AppBridge.

There are components within Polaris that shouldn't be used in third party apps, like Navigation and Frame (there should only be one Navigation and Frame per page and they already exist within the admin). The other components should be accessed via AppBridge Actions, where you'll find the remaining components: Toast, Modal, Loading, and more.

[mesija]

The task of rewriting the Modal component to adhere to new rules will be challenging and time-consuming due to the limited functionality of the app bridge version. This change will require modifying the application's logic in multiple areas, which will add to the maintenance workload.

Additionally, a major challenge with using the app bridge is that it only works within an iframe, making it difficult to test and integrate with React projects outside of the iframe. Unfortunately, the automatic update feature of React does not function with the frame. The unavailability of app bridge components outside of the iframe is a significant limitation.

The status of "@shopify/app-bridge-react" is unclear as it has been moved to the "Previous versions" section, raising concerns about its discontinuation in the future.

It would be helpful to know if there are any alternatives that allow for the use of app bridge components outside of the iframe and what is the fate of @shopify/app-bridge-react?

[lehoangnnx]

I also have the same question, why was there no notice before removal and no reasonable alternative?

1/ Using Modal at @shopify/app-bridge-react, I don't see any documentation that allows adding more UI to Modal's body, Modal is simply a string message. This affects us a lot.

2/ With @shopify/app-bridge-react being included in "Previous versions", what does its future look like? Has it been eliminated? What will the future of apps built based on React be like if removed? Converting a React application to Remix is not easy.

[SinXie]

If I want to continue using these components, What do I need to do?

Sorry about the abruptness of this change. These components were always meant for internal use only, and the documentation should have been removed with the inception of AppBridge.

There are components within Polaris that shouldn't be used in third party apps, like Navigation and Frame (there should only be one Navigation and Frame per page and they already exist within the admin). The other components should be accessed via AppBridge Actions, where you'll find the remaining components: Toast, Modal, Loading, and more.

My project doesn't exist on shopify page, so I don't use AppBridge.

[yuvrajharod]

Even if you want to deprecate, you can do that and we will consider upgrading with a deadline in mind, I am not sure how can you just hide a components documentation which hurts our business planning and timelines.

It would be best if you can atleast bring back the documentation for now at the deprecated section, we will upgrade definitely in the future once we have spare time to do that. @kyledurand

[kyledurand]

My project doesn't exist on shopify page

Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps

[mesija]

Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps

Hi, the question was not addressed to us, but I can give you our use cases:

1. A browser extension that works in the Shopify admin area, so that it matches the design of the admin area and so that you can use components from the main application, we use Polaris there. And of course, there is no way to connect an app bridge, so a lot of things will have to be rewritten when the same modal windows do not work.

2. The admin part of the application. We understand that this is not directly related to the application, but the use of Polaris in our admin allows us not to write the code twice and use many modules there.

3. Testing and development. Again, the fact that most everything could be implemented without an app bridge allowed us to quickly and efficiently develop and test applications. Now you have to tie everything to the shopify admin panel and the iframe. And of course, page loading in the admin frame is ten times slower than from a conditional localhost.

Of course, Polaris was not designed for such scenarios, but the fact that it could work without an app bridge made it more versatile and accelerated development and simplified support. Making these changes, especially the abandonment of local modal windows, will make life more difficult for developers.

Polaris was created and is generally considered to be in the direction of simplifying development, but this decision seems to go against those statements.

[ShawnChenXHC]

I am a developer at Meta, actively working on the Facebook and Instagram sales channel in Shopify Admin.

I would like to add to the conversation and express my concerns about the sudden deprecation of these components. Modals and Toasts are used extensively within the Facebook and Instagram sales channel. Now that the documentation for these components is completely gone, it makes it hard for us to determine how to transition to AppBridge modals, even if we decided to do that.

Can the documentation for Modal, Frame, Loading, Navigation and Toast be brought back on the Shopify Polaris website?

• https://polaris.shopify.com/components/deprecated/legacy-card - LegacyCard and other components are good examples. These components were deprecated, but the documentation is still available.

[jineshshah36]

There are components within Polaris that shouldn't be used in third party apps, like Navigation and Frame (there should only be one Navigation and Frame per page and they already exist within the admin). The other components should be accessed via AppBridge Actions, where you'll find the remaining components: Toast, Modal, Loading, and more.

@kyledurand What about all of us that are part of the Shopify ecosystem and use these components in standalone versions of our apps? This represents a huge breaking change for many of us. We use polaris not only in our embedded apps, but also in our standalone apps. All of these apps are part of the same ecosystem and taking these components away will make it harder for us to support any of polaris.

1. If we don't have these foundational components, we have to use something other than polaris, and given the size of our team, we cannot support both an embedded polaris and non-embedded non-polaris version of our app.

2. This seems to be a sudden and major change to polaris that has had little-to-no communication

[jineshshah36]

I just traced these changes to the following PR: https://github.com/Shopify/polaris/pull/11382

Am I correct in understanding that your goal is just to add friction? If so, I believe there must be better ways to do this.

I'm curious if @alex-page, @craigbrunner, or @themarkappleby chatted with anyone in the ecosystem before moving forward with this change.

My intention is only to provide the perspective of a company that is in the Shopify ecosystem:

I'm one of the cofounders of Endear, a CRM and clienteling solution for consumer brands, many of whom are Shopify merchants. We are a Shopify Plus certified app partner.

We use Polaris to build our applications which span standalone web, a mobile app, a POS embedded app, and a soon to release web embedded app.

We use Polaris across all these surfaces because we want to be good ecosystem citizens, but we are a small team, so we build and maintain a single app for all of these surfaces.

We also like Polaris because it "just works", is accessible, and covers the most important UI components that most apps need. Many of the deprecated components would fall into that category.

If you move forward with this change, we will have no choice but to migrate away from Polaris because we need to have a stable and complete UI lib to do our jobs well. It won't be a good use of our team's time to build a Polaris version of our app just to embed in Shopify if we use a different UI lib outside Shopify. This would mean that any surface embedded in Shopify that requires Polaris will have fewer features because we will now have to support embedding just to check a box for "built for Shopify" certification and similar.

If you interviewed the merchants we share (many of whom are some of your largest merchants), I guarantee you that the changes being made here would not fall into their top 10 or even top 100 list of concerns.

I completely understand that you don't want app devs using some of these components when embedded because it degrades the UX in Shopify admin, but that seems solvable with stricter guidelines for app approval and built for Shopify certification. I would suggest a separate section called "for standalone apps" or an automatic warning or error when rendering those components when they are embedded in Shopify.

I know this is a long post, but I'm hoping that it helps exemplify how important it is to us that these components are maintained. You are building, not just for Shopify and embedded apps, but also an entire ecosystem beyond that which relies on you as a platform.

Lastly, I want to request that if you are committed to supporting that ecosystem, that you consider adopting an RFC process and/or design partner program to work with different stakeholders in the ecosystem to build for everyone. I love what @ryanflorence and @mjackson have done with their open processes, and I believe Polaris would benefit from a similar approach.

[yuvrajharod]

I just traced these changes to the following PR: https://github.com/Shopify/polaris/pull/11382

Am I correct in understanding that your goal is just to add friction? If so, I believe there must be better ways to do this.

I'm curious if @alex-page, @craigbrunner, or @themarkappleby chatted with anyone in the ecosystem before moving forward with this change.

My intention is only to provide the perspective of a company that is in the Shopify ecosystem:

I'm one of the cofounders of Endear, a CRM and clienteling solution for consumer brands, many of whom are Shopify merchants. We are a Shopify Plus certified app partner.

We use Polaris to build our applications which span standalone web, a mobile app, a POS embedded app, and a soon to release web embedded app.

We use Polaris across all these surfaces because we want to be good ecosystem citizens, but we are a small team, so we build and maintain a single app for all of these surfaces.

We also like Polaris because it "just works", is accessible, and covers the most important UI components that most apps need. Many of the deprecated components would fall into that category.

If you move forward with this change, we will have no choice but to migrate away from Polaris because we need to have a stable and complete UI lib to do our jobs well. It won't be a good use of our team's time to build a Polaris version of our app just to embed in Shopify if we use a different UI lib outside Shopify. This would mean that any surface embedded in Shopify that requires Polaris will have fewer features because we will now have to support embedding just to check a box for "built for Shopify" certification and similar.

If you interviewed the merchants we share (many of whom are some of your largest merchants), I guarantee you that the changes being made here would not fall into their top 10 or even top 100 list of concerns.

I completely understand that you don't want app devs using some of these components when embedded because it degrades the UX in Shopify admin, but that seems solvable with stricter guidelines for app approval and built for Shopify certification. I would suggest a separate section called "for standalone apps" or an automatic warning or error when rendering those components when they are embedded in Shopify.

I know this is a long post, but I'm hoping that it helps exemplify how important it is to us that these components are maintained. You are building, not just for Shopify and embedded apps, but also an entire ecosystem beyond that which relies on you as a platform.

Lastly, I want to request that if you are committed to supporting that ecosystem, that you consider adopting an RFC process and/or design partner program to work with different stakeholders in the ecosystem to build for everyone. I love what @ryanflorence and @mjackson have done with their open processes, and I believe Polaris would benefit from a similar approach.

I agreee with what Jinesh just mentioned here. Working as a small team, it's pretty hard to use different UI libs, providing the best merchant ux is only goal all developers have and we go beyond our abilities to deliver that. Making it hard is bad, it was easy already, so why break something which was working before.

Special focus on the built for shopify thing as that's a requirement when you even consider those.

Again we understand you want them to be used in a certain way. We're more than happy to adhere them but can we please follow a better way of doing that? A warning or rejecting the app application would have been a much better way clearly, and also deprecating without any prior notice and hiding the doc altogether was another unprofessional step by the team. Atleast let the doc be there so we can work with what we have...

[alex-page]

Hey folks thanks for the feedback. I am going to share context here on why this decision was made and I cannot promise this is a change we will undo in the future. Please continue sharing feedback it's super helpful.

I'm curious if @alex-page chatted with anyone in the ecosystem before moving forward with this change

No. For many years we have maintained AppBridge and Polaris components side by side. The confusion this has caused our developers and the poor quality experiences we have built due to this has created a need to make an intentional change. We know this would be a challenging decision and one that would be frustrating to some users. Polaris is an open source UI library used for many different purposes today. The intention of this change is to narrow the scope of Polaris to focus on helping Shopify developers build the best applications and channels possible.

One of the most common issues when building a Shopify application or channel is that developers incorrectly use the Polaris components (<Modal> <Toast>, <ContextualSaveBar>...). Using the Polaris library causes the components to render incorrectly which reduces the quality of the experience for our merchants. This happens because the App Body <iframe> limits the position components can be rendered in. To ensure that our community builds the highest quality experiences for merchants we are directing you to use AppBridge which ensures these components are rendered in the correct place.

If I want to continue using these components, What do I need to do?

If you are building a Shopify application or channel I would start by replacing the deprecated components with AppBridge. The API's are different but the user experience is the best it can be for our merchants. The App Bridge Modal API allows children to be rendered in with the src property which is a URL to a HTML page to render inside the <Modal>. This is quite different to how children can be added with JSX in Polaris today.

If you are not building a Shopify application or channel I would recommend copy pasting the component code from Polaris and adding it to your application. In the future these components will be removed and they will always be accessible in git history in the Polaris repository.

Can the documentation for Modal, Frame, Loading, Navigation and Toast be brought back on the Shopify Polaris website?

I will talk to the team this week and make a decision on what documentation could be added back to the Polaris website. To set expectations this would likely be the highly used components (my gut feeling is it would probably be <Toast> and <Modal> only).

My opinion is that we need to direct developers to AppBridge documentation. Unlike <LegacyCard> the documentation lives on a different website. Maintaining the old documentation is going to misdirect developers to build the wrong solutions. If you absolutely have to read the old documentation right now it is available in git history.

Even if you want to deprecate, you can do that and we will consider upgrading with a deadline in mind

These components can still be used today. We will update developers with a timeline for removal from the library soon. See this as the first initial nudge that these components should be replaced.

[mesija]

Hi @alex-page , the issue of @shopify/app-bridge-react support and its relocation to the "Previous versions" section seems to have slipped through the cracks. I would like to understand what your plans are to understand and rewrite the code of modal windows for the react version or consider another option right away? It would be nice not to rewrite the code twice.

Thanks.

[alex-page]

@mesija sorry I should have included this in my response.

I have asked the app bridge team to clarify what is happening there. My understanding is that nobody should have to rebuild their application in Remix (even though we are big fans of the framework) and that AppBridge is a supported library. I want their team to chime around the specific reasons why it is in "Previous versions" as I don't want to respond with misinformation.

[SinXie]

My project doesn't exist on shopify page

Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps

This project is a private app of my Shopify store, which can open a new page. I hope the interaction and ui of this page are consistent with Shopify admin.

[SinXie]

My project doesn't exist on shopify page

Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps

This project is a private app of my Shopify store, which can open a new page. I hope the interaction and ui of this page are consistent with Shopify admin.

Then I wondered if Shopify would later have a ui library for such apps. Because the previous Polaris fits my app scenario very well.

[charlesdobson]

Hi all,

Just wanted to touch on the comments about the @shopify/app-bridge-react package. It's not deprecated and we're still supporting it. We'll be releasing a new version soon which includes React wrappers for components like the new ui-modal that allows you to write custom DOM content within the Modal instead of just content strings or an iframe src. Once that's released, all of the main App Bridge docs will have the React wrappers alongside them again.

cc: @mesija @lehoangnnx

[jineshshah36]

Hey folks thanks for the feedback. I am going to share context here on why this decision was made and I cannot promise this is a change we will undo in the future. Please continue sharing feedback it's super helpful.

I'm curious if @alex-page chatted with anyone in the ecosystem before moving forward with this change

No. For many years we have maintained AppBridge and Polaris components side by side. The confusion this has caused our developers and the poor quality experiences we have built due to this has created a need to make an intentional change. We know this would be a challenging decision and one that would be frustrating to some users. Polaris is an open source UI library used for many different purposes today. The intention of this change is to narrow the scope of Polaris to focus on helping Shopify developers build the best applications and channels possible.

If you don't talk to any of the developers using your library in the ecosystem, how do you know that you are actually solving their problems? We are Shopify developers. We are a Plus certified app partner and pay a lot of money to shopify for the platform capabilities they provide. Polaris falls into this bucket, and it seems unreasonable to make a major change like this & drop all the docs without talking to Shopify developers like us.

One of the most common issues when building a Shopify application or channel is that developers incorrectly use the Polaris components (<Modal> <Toast>, <ContextualSaveBar>...). Using the Polaris library causes the components to render incorrectly which reduces the quality of the experience for our merchants. This happens because the App Body <iframe> limits the position components can be rendered in. To ensure that our community builds the highest quality experiences for merchants we are directing you to use AppBridge which ensures these components are rendered in the correct place.

This is why I suggested the alternatives. These components could easily detect when they are rendered in Shopify admin embedded and warn or error.

If I want to continue using these components, What do I need to do?

If you are building a Shopify application or channel I would start by replacing the deprecated components with AppBridge. The API's are different but the user experience is the best it can be for our merchants. The App Bridge Modal API allows children to be rendered in with the src property which is a URL to a HTML page to render inside the <Modal>. This is quite different to how children can be added with JSX in Polaris today.

To be clear, we are a Shopify application, we are a Shopify channel, and we are a Shopify POS application. We are literally all of these things.

If you are not building a Shopify application or channel I would recommend copy pasting the component code from Polaris and adding it to your application. In the future these components will be removed and they will always be accessible in git history in the Polaris repository.

This seems like a band-aid at best. Over time, you will almost definitely end up breaking compat with copy-pasted-code here.

Can the documentation for Modal, Frame, Loading, Navigation and Toast be brought back on the Shopify Polaris website?

I will talk to the team this week and make a decision on what documentation could be added back to the Polaris website. To set expectations this would likely be the highly used components (my gut feeling is it would probably be <Toast> and <Modal> only).

My opinion is that we need to direct developers to AppBridge documentation. Unlike <LegacyCard> the documentation lives on a different website. Maintaining the old documentation is going to misdirect developers to build the wrong solutions. If you absolutely have to read the old documentation right now it is available in git history.

Even if you want to deprecate, you can do that and we will consider upgrading with a deadline in mind

These components can still be used today. We will update developers with a timeline for removal from the library soon. See this as the first initial nudge that these components should be replaced.

I would again implore you to reconsider this decision. I don't believe the problems you are trying to solve are incompatible with keeping this library fully featured.

[mesija]

@alex-page @charlesdobson , thank you for your quick response.

Our team is very pleased that the bridge support for React will be relevant, we have already ordered a celebratory pizza on this occasion 🎉

Of course, we have nothing against Remix, but still, rewriting an application on a new framework is not an easy task :)

[vixalien]

Hello! I was indeed confused by this change too. There was nothing in the changelog and now currently many components' documentation are missing and they are all marked as deprecated.

I understand that Polaris was primarily made for Shopify apps, but there are some of us who use it to create completely external apps that don't integrate with Shopify in any way, as supported by the LICENCE file:

external, stand-alone applications that do not embed directly inside Shopify, the rights granted above may only be exercised to develop and distribute applications that are dissimilar and visually distinct from Shopify products and services (including the internal administration page of a Shopify merchant store), as determined by Shopify in its sole discretion.

Now, if I understand this correctly, these components are being removed in favour of similar components already in the Shopify AppBridge library.

AppBridge seems to be a proprietary and closed-source library that only work within the Shopify Admin, as evidenced from the following text from the AppBridge website:

App Bridge components don't render as part of the app's component hierarchy. They are React-like wrappers around JavaScript messages that communicate with the Shopify admin. The Shopify admin does the UI rendering.

With this change, does that mean that open source developers that develop external websites that don't integrate with Shopify will cease to be supported? Does that mean that Polaris is now only for Shopify apps? Will the clause granting that access to external developers in the licence get removed? I'm really confused and would like to gently ask for clarification.

[errolgr]

I came to this issue after noticing the deprecation of key components like Toast and Modal while building a new app on Shopify. My perspective on this issue is shaped by my experience with App Bridge. Initially, I felt that App Bridge started off as a utility library aimed at helping us, Shopify app developers, to integrate more seamlessly and effectively into Shopify. But somewhere along the line, it seems to have diverged from being a facilitative tool to becoming a limiting factor, especially with the recent deprecations. These changes appear to restrict the flexibility and functionality we had come to rely on, rather than enhancing our ability to develop robust Shopify applications.

No. For many years we have maintained AppBridge and Polaris components side by side. The confusion this has caused our developers and the poor quality experiences we have built due to this has created a need to make an intentional change. We know this would be a challenging decision and one that would be frustrating to some users. Polaris is an open source UI library used for many different purposes today. The intention of this change is to narrow the scope of Polaris to focus on helping Shopify developers build the best applications and channels possible.

The decision to deprecate these components, under the pretext of reducing confusion between AppBridge and Polaris components, feels like an unnecessary forceful measure against the developer community. While the intent to streamline might be well-meant, the actual execution overlooks the immediate needs and investments of developers like myself.

If you are building a Shopify application or channel I would start by replacing the deprecated components with AppBridge. The API's are different but the user experience is the best it can be for our merchants. The App Bridge Modal API allows children to be rendered in with the src property which is a URL to a HTML page to render inside the . This is quite different to how children can be added with JSX in Polaris today.

it's important to note that this doesn't cater to the diverse use cases of the broader developer community. The limitations of the App Bridge Modal API, as opposed to the flexibility offered by JSX in Polaris, can significantly hinder developers in crafting effective and user-friendly solutions. This change, therefore, not only limits the tools available to developers but also potentially impacts the end-user experience negatively.

I am currently maintaining an existing application that uses these now-deprecated components and am developing a new app using the App Bridge. However, the alternatives provided through the App Bridge API fall short of the usability and functionality that the original Polaris components offered.

If you are not building a Shopify application or channel I would recommend copy pasting the component code from Polaris and adding it to your application. In the future these components will be removed and they will always be accessible in git history in the Polaris repository.

Furthermore, the advice to replicate Polaris component code in our applications is a short-sighted and impractical workaround. This approach fails to consider the long-term requirements of software maintenance, such as regular updates and security, which are critical aspects of using a managed library. It is a disservice to the principles of sustainable software development and does not adequately support the ongoing needs of the Shopify developer community.

[alex-page]

Thanks for all the feedback. There is a lot here and we are working through it.

One of the biggest issues was not being able to access the deprecated component documentation. The initial change to direct application developers to App Bridge was too harsh. To address this I have added back the component documentation to all of the newly the deprecated components https://github.com/Shopify/polaris/pull/11493.

You can view the documentation for all deprecated components:

• https://polaris.shopify.com/components/deprecated/contextual-save-bar
• https://polaris.shopify.com/components/deprecated/frame
• https://polaris.shopify.com/components/deprecated/loading
• https://polaris.shopify.com/components/deprecated/modal
• https://polaris.shopify.com/components/deprecated/navigation
• https://polaris.shopify.com/components/deprecated/toast
• https://polaris.shopify.com/components/deprecated/top-bar

[vixalien]

Thanks, @alex-page, for hearing out the community.

Hopefully, a solution that provides an alternative to App Bridge for non-Shopify websites can be discussed next.

[daviareias]

There's currently 0 information on how to integrate React with the Webcomponents being used by Appbridge, I kinda did, but because they contain an isolated shadowRoot, you get virtually a lot less customization, you can't even get a destructive button on the new ui-modal tag

[mesija]

We ran into a problem while planning our migration to App Bridge Modal. Our application relies on modules that run in modal windows, such as a resource picker. This is an extended version of it that allows you to select a lot of different resources such as orders, pages, metafield definitions, etc. And it seems that this is a good practice, given the similar things in the Shopify admin panel and the App Bridge itself. But it seems that the current modal API of App Bridge is not able to meet our needs without using complex iframes and a lot of magic and crutches.

We're not sure how this aligns with your new approach to app development. If we could embed JSX content in modal elements, that might solve the problem, but we don't see a clear solution to this problem right now.

@charlesdobson mentioned React wrappers for modal elements, but there are still doubts about the effective use of JSX components. If we can't use the same Polaris components in new modalities, it won't allow us to implement our own resource picker. It seems that the only option is to create our own modal implementation, which adds complexity.

Moreover, the return to local modal versions seems inevitable, so it seems that the problem you are trying to solve with these changes may remain, because local versions of modal windows seem to be the only viable solution for this functionality.

We would be grateful for your thoughts and recommendations on this, as we want to comply with Shopify's requirements, but at the same time we can't afford to abandon our own implementations of the same resource pickers as it is an important part of the application.

Thanks ^^

[patryk-smc]

Removal of those components makes studying user session recordings harder, as those App Bridge components cannot be recorded by tools like LogRocket or Hotjar. Especially Modal.

[Arlen22]

As someone who is using this for a completely unrelated project, I'm a bit concerned, because I have just enough experience with user interfaces to appreciate being able to offer my own customers a consistent user experience across all kinds of platforms throughout an entire ecosystem.

I can't possibly imagine that the only intended use case for Polaris is inside an IFrame on the Shopify website, especially since the Shopify Admin itself is literally Polaris.

I have no idea what AppBridge is and how to use it properly in a standalone application, or if that's even possible, but I'm starting to get the feeling it isn't. At the very least, a page explaining what all is going on and how to migrate for both Shopify Admin and standalone projects, or even just a link to this issue, would probably be a good idea.

Also, make sure you're importing Modal, not Model. It's still available in v12. You're welcome.

[jineshshah36]

@alex-page It would be great to have a decision one way or another. We are now viewing any further investment in Polaris as a risk since we don't know if we can safely assume Polaris will be designed for anything besides the embedded use-case. I want to make sure I have clear guidance to offer my team. I understand that Shopify has its own priorities, but we just want to know where you are going to land so we don't further incur tech debt on Polaris.

I'll make my last case. You're not just here to serve what Shopify wants. All of us in the ecosystem pay Shopify one way or another for access to not just the APIs, but also this UI library. That should come with some responsibility of good stewardship on your end, and that means supporting the larger ecosystem's needs.

[vixalien]

While most of the comments on this page have been understandably negative, I would like to appreciate @alex-page and the team for listening to us, and acting in the favour of the community so far. Thank you!

[alex-page]

Hey folks. We are listening. This is a challenge and we are figuring out next steps carefully. Sorry for the delay.

[mesija]

@alex-page, thank you for communicating with the community, hopefully we will come to a solution that is acceptable to everyone. After all, Polaris is a very good library that really simplifies integration with Shopify, and we are all interested in its further development ^^

[Michael-Gibbons]

I am experiencing the same issues. Callbacks not working within Polaris modals, no information on how to integrate/replace old modals with the app bridge modal, and the app bridge ui modal not working either.

The Shopify admin itself uses modals in countless places, it seems like every time I write an application in Polaris something gets deprecated that breaks my application with no notice forcing me to rewrite it without a robust alternative.

It makes no sense that these components are being passed off to app bridge. The justification is that these components are meant for "internal use only" yet there are countless applications using them. So obviously they have value to frontend app developers. If the components themselves have issues that are a pain to support related to them then that is an error on shopify's end and the components should be re-written in Polaris.

The only justification I can think of for passing these off to app bridge is since these are floating elements they are technically outside the scope of the embedded app and therefore outside of polaris' domain, but that seems like a css/visual issue rather than one that should be enforced on developers with no warning. In fact one of the "solutions" mentioned above is to recreate the modal yourself, so it doesn't seem that accessibility is too much of a concern.

I respect Shopify's desire for us to write robust applications that fit in with the Shopify Admin and am willing to put in the work to do so. Please respect our desire to not have our time and work wasted.

Thank you for your work and communication I understand this is a difficult situation for you to be in.

[Michael-Gibbons]

@alex-page Can you help me understand why these are considered "incorrect" usages of these components?

On the just Customer Admin page there are at least 9 different modals

Here is my application which is has actions that are no longer functional since they've apparently been deemed an "incorrect usage"

This really seems like its an internal Shopify problem being passed off to us.

[pnmcosta]

fyi, I only noticed this major issue cause the Frame component now has a border-inline-end, which was introduced here https://github.com/Shopify/polaris/blame/2c53d64762ff545f56787e932e0b0935c45b5fdc/polaris-react/src/components/Frame/Frame.module.scss#L227 only last week.

as per https://github.com/Shopify/polaris/issues/11460#issuecomment-1904035397 if these will eventually be ported into the react package, wouldn't it make sense to hold on to deprecating them (or making style changes like above) until they are?

[renatopiermarini]

Hey folks thanks for the feedback. I am going to share context here on why this decision was made and I cannot promise this is a change we will undo in the future. Please continue sharing feedback it's super helpful.

I'm curious if @alex-page chatted with anyone in the ecosystem before moving forward with this change

No. For many years we have maintained AppBridge and Polaris components side by side. The confusion this has caused our developers and the poor quality experiences we have built due to this has created a need to make an intentional change. We know this would be a challenging decision and one that would be frustrating to some users. Polaris is an open source UI library used for many different purposes today. The intention of this change is to narrow the scope of Polaris to focus on helping Shopify developers build the best applications and channels possible.

One of the most common issues when building a Shopify application or channel is that developers incorrectly use the Polaris components (<Modal> <Toast>, <ContextualSaveBar>...). Using the Polaris library causes the components to render incorrectly which reduces the quality of the experience for our merchants. This happens because the App Body <iframe> limits the position components can be rendered in. To ensure that our community builds the highest quality experiences for merchants we are directing you to use AppBridge which ensures these components are rendered in the correct place.

If I want to continue using these components, What do I need to do?

If you are building a Shopify application or channel I would start by replacing the deprecated components with AppBridge. The API's are different but the user experience is the best it can be for our merchants. The App Bridge Modal API allows children to be rendered in with the src property which is a URL to a HTML page to render inside the <Modal>. This is quite different to how children can be added with JSX in Polaris today.

If you are not building a Shopify application or channel I would recommend copy pasting the component code from Polaris and adding it to your application. In the future these components will be removed and they will always be accessible in git history in the Polaris repository.

Can the documentation for Modal, Frame, Loading, Navigation and Toast be brought back on the Shopify Polaris website?

I will talk to the team this week and make a decision on what documentation could be added back to the Polaris website. To set expectations this would likely be the highly used components (my gut feeling is it would probably be <Toast> and <Modal> only).

My opinion is that we need to direct developers to AppBridge documentation. Unlike <LegacyCard> the documentation lives on a different website. Maintaining the old documentation is going to misdirect developers to build the wrong solutions. If you absolutely have to read the old documentation right now it is available in git history.

Even if you want to deprecate, you can do that and we will consider upgrading with a deadline in mind

These components can still be used today. We will update developers with a timeline for removal from the library soon. See this as the first initial nudge that these components should be replaced.

So basically the only solution I see is downgrading to an older version of polaris with modal and else or completely move away from polaris to something that doesn't introduce weekly breaking changes. I was part of Boost (huge app) and I have 2 apps right now doing well, we'll keep them on the older version.

[mesija]

@renatopiermarini this seems to be the only logical solution at the moment, and we have also stopped trying to update the version until Shopify makes a final decision. And then, depending on what their decision will be, either using new versions of modals from Polaris or something custom, because now everything indicates that the new version of modals will not be viable and too complicated to use... unfortunately :(

[yuvrajharod]

To the folks at shopify: this really is a huge issue and it massively limits our capacity to customize the code when using these components. I'd personally prefer to bring the older component's code into our project and customize it further to use it as per needs of our project, I've tried working with the newer components and have realized that's not probably the way we'd wanna go.

I just wanna convey that the newer methods/components seems a downgrade rather than an upgrade when it comes to dev experience. I hope this insight will give you better understanding and ways to build the tools in the future, until that point, we'll happily use custom components!

[charlesdobson]

Hi all,

We've just released App Bridge React v4 which includes a React Modal component that accepts custom content (including React and Polaris components).

Documentation is here: https://shopify.dev/docs/api/app-bridge-library/react-components/modal

Migration guide if you're coming from App Bridge React 3.x.x is here: https://shopify.dev/docs/api/app-bridge/migration-guide

[mesija]

Hi @charlesdobson. This is very good news.

We've tried this component in the field and it seems to work with errors even on the basic example from the manual.

To exclude the possible influence of other modules or styles, we used a completely empty react project where only @shopify/app-bridge-react was connected from all the libraries.

Unfortunately, we were unable to get this component to work stably, in chrome it seems to be unable to determine the height of the content, and always has the maximum size. In Firefox, for some reason, when you first open it, the content is placed outside the modal window.

With all the desire, this cannot be used in a production build.

Maybe we are doing something wrong?

Here is a small test record: https://share.vidyard.com/watch/jxzstMvgJpFztiNXX62dP5

[yuvrajharod]

While I was happy with the launch of App bridge react hoping that it will resolve all the current issues, it seems to have bought new sets of issues. I can confirm what @mesija just mentioned is correct and I am facing the same issues on my end as well. Do we have an update on when can we expect this to be resolved? @charlesdobson

[mesija]

@charlesdobson We also noticed that there is a certain gap in the functionality of the Contextual Save Bar API. It fully automatically tracks changes in the form, and we could not find in the method documentation how to control this value. That is, in the current implementation, we cannot be sure whether the save bar will behave correctly with our form, whether it will see all the changes as we expect.

This is quite strange, because then we can't fully control this component as we did in previous versions of App Bridge, where its behavior was more stable and predictable.

Maybe we just couldn't find it in the documentation, but... :)

[charlesdobson]

Hi @mesija and @yuvrajharod, we've identified the problem with the height calculation and we're shipping a fix for this shortly.

---

@mesija If you could, please create an issue in https://github.com/Shopify/shopify-app-bridge so that we can track it. There are a couple of other Contextual Save Bar issues there at the moment that we're looking into, so grouping everything together would be helpful.

[mesija]

I'm updating the information about modal windows, the above-mentioned problem with the window size has been fixed, now it works correctly :)

[mesija]

Hello everyone,

I would like to share feedback on our process of transitioning to App Bridge version 4.

In short, it cannot fully replace version 3 as it has less functionality. Most importantly for us, the new Max Modal, intended to replace the full-screen mode, does not work properly as it has all the accompanying modal window issues. Therefore, we are currently trying to make the most of App Bridge in our project, but specifically, its version 3 which is stable and offers good functionality.

More details on key issues:

1. The new modal window has many compatibility problems with modules that work with text selection and drag-and-drop. In our project, we couldn't make the "dnd kit" and CKEditor work inside the modal window, while outside it, they work without problems.
2. Max Modal != full screen. This is a significant issue because Max Modal inherits all the compatibility problems of modules, and if you use this mode to display your entire app in full-screen mode, the above-mentioned modules don't work across the whole page as they are technically inside a modal window.
3. Nesting problem. Even if you manage to open your app using Max Modal and everything works, you won't be able to open another modal window, for example, to confirm the deletion of an item because only one modal window can be open at a time, and you either need to exit "full-screen mode" or use a different approach, which is very problematic.

Conclusion: We spent a lot of time researching the possibility of transitioning to the new version of App Bridge and, unfortunately, concluded that it is not feasible due to a large number of technical issues. The new modal windows deserve special attention; they have numerous technical problems and serve as a breeding ground for bugs and limitations.

Therefore, we will continue to use the local version of modals and would be very grateful if the old versions of components like Loading, Modal, Toast, and ContextualSaveBar were available in regular Polaris as it allows for writing adaptive code that works both in embedded apps, where we use App Bridge versions of these components, and locally for development and internal tools. This really simplifies development and makes Polaris universal.

The subjective opinion of our team is that the modal windows in App Bridge version 4 are one of the worst solutions we have seen in our entire time working with Polaris. We very much hope that the Shopify team will take the community's opinion into account.

[fabregas4]

We've just released App Bridge React v4 which includes a React Modal component that accepts custom content (including React and Polaris components).

Is it just me or does this modal take 1-2 seconds to load each time you open it? It pops up and shows a spinner for a second or two, even when the only content within the modal is a bit of static text! Makes for a terrible user experience.

Nevermind the thought of using it as a confirmation dialog - no way.

Though maybe it's just me... Can anyone share their experience?

[daviareias]

We've just released App Bridge React v4 which includes a React Modal component that accepts custom content (including React and Polaris components).

Is it just me or does this modal take 1-2 seconds to load each time you open it? It pops up and shows a spinner for a second or two, even when the only content within the modal is a bit of static text! Makes for a terrible user experience.

Nevermind the thought of using it as a confirmation dialog - no way.

Though maybe it's just me... Can anyone share their experience?

I get the same experience on Resource Picker, it takes a lot of time to load.

[fabregas4]

I get the same experience on Resource Picker, it takes a lot of time to load.

Same, though I just assumed it was doing a bit of work to get the resources. Maybe it's just the Modal being slow.

[fabregas4]

@charlesdobson Any thoughts on the last couple of comments?

It seems like even displaying some static text within the react Modal causes a complete load of the whole page on which it resides, so you always see a loading spinner for a couple of seconds before content is shown.

That can't be intended, can it?

It virtually makes the Modal unusable as a confirmation dialog or just a plain poor user experience in many other use cases.

It seems to be covered here - https://github.com/Shopify/shopify-app-bridge/issues/314 - but I'm surprised it's not getting more attention from the team.

[charlesdobson]

Hi @fabregas4,

This is currently expected and the team is aware of the issue. We're rendering the modal on the Shopify Admin side, so it takes time (1-2 seconds as you noticed) to open up the iframe and move the contents.

We're working on preloading the modal contents to fix this experience.