How it works
ButtonBorderShape describes the outline that SwiftUI draws around a button's background, letting you control whether that border reads as a capsule, a rounded rectangle, a circle, or another predefined form. It exists so you can shape a button's bordered appearance without writing a custom button style or clipping the control by hand. Reach for it when a bordered button style fills its background but you want that fill to follow a particular silhouette — for example, a pill-shaped call to action or a round icon button.
Apply a shape with buttonBorderShape(_:)
The
buttonBorderShape(_:)modifier sets theButtonBorderShapethat surrounding buttons use to draw their border. You attach it to a button or to a container of buttons and pass one of the shape values, as in.buttonBorderShape(.capsule).Pair it with a bordered style
ButtonBorderShapeonly takes visible effect when the button has a background to outline, so it works alongside a bordered button style. Here.buttonStyle(.borderedProminent)gives each button a filled background, and the border shape then determines the contour that fill follows.Choose a built-in shape value
The type vends static members for the common forms:
.capsuleproduces fully rounded ends,.roundedRectangleproduces softly rounded corners, and.circleproduces a round outline suited to compact, icon-style buttons. EachButtonin the example selects a different one to show the contrast.Scope it through the environment
Because
buttonBorderShape(_:)propagates through the view hierarchy, placing it on a container applies the sameButtonBorderShapeto every button inside. Applying it per button instead — as theVStackdoes here — lets each control adopt its own shape.
.buttonBorderShape(.circle) on the "Circle" button to .buttonBorderShape(.roundedRectangle) and watch its outline shift from a round form to softly rounded corners.Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct ButtonBorderShapeDemo: View {
var body: some View {
VStack(spacing: 16) {
Button("Capsule") {}
.buttonBorderShape(.capsule)
Button("Rounded") {}
.buttonBorderShape(.roundedRectangle)
Button("Circle") {}
.buttonBorderShape(.circle)
}
.buttonStyle(.borderedProminent)
.padding()
}
}