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.
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.