# Choosing Between Drop-in and Elements

ODUS Checkout SDK offers two integration paths: **Drop-in** and **Elements**. Both use the same backend APIs, handle 3DS authentication, and support the same payment methods — they differ in how much UI control you retain.

This page helps you decide which path fits your project.

Whichever path you choose, use `@odus/checkout` `1.12.0` or later before 4 November 2026. Version `1.12.0` is the first SDK release that calls only API v2. SDK versions that call API v1 routes stop working when v1 stops being served.

## Comparison

| Dimension                 | Drop-in                                                            | Elements                                                                                   |
| ------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Time to first payment** | Minutes — one `mount()` call renders the full form                 | Hours — you build the layout, wire up submit, call `validate()` and `authorize()` yourself |
| **Customization level**   | Configuration-based (`appearance`, `layout`, `initialValues`)      | Unlimited — mount elements anywhere in your own markup                                     |
| **UI ownership**          | ODUS controls the form structure; you configure its look           | You own the form; ODUS provides isolated input fields                                      |
| **Styling**               | `appearance.styles` config object                                  | CSS custom properties via `applyTheme()` or per-element `setTheme()`                       |
| **Pay button**            | Built-in, activates automatically after `associatePayment()`       | You provide your own button and call `authorize()`                                         |
| **Validation**            | Automatic on submit                                                | Explicit — call `validate()` from your submit handler                                      |
| **Shadow DOM**            | Single shadow root for the entire form                             | Separate shadow root per element                                                           |
| **Maintenance effort**    | Low — SDK upgrades may introduce new UI improvements automatically | Moderate — layout changes are your responsibility                                          |
| **Design consistency**    | Guaranteed by the SDK                                              | Depends on your implementation                                                             |
| **Required imports**      | `@odus/checkout` + `@odus/checkout/styles`                         | `@odus/checkout/elements` (styles built-in)                                                |

## Decision Flowchart

Use this flowchart to narrow down the right integration for your use case:

<!-- -->

## When to Use Drop-in

Choose Drop-in when:

* You want the shortest path to accepting payments
* A standard card form layout is acceptable
* You prefer configuration over code for styling
* Your team does not have dedicated frontend engineers for the checkout page
* You want automatic UI improvements from SDK upgrades without code changes

## When to Use Elements

Choose Elements when:

* Your checkout page has a custom design that cannot be expressed through configuration alone
* You need to place input fields in non-standard positions (e.g., card input inside a multi-step wizard, email field in a header)
* You require programmatic control over validation timing and error display
* You want to build a checkout experience that matches your product's design system exactly

## Can I Switch Later?

Yes. Both paths share the same backend integration (`associatePayment`, `checkoutKey`, payment creation). Switching from Drop-in to Elements (or the reverse) requires only frontend changes — your backend stays the same.

tip

If you are unsure, start with Drop-in. You can move to Elements later without backend changes if you outgrow the configuration options.