Forge UI Kit vs. Custom UI: The Honest Decision Guide

When your team is planning a new Forge app, you’ll face a fundamental question early on: UI Kit or Custom UI? Both approaches are officially supported by Atlassian, both have their place – and both are regularly chosen for the wrong reasons. This article is intended to help you make the decision on solid footing.

What’s What?

UI Kit (previously known as UI Kit) is Atlassian’s own component system for Forge apps. Developers build their interface from a predefined set of React components, which Atlassian renders for you. There’s no separate frontend bundle to ship and no external context to wire up – the React reconciler runs client-side in the browser, and the design automatically follows the Atlassian Design System.

Custom UI gives teams full control: the app interface is developed as a standalone web app that runs in an iframe inside Jira or Confluence. Technology choice, layout, and styling are largely unrestricted, with React being the de facto standard.

The difference is not merely technical. It significantly determines how much effort an app requires across its entire lifecycle – from the first line of code to year three of operation.

UI Kit: Strengths and Typical Use Cases

The biggest advantage of UI Kit is speed. Teams building an app with standard interaction patterns – forms, lists, panels, configuration pages – will reach a working result quickly. There’s little overhead in the initial setup, no frontend build pipeline to configure, and the result looks like Atlassian because it is Atlassian.

This pays off in the long run as well. When Atlassian updates its Design System, UI Kit follows automatically. Your team doesn’t need to manually catch up, and there’s no risk of incompatibilities between your own components and the platform UI.

Typical use cases:

Admin and configuration pages
Simple data entry and display
Issue panels and glances in Jira
Standard dashboards built on UI Kit’s native chart components
Internal tools where look-and-feel consistency matters

Custom UI: Strengths and Typical Use Cases

Custom UI is the right choice when UI Kit reaches its limits, or when the app has requirements from the outset that can’t be met with a predefined component set.

This applies above all to data visualizations that go beyond UI Kit’s native chart components – think dedicated charting libraries, custom SVG rendering, or highly interactive graphics. It also applies to apps with highly individualized interaction patterns, multi-step workflows, or embedded editors. Anyone wanting to embed a full single-page application in Confluence or Jira has no alternative to Custom UI.

Another factor is existing code. If a team already has a web app or component library to be brought into a Forge app, Custom UI is the natural path. The effort of rebuilding from scratch using UI Kit would exceed the iframe overhead.

Typical use cases:

Dashboards and visualizations beyond UI Kit’s native charts
Apps with complex, multi-step forms or workflows
Embedding existing web applications
Scenarios where a highly individualized design is required

The Limitations of Both Approaches

Neither approach is without drawbacks. UI Kit offers a limited component selection. What isn’t in the catalog can’t easily be added. Free CSS is not possible – styling is handled strictly through Atlassian’s constrained token system (xcss). Certain interaction patterns that are taken for granted in modern web apps can’t be implemented with UI Kit, or only with considerable effort. Teams that hit these limits mid-development face a real problem: switching to Custom UI essentially means rebuilding the entire frontend layer.

Custom UI brings its own costs. The iframe approach means the app and platform run in separate contexts, with communication handled via the Forge Bridge API (@forge/bridge). Since the iframe and your JavaScript bundles must be loaded and parsed on initial render, performance is not a given – active optimization is required.

Security overhead is also not to be underestimated: every external connection, every font, and every script must be explicitly declared through the Content Security Policy (CSP) in the app manifest (manifest.yml). Overall, the initial effort is higher: build pipeline, deployment configuration, component library – all of it needs to be set up and maintained.

That said, your team doesn’t have to start from scratch with Custom UI either: Atlassian’s official components (@atlaskit) are available via npm to help maintain visual consistency. Setup and maintenance of those libraries, however, remain your responsibility.

Typical Pitfalls

“We’ll go with Custom UI – that gives us more control.” True, but control comes at a cost. Teams that choose Custom UI primarily because it feels more professional or flexible tend to underestimate the maintenance burden. An app that nobody wants to touch anymore because the setup became too complex is not a win.

“UI Kit is fine for now.” Sometimes “for now” becomes the foundation on which far more gets built than originally planned – and teams then hit limits after a few months that force a rebuild. Anyone with foreseeable complex UI requirements should plan for that from the start.

Can hybrid approaches combine the best of both? It’s entirely possible – and often sensible – to combine UI Kit and Custom UI within a single app. Different modules can use different UI technologies. A practical example: a configuration page in UI Kit, a complex dashboard panel in Custom UI. This allows UI Kit to be used where it’s sufficient, and Custom UI only where it’s genuinely needed – keeping overall maintenance low without sacrificing flexibility.

A hybrid approach cannot, however, replace the underlying decision. Combining both technologies means your team must understand and maintain both. The increased complexity should be acknowledged clearly – it’s not an argument against a hybrid approach, but the team should choose it deliberately rather than as a way to avoid making a clear call.

Decision Guide: 5 Questions Before You Choose

Before making the decision, it’s worth working through the following questions concretely.

What UI requirements does the app have that UI Kit can’t meet? Does the app need visualizations beyond UI Kit’s native charts, an embedded editor, drag and drop, or other interaction patterns not available in the UI Kit component catalog? If not – if the app essentially consists of forms, lists, panels, and simple actions – UI Kit is likely sufficient, regardless of how complex the business logic behind it may be.

Who is responsible for visual consistency with the Atlassian platform? With UI Kit, Atlassian handles this automatically. With Custom UI, that responsibility lies with your development team: the Atlassian Design System is openly available, but your team must actively apply it.

What frontend expertise does your team have? UI Kit is accessible even to teams with limited React experience. Custom UI requires someone on the team who can handle web development professionally – build tools, bundlers, CSP configuration in the manifest – and who is prepared to own that long-term.

Who will maintain the app in two years? This is a question that often goes unasked during initial planning. Custom UI apps require ongoing upkeep. If the team changes or the app moves to a different area of the organization, even a well-structured Custom UI project can become a liability. A straightforward UI Kit project much less so.

Is there existing code to be reused? If web components or entire applications already exist and should be carried forward – for example, to bring an existing solution into Forge – Custom UI is generally the more pragmatic starting point.

A Deliberate Decision

There is no universally correct answer. Framing UI Kit as the “easy” option and Custom UI as the “professional” one misses the point: both are legitimate tools with different strengths and costs.

What matters is that your team makes the decision deliberately – based on concrete requirements, a realistic assessment of your own capacities, and a clear view of the app’s entire lifecycle.

Do you want to build a Forge app and need support choosing the right architecture from the start? Whether you’re evaluating UI Kit, Custom UI, or a hybrid approach – our experienced Atlassian professionals will help you from strategic planning to implementation.