Creating Custom Gestures by Subclassing UIGestureRecognizer

Why it exists

iOS provides a rich set of standard gestures like taps and swipes, but some applications require unique interactions not covered by the defaults. Subclassing UIGestureRecognizer was created to provide a formal, reusable way to define new gestures, encapsulating complex touch-parsing logic instead of scattering it inside a view controller.

The mental model

Think of a custom gesture recognizer as a small, focused state machine. It observes a raw stream of touch data, and your job is to write the rules that determine if that stream constitutes your specific gesture. You are essentially teaching the system a new pattern of touch interaction by defining what sequence of touches is significant.

How it works

You create a subclass of UIGestureRecognizer and override the core touch-handling methods: touchesBegan, touchesMoved, touchesEnded, and touchesCancelled. Within these methods, you inspect the UITouch objects to track finger movement, timing, and position. Based on your custom logic, you manually update the recognizer's state property. For a gesture to be successful, you must transition its state from the initial .possible to .began (when the gesture starts), then potentially .changed (as it continues), and finally to .ended. If the touch sequence doesn't match your criteria, you must set the state to .failed so the system can let other recognizers try.

When to use it

Subclass when you need a novel, reusable interaction that is core to your app's identity. This is ideal for things like a circular dial gesture, a specific drawing pattern to trigger an action (like drawing a checkmark), or a multi-finger "chord" to open a special menu. It keeps your code clean and your gesture logic portable.

When not to use it

Avoid subclassing for simple configurations of existing gestures. If you just need a two-finger tap, configure a standard UITapGestureRecognizer's numberOfTouchesRequired property. Subclassing is overkill if a built-in recognizer can be configured to do the job. It's also generally not for one-off, simple touch handling that is tightly coupled to a single view and will never be reused.

One canonical example

Creating a gesture to detect a small circular motion. In touchesBegan, you would store the initial touch point as the circle's center. In touchesMoved, you would calculate the distance and angle of the current touch point relative to the center. If the touch moves around the center while maintaining a relatively constant radius, you could set the state to .began and then .changed. If the finger is lifted after completing a near-full circle, you set the state to .ended. If the finger moves too far from the center or strays wildly, you set the state to .failed.