Repository navigation
Border.symmetric() is confusing #193094
Description
Use case
Developers combining symmetric EdgeInsets (padding) and borders might get a bit confused that "vertical/horizontal" does not mean the same thing for borders and padding.
Given the following code sample:
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
body: Center(
child: Container(
color: Colors.green,
padding: .symmetric(horizontal: 32, vertical: 4),
child: DecoratedBox(
decoration: BoxDecoration(
border: Border.symmetric(
vertical: BorderSide(color: Colors.red),
horizontal: BorderSide(color: Colors.blue),
),
),
child: Text('Hello, World!'),
),
),
),
),
);
}
}- The vertical padding is on the top and bottom, the horizontal padding is on the left and right.
- Now compare the above statement with what happens for Border: The "vertical" argument are the left and right borders, not the top and bottom ones. This is very unintuitive in my opinion.
In retrospect the arguments refer to how the border is drawn, not where it is positioned. (i.e. left & right are drawn vertically)
The entire framework barely uses said constructor, it only seems to be referenced in a test?
TableBorder also has a symmetric constructor, but that one uses different named parameters (inside, outside) and applies them uniformly like so
const TableBorder.symmetric({
BorderSide inside = BorderSide.none,
BorderSide outside = BorderSide.none,
this.borderRadius = BorderRadius.zero,
}) : top = outside,
right = outside,
bottom = outside,
left = outside,
horizontalInside = inside,
verticalInside = inside;
Proposal
Deprecate the "old" behavior of Border.symmetric() and flip the arguments around so that "horizontal" means left/right and "vertical" means top/bottom, matching what EdgeInsets does.
Context
The original addition is 6+ years old, and the original issue for it #45524
did not specify exactly which side horizontal/vertical where for (the example in the issue seems very arbitrary)
Activity
Renzo-Olivares commentedon Sep 22, 2026
Hi @navaronbracke, thanks for filing this proposal!
Looking back at the git history, there is actually an interesting backstory here:
EdgeInsets.symmetricdates back to March 2016 (e71bd77e4f4), whereverticalapplies totop/bottomandhorizontalapplies toleft/right.Border.symmetricwas originally added in January 2020 (AddBorder.symmetricconstructor #47523), it did matchEdgeInsets.symmetric(top = vertical, bottom = vertical, left = horizontal, right = horizontal).left = vertical, right = vertical, top = horizontal, bottom = horizontalon the rationale that the vertical borders (the lines running vertically, likeTableBorder.verticalInsideandVerticalDivider) are the left and right borders, whereas horizontal borders (likeTableBorder.horizontalInsideandDivider) are the top and bottom borders.Because this behavior was deliberately migrated in #61470 to align with
Divider/VerticalDivider/TableBorderand has been in place for 6 years, flipping it back in-place would break existing callers. We can leave this open to see if there is appetite for clearer parameter naming or documentation.navaronbracke commentedon Sep 22, 2026
Then I would propose to use this as an addendum to the docs?
I.e.
Then again I personally don't really use this constructor much (I either pick fromBorderSide() or explicit top/left/right/bottom in the unnamed constructor)
[docs] Make Border.symmetric docs more explicit about their arguments (…
github-actions commentedon Oct 16, 2026
This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of
flutter doctor -vand a minimal reproduction of the issue.[docs] Make Border.symmetric docs more explicit about their arguments (…