subcaption vs. subfig: Best package for referencing a subfigure

On this question, a comment by Martin H says: that one should forget about the subfigure and subfig packages and use subcaption. As subfig replaces subfigure, no argument there.

I am currently using subfig for displaying my subfigures and quite content with it. So I am wondering, what the advantages of using subcaption instead would be or if and why the use of subcaption is generally preferable to subfig.

-

subfig is not working properly with hyperref. The author of the caption package wrote here:

Please note that the hyperref support within the subfig package is broken. You could give my subcaption package a try instead.

Internet or Usenet search for subfig+hyperref would show compatibility and functionality issues, I guess we don't need to create an example for it here.

-
Thanks, and yes, really no need for an example here :) –  meep.meep Mar 16 '11 at 14:23
meep.meep The problem now is Do you think hyperref works properly? You write : If A does not work with B, but A works with C then B is obsolete but if B works with D and C does not work with D then what is your choice ? –  Alain Matthes Mar 16 '11 at 16:16
@Altermundus: As this question is just about the choice between subfig and subcaption, I think your comment can make a new question. Besides that: subfig hasn't been changed since 2005. In contrast, hyperref got many updates and improvements, the most recent update has been just 7 days ago. And, in my experience, subcaption supports hyperref well. –  Stefan Kottwitz Mar 16 '11 at 18:08
Basically the intention of my comment was to point out that subfig is not actively developed anymore but subcaption is. Also, just a personal preference, the syntax of subcaption with \begin{} \end{} looks much cleaner un more readable to me –  Martin H Mar 17 '11 at 10:08
@Altermundus: I agree with Stefan and think this would need to be asked in a new question, and a very interesting one as off the top of my head I (and I guess we all) can think of several packages not working properly with hyperref. Just didn't know about this incompability yet. –  meep.meep Mar 17 '11 at 11:49

Pro subcaption:

• subfig's hyperref support contains bugs (which is clearly a problem of subfig and not of hyperref) while the subcaption package (hopefully ;-)) works fine with hyperref.
• The subcaption package offers enhanced hyperref support, \subref* will behave like \ref* (offered by the hyperref package), \autoref will work out-of-the-box, and the caption options hypcap= and hypcapspace= will work for sub-captions, too.
• The subfig package breaks the starred version of \ContinuedFloat offered by the caption package while the subcaption package does not.
• The subcaption package is more "in touch" with the caption package, supporting more common options like list=on etc., and offering similar commands to \caption, \captionbox, and the figure environment: \subcaption, \subcaptionbox, and the subfigure environment. (Please note that \captionbox is not avail yet but will be offered by the very next version 3.2 of the caption package.)
• Offers more ways to place and align sub-captions, e.g. \subcaption could be used to place a sub-caption (left or right) beside the figure.
• \subcaptionbox offers more optional arguments than \subfloat, e.g. for giving the box a specific width.
• Offers \phantomsubcaption for referencing without having a caption. (since version 1.1 of the subcaption package)
• Is supported by the bicaption package for typesetting bilingual sub-captions. (since version 1.1 of the subcaption package)

Pro subfig:

• The subcaption package needs the caption package while the usage of the caption package is optional in subfig. (The subfig package offers the option caption=false.) Because of that the subfig package could also be used with document classes which are incompatible to the caption package.
• The subcaption package does not offer top and bottom margins (yet) while the subfig package does. So when using the subcaption package one have to do the vertical spacing between sub-figures manually by using the \vspace command, \smallskip, \medskip, \bigskip, or similar.

Please note that I'm the author of the caption & subcaption package, so this list is far from being objective ;-)

But is the use of subcaption generally preferable to subfig? IMHO no, because the subfig package is a fine (and well documented) one, and if one is contented with the subfig package there is no need to switch.

-
Could you update the Package maintainers list on the meta site? –  Seamus Mar 18 '11 at 15:46
@Seamus Didn't know about that list before - just added my dog tag there. –  Axel Sommerfeldt Mar 18 '11 at 18:09
Maybe it should be mentioned that the subfloats of subfig determine their width automatically, while subfigure from subcaption needs the width specified. –  mafp Feb 1 '13 at 14:47
subfloats of subcaption, typeset with \subcaptionbox, will determine their width automatically, too. –  Axel Sommerfeldt Feb 2 '13 at 8:48
subfig reserves space for caption even if you say caption{}. And if don't, you get warning from hyperref. subcaption does not have that problem. –  Jori Mäntysalo Jun 1 '13 at 8:59

Just for documentation: In an up-to-date TeXlive 2011 installation, references to subfloats are off by one if the caption is above the subfloat (position=top). In the example below, this concerns references to subtables but not to subfigures.

\documentclass{scrartcl}
\pagestyle{empty}
\usepackage{subfig}

\captionsetup*[table]{position=top}
\captionsetup*[subtable]{position=top}
\captionsetup*[figure]{position=bottom}
\captionsetup*[subfigure]{position=bottom}

\begin{document}
\begin{figure}
\subfloat[1]{11111\label{fig:1}} \subfloat[2]{22222\label{fig:2}}
\caption{fig}\label{fig}
\end{figure}

\begin{table}
\caption{tbl}\label{tbl}
\subfloat[A]{aaaaa\label{tbl:a}} \subfloat[B]{bbbbb\label{tbl:b}}
\end{table}

Figure~\ref{fig} (\ref{fig:1}, \ref{fig:2})  and Table~\ref{tbl} (\ref{tbl:a}, \ref{tbl:b}).
\end{document}


Switching to subcaption has resolved the issues, but I wish there would be a "compatibility" option so that code that used to work with subfig works also with subcaption. (Or at least a HOWTO with a reference to \subcaptionbox.)

-
@percusse: I don't see how Section 4.3 of the subfig manual (?) relates to referencing errors. The problem here is not the misaligned "a"-s and "b"-s, rather the references to the subtables (lowest line of text). –  krlmlr Jul 25 '12 at 11:51
There were plans implementing an "compatibility" option, and very early versions of the subcaption package even offered \subfloat as well (but this was never a documented feature), but it has shown that this was not a very good idea. For example the subfig package allows having the \label in its contents while the subcaption package does not. Clearing this issue and removing more subtle differences would end up in writing more code for offering a compatible \subfloat than it took for the rest of the whole subcaption package. (Therefore I decided to drop that idea.) –  Axel Sommerfeldt Feb 1 '13 at 7:43
Regarding the HOWTO: IMHO a HOWTO for migrating from subfig to subcaption offered by me would have been overbearing. But since subfig is "dead" more than 7 years now I may need reconsidering this... –  Axel Sommerfeldt Feb 1 '13 at 7:50