Skip to main content
Version: Live

Styling and Managing States

This guide will walk you through the basics of styling your Pay Theory Fields and state management. You will learn how to style the text inputs and radio buttons using CSS and how to use the stateObserver.

Styling the Pay Theory fields​

To style the Pay Theory fields you can pass in a custom style object to the create function in our SDK. The style object accepts a fixed set of keys for each surface — text inputs (across default, success, and error states), the ACH account-type radio buttons, and the placeholder visibility flag. To style the hosted checkout button, pass style to button instead. See Style object. Any property not listed in the tables below is silently ignored.

paytheory.js
const STYLES = {
  default: {
    color: 'black',
    fontSize: '14px',
    fontFamily: 'Helvetica, Arial, sans-serif',
    padding: '10px',
    border: '1px solid #ccc',
    borderRadius: '4px',
    backgroundColor: '#ffffff',
  },
  success: {
    color: '#5cb85c',
    borderColor: '#5cb85c',
  },
  error: {
    color: '#d9534f',
    borderColor: '#d9534f',
  },
  radio: {
    width: 18,
    fill: 'blue',
    stroke: 'grey',
    text: {
      fontSize: '14px',
      color: 'grey',
      fontFamily: 'Helvetica, Arial, sans-serif',
    },
  },
  hidePlaceholder: false,
};

Top-level keys​

Keytypedescription
defaultobjectStyling applied to text inputs when not in success or error state. Accepts the field state properties.
successobjectStyling applied to text inputs that pass validation. Merged on top of default — any property not set here falls back to its default value.
errorobjectStyling applied to text inputs that fail validation. Merged on top of default — same fallback behavior as success.
radioobjectStyling for the ACH account-type radio buttons. See Radio object.
hidePlaceholderbooleanWhen true, the placeholder text in the input fields is hidden. Defaults to false.
success and error inherit from default

Properties set in default automatically apply to success and error too — you only need to override the keys that actually change between states (commonly color and borderColor).

Field state properties​

default, success, and error each accept the same 18 properties. All values are CSS strings; any other key is ignored.

Keytypedescription
colorstringText color. Accepts hex (#fff, #ffffff), rgb() / rgba(), hsl() / hsla(), named colors, CSS variables (var(--x)), transparent, inherit.
fontSizestringFont size. Numeric value with a unit (px, em, rem, %, vh, vw, pt, pc, in, cm, mm, ex, ch, vmin, vmax), or calc(...), var(...), auto.
fontFamilystringFont family stack. Capped at 100 characters.
lineHeightstringCSS line-height value.
paddingstringCSS padding shorthand. Same unit rules as fontSize.
marginstringCSS margin shorthand. Same unit rules as fontSize.
textAlignstringCSS text-align value (left, right, center, justify, start, end).
borderstringCSS border shorthand (e.g. '1px solid #ccc').
borderColorstringBorder color only. Same value rules as color.
borderRadiusstringCSS border-radius value.
backgroundColorstringBackground color. Same value rules as color.
boxShadowstringCSS box-shadow value.
outlinestringCSS outline shorthand.
widthstringCSS width. Same unit rules as fontSize.
heightstringCSS height. Same unit rules as fontSize.
transitionstringCSS transition shorthand.
opacitystringCSS opacity ('0'–'1').
webkitAppearancestringCSS -webkit-appearance value.

Radio object​

Styles for the ACH account-type radio buttons.

Keytypedescription
widthintWidth of the radio button, in pixels.
fillstringFill color of the selected indicator.
strokestringColor of the radio outline.
textobjectStyles for the radio labels. Accepts fontSize, color, fontFamily, fontWeight.

Additional styling​

To style the input parent div, provide your own CSS for the Pay Theory containers you create. This is best used to style the height, width, and border of the container.

Warning

Individual pay-theory-credit-card-number containers should be at least 340px wide, pay-theory-credit-card combined input should be 400px

src/custom.css
#pay-theory-credit-card-number,
#pay-theory-credit-card-exp,
#pay-theory-credit-card-cvv {
  height: 1.75em;
  border: solid 1px #ccc;
  border-radius: 5px;
  margin: 4px 0;
}

Using the stateObserver​

A stateObserver lets you keep an eye on changes to the state of hosted fields and react to them. It offers a mechanism to keep a look on things like field focus, if a field is empty or if there are any validation errors with the field. Each time the state of a text input changes, the stateObserver callback method is called.

src/paytheory.js
const stateHandler = state => {
  const cardState = state['card-number'];
  const cardField = document.getElementById('pay-theory-credit-card-number');
  if (cardState.isDirty) {
    cardField.classList.add('dirty');
  } else {
    cardField.classList.remove('dirty');
  }
  if (cardState.isFocused) {
    cardField.classList.add('focused');
  } else {
    cardField.classList.remove('focused');
  }
  if (cardState.errorMessages && cardState.errorMessages.length > 0) {
    cardField.classList.add('error');
  } else {
    cardField.classList.remove('error');
  }
};

window.paytheory.stateObserver(stateHandler);

Show fields as they load​

Each field's state also has iframeLoaded. It's false while the field loads and turns true once that field's iframe has loaded. Use it to swap a placeholder for the field as soon as it renders, instead of waiting for the readyObserver.

src/paytheory.js
window.paytheory.stateObserver(state => {
  const loaded = state['card-number'].iframeLoaded;
  document.getElementById('card-number-skeleton').hidden = loaded;
  document.getElementById('pay-theory-credit-card-number').hidden = !loaded;
});
Additional stateObserver functionality

For more details on stateObserver functionality

View stateObserver

Next steps​

Once your Pay Theory fields are stylized you will need to make sure Error handling is set up. Additionally you can further customize your Pay Theory fields by adding Cash and or ACH functionality.