Cup marker.

Available on Hole and Green graphics, the Cup marker shares the Flag marker's protected green placement plus local movement, reset, image, and origin controls. It uses an image-only square golf cup PNG with no visible label and aligns its center to the authoritative pixel by default.

type: "cup"component: caddie-cup-markerProtected placement

Usage

Add the cup marker to a graphic.

Include the component in the initial mount call, reconcile it through view.setSmartComponents, or append it with view.addSmartComponent. Types may repeat. Give repeated instances stable id values to style, show, hide, move, reset, or remove one instance independently. The selected Smart Component type, instance ID, render receipt, and protected selection options such as yardages, grid spacing, coverage, measured origin, buffer distance, detail, limits, or targets are sent to the overlay service. Marker-image origins, images, presentation styles, supported labels, and movement remain local.

const view = await caddie.mount(container, graphicRequest, [
  {
    type: "cup",
    target: "maximum-clearance",
    movable: false,
    origin: "center",
    style: {
      size: 16,
    },
  },
]);

view.setSmartComponentStyle({ type: "cup", style: { size: 20 } });
view.setSmartComponentImage("cup", null);

Defaults

Built-in presentation.

Protected targetMeasured green center

Origincenter

Proxy diameter16 inches

Built-in visualSquare transparent golf cup PNG

Component options

Configure behavior and presentation.

Option	Type	Default	Description
type	"cup"	Required	Requests protected green placement and selects the cup marker component.
target	"green-center" \| "maximum-clearance"	"green-center"	Chooses the measured green center or the protected maximum-clearance point: the center of the largest ground-space circle contained by the mapped green.
id	string	Automatic	Optional stable 1–64 character instance ID using letters, numbers, underscores, or hyphens. Use IDs to independently control repeated Smart Components of the same type.
movable	boolean	false	Allows pointer dragging and arrow-key movement. Shift + Arrow moves the marker by 10 image pixels.
imageUrl	string \| null	null	Uses a client-hosted HTTPS PNG instead of the built-in transparent PNG. Pass null to restore the built-in PNG.
origin	GraphicOverlayOrigin	Component default	Selects which point on the marker is aligned with the protected placement pixel.
style.size	number	16	Cup proxy diameter in inches, from 4 through 64. The SDK scales the server-resolved image-pixel diameter proportionally without rebuilding the graphic.

Behavior

Important implementation details.

Center origin aligns the middle of the cup image with the protected resolved green pixel.
maximum-clearance finds the center of the largest circle contained by the green in protected ground-meter space; it falls back to green-center when mapped polygon geometry is unavailable.
Only the final image pixel and resolvedTarget reach the browser. Green polygons and projection transforms remain server-side.
The server converts a 16-inch physical proxy through the protected render scale and applies a small image-relative readability floor on distant hole views.
The Cup marker is image-only and does not create or accept a visible label.
Clients can change movement, size, origin, or image locally without rebuilding the clean graphic.
The built-in cup remains visible if a custom HTTPS PNG fails to load.

Protected course dataComponent responses contain only artifact-bound image pixels and safe presentation values. They do not include longitude, latitude, course geometry, affine transforms, control points, or the internal render sidecar.