🧭 Migration from Angular Flex-Layout

If you consider migrating to css-fx-layout from Angular Flex-Layout be sure to know this library's limitations. Not every feature of Flex-Layout is available but almost all popular features should be and some missing features can be easily replaced.

As the migration is easier when you choose to use css-fx-layout with attribute selectors, this guide only focuses on this migration.

Limitations

Let's start with what is missing in css-fx-layout in comparison with Angular Flex-Layout:

• no JavaScript API
• no general support for Angular expression bindings
• no alternative for fxFlex with numerical units other than percent
• the alternatives for fxFlexAlign only support start, center, end, baseline and stretch
• no grid functionality
• no alternative for fxFlexOrder
• no alternative for fxFlexOffset
• no custom breakpoints
• the alternative to fxShow only supports the responsive API and does not work the same way it does in Flex-Layout

Migrate away from fxShow / data-show

When moving to css-fx-layout it is recommended to migrate all elements using fxShow with more than one media size or in combination with fxHide to multiple data-hide attributes. css-fx-layout is not a JavaScript powered library and cannot make the selectors work the same smart way they do in Angular Flex-Layout. Ignoring this advice and keeping multiple data-show attributes on your elements or trying to combine them with data-hide will very likely not result in what you want!

There may be more differences in the details but these are the most obvious and big ones.

Migration

Now that we got this out of the way let's migrate. There is a migration script available which will try to do most of it automatically. You can call it like this:

npx css-fx-layout migrate [path/to/src]

The script does the following:

• Migrate all supported selectors in all .html files from flex-layout to css-fx-layout
• Migrate (row|column)-reverse to (row|column) reverse
• Log warnings for some of the unsupported selectors
• Log warnings when data-flex (before migration: fxFlex) is being used with unsupported values
• Log warnings when data-show (before migration: fxShow) is being used

After running the script, you should do the following:

• Check the warnings and resolve the issues
• You should change your code to follow the advice regarding data-show (before migration: fxShow) from the warning box above
• You should check all usages of Angular expression bindings. Some may need to be changed for it to continue to work as you expect it. For example [fxHide]="hideIfTrue should be changed to [attr.data-hide]="hideIfTrue ? true : null". The reason is that Angular needs to remove the attribute if the condition is false, because otherwise the CSS will be applied without checking the condition in the value.
• If you are using a different file extension than .html, for example, if you have short templates inlined in the .ts files, you need to do the change manually.
• Check your application for layout issues. After following this gude almost everything should work, but the libraries are effectively not the same and may differ in some details.

The script can be run multiple times. After the first run, it will just continue to log the warnings. You can use this to check if you removed all warnings.

info

css-fx-layout generates some selectors only for the defined numerical values, for example the gap or flex selectors. Make sure to customise the parameters of the mixins in a way that generates all selectors you need in your project.

Previously, this section contained a table specifying the regex find and replaces necessary, but as it was not covering all cases, it has been removed. If you are interested in the find/replace necessary please look into the code of the migration script.

That's it. In many projects, even larger ones, this could already be all the work required to move away from Angular Flex-Layout.

Did we miss something? Feel free to contribute to the documentation, migration script or the library on GitHub.