Fix: Cannot Set Custom Border Color on UITextField in UIKit

Fix: Cannot Set Custom Border Color on UITextField in UIKit

Written by

in

Quick answer: UITextField doesn’t expose a borderColor property directly. Set the text field’s layer.borderColor, layer.borderWidth, and layer.cornerRadius after importing QuartzCore. Also set borderStyle to .none and layer.masksToBounds to true so the custom border renders correctly.

Why this happens

UITextField’s built-in borderStyle property only offers a handful of predefined styles (none, line, bezel, roundedRect). None of them let you choose a custom color. The visible border you see is actually drawn by the text field’s underlying CALayer, which does have borderColor, borderWidth, and cornerRadius properties. Until you configure that layer directly, any color you try to apply is ignored.

Another catch: if you leave borderStyle at its default (.roundedRect on iOS), the system draws its own border on top of your layer border, so your custom color never appears. You must switch borderStyle to .none and let the layer do all the drawing.

How to fix it

1. Configure the text field’s layer (recommended)

This is the standard, future-proof approach. It works in code or in a storyboard @IBInspectable extension.

import UIKit

final class ViewController: UIViewController {
    @IBOutlet private weak var emailField: UITextField!

    override func viewDidLoad() {
        super.viewDidLoad()
        styleTextField(emailField, borderColor: .systemBlue)
    }

    private func styleTextField(_ field: UITextField, borderColor: UIColor) {
        field.borderStyle = .none                 // 1. Disable system border
        field.layer.borderWidth = 1.0             // 2. Width in points
        field.layer.borderColor = borderColor.cgColor // 3. Custom color
        field.layer.cornerRadius = 8.0            // 4. Rounded corners
        field.layer.masksToBounds = true          // 5. Clip content to rounded rect
    }
}

Key points
– borderColor expects a CGColor, hence .cgColor.
– masksToBounds = true ensures the background and any subviews stay inside the rounded corners.
– Call this once (e.g., in viewDidLoad or awakeFromNib); no need to repeat in layoutSubviews.

2. Storyboard / XIB via @IBInspectable (designer-friendly)

If you prefer Interface Builder, add a small extension so the border color appears in the Attributes inspector.

import UIKit

@IBDesignable
extension UITextField {
    @IBInspectable var borderColor: UIColor? {
        get {
            guard let cg = layer.borderColor else { return nil }
            return UIColor(cgColor: cg)
        }
        set {
            layer.borderColor = newValue?.cgColor
            layer.borderWidth = newValue == nil ? 0 : 1
            borderStyle = .none
            layer.masksToBounds = true
        }
    }

    @IBInspectable var borderWidth: CGFloat {
        get { layer.borderWidth }
        set { layer.borderWidth = newValue }
    }

    @IBInspectable var cornerRadius: CGFloat {
        get { layer.cornerRadius }
        set { layer.cornerRadius = newValue }
    }
}

After adding this file to the target, select any text field in the storyboard, open the Attributes inspector, and you’ll see Border Color, Border Width, and Corner Radius fields.

3. SwiftUI wrapper (if you’re mixing UIKit in SwiftUI)

When you wrap a UITextField with UIViewRepresentable, apply the same layer configuration in makeUIView:

import SwiftUI
import UIKit

struct CustomTextField: UIViewRepresentable {
    @Binding var text: String
    var borderColor: Color = .blue

    func makeUIView(context: Context) -> UITextField {
        let tf = UITextField()
        tf.borderStyle = .none
        tf.layer.borderWidth = 1
        tf.layer.borderColor = UIColor(borderColor).cgColor
        tf.layer.cornerRadius = 8
        tf.layer.masksToBounds = true
        tf.delegate = context.coordinator
        return tf
    }

    func updateUIView(_ uiView: UITextField, context: Context) {
        uiView.text = text
        uiView.layer.borderColor = UIColor(borderColor).cgColor
    }

    func makeCoordinator() -> Coordinator { Coordinator(text: $text) }
    final class Coordinator: NSObject, UITextFieldDelegate {
        @Binding var text: String
        init(text: Binding<String>) { _text = text }
        func textFieldDidChangeSelection(_ tf: UITextField) { text = tf.text ?? "" }
    }
}

How to prevent it

  • Always set borderStyle = .none before configuring the layer; otherwise the system border overlaps yours.
  • Remember layer.borderColor takes a CGColor, not a UIColor directly.
  • Enable layer.masksToBounds = true whenever you use cornerRadius so the background doesn’t bleed outside the rounded corners.
  • If you support dark mode, use semantic colors (e.g., .systemBlue, .label) or a color asset so the border adapts automatically.
  • For reusable styling, centralize the logic in an extension or a TextFieldStyle protocol instead of copying the four lines everywhere.

FAQ

Why does my custom border disappear when the text field becomes first responder?

Some system animations briefly reset the layer. Re-apply the border color in textFieldDidBeginEditing(_:) or, better, move the styling to a subclass’s layoutSubviews so it survives every layout pass.

Can I animate the border color change?

Yes. Wrap the layer.borderColor assignment in a UIView.animate block or use CABasicAnimation on the borderColor key path for more control.

Does this work on macOS (Mac Catalyst)?

Yes. UITextField on Mac Catalyst is still backed by CALayer, so the same code works. Just ensure you import QuartzCore (automatically included via UIKit on iOS, but explicit on macOS).

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 3.0; this article is shared under the same license.