dropcap.js
dropcap.js makes beautiful drop caps easy for the web. Try it out at http://webplatform.adobe.com/dropcap.js/
Why
Though drop caps are very common in magazines and books, they remain rare on the web. We believe this is because doing it right simply and reliably is too difficult. A simple CSS float:left on a ::first-letter pseudo-element is not enough, as this tumblr shows. This blog post explains some of the challenges of defining drop caps in CSS today.
The CSS Working Group is currently specifying a new property for drop cap layout. Until this makes it into all our favorite browsers we wanted to make it work with today's platform.
Getting Started
Options for adding dropcap.js to your project:
- Install with npm:
npm install dropcap.js
- Clone the repo:
git clone https://github.com/adobe-webplatform/dropcap.js.git
Using dropcap.js
First, your drop cap letters need to be enclosed in an HTML element e.g.:
<p> <span class="dropcap">T</span>HE Quick Brown Fox... </p>
This is required because the CSS Object Model does not expose write access to the styling of pseudo-elements like ::first-letter; until then, explicit markup is preferred in this version.
Then, once you have updated your markup, simply include the script in your page.
<script src='./dropcap.min.js'></script>
The script defines the window.Dropcap.layout
method; you call it like so:
window.Dropcap.layout(dropcapRef, heightInLines, baselinePos);
For instance:
<script src='./dropcap.min.js'></script> <script> // We retrieve our drop cap elements using a class selector... var dropcaps = document.querySelectorAll(".dropcap"); // ...then give them a height of three lines. // By default, the drop cap's baseline will also be the third paragraph line. window.Dropcap.layout(dropcaps, 3); </script>
For a live example, see the source code of the our project home page.
Dropcap.layout(dropcapRef, heightInLines, baselinePos)
dropcapRef
The dropcapRef
parameter may be one of:
- An individual HTMLElement object
- A NodeList e.g. obtained from
querySelectorAll()
or a property such asNode.childNodes
For instance:
<script src='./dropcap.min.js'></script> <script> var dropcaps = document.querySelectorAll(".dropcap"); window.Dropcap.layout(dropcaps, 3); </script>
The specified element(s) will be floated, sized and positioned based on the values you specify for baselinePos
and heightInLines
.
heightInLines
The heightInLines
parameter must have a value of 1 or higher. It specifies the height of the drop cap as a number of lines of the adjoining paragraph.
baselinePos (optional)
The baselinePos
parameter is optional; when specified, its value should be 1 or higher. It defines which baseline of its parent element the drop cap's own baseline must align with. For instance, a value of 4 means 'align the drop cap's baseline with the baseline of the paragraph's fourth line'. By default, baselinePos
is the same as heightInLines
, which makes the drop cap extend from the baseline of the baselinePos
-th line to the cap line of the first line. (This is the most common use-case). When baselinePos
is smaller than heightInLines
, the result is that of a 'raised cap' as the top of the drop cap will be a number of lines above the first line of the paragraph.
The Dropcap.options object
The properties of the options object expose general runtime configuration features of dropcap.js.
runEvenIfInitialLetterExists
Default value: true
When this option is true, Dropcap.layout
will run whether or not the browser supports the initial-letter
property. When set to false, Dropcap.layout
will first check for the presence of initial-letter
in the CSSOM and abort if it is found. Prefixed variations are checked.
Building dropcap.js
To edit and build your own version of dropcap.js, you will need node, npm, and grunt. To build:
- Clone the repository
- Enter the src directory of the repo
- Run
npm install
- Run
grunt build
You should see a dropcap.js
and dropcap.min.js
in the repository's root.
Testing dropcap.js
The test folder currently has one test. The ten-line-tests.html file has several large initial letters hand-coded to look correct in Mac Firefox. The test button will run window.Dropcap.layout
on all of these initial letters and measure the difference between the script output and the hand-coded expected result. The differences are displayed in the console. This test was used to confirm whether iterations on the library were improving or degrading the result.
Known Constraints & Limitations
- We recommend setting an explicit line-height value for your drop caps' parent element. At least one browser (Chrome) computes the property's initial value of 'normal' to 'normal' instead of a length. You will get the best results with a length value or a factor like 1.2.
- dropcap.js currently assumes western content. Other international conventions - e.g. drop words, or Asian script conventions - are not supported.
- The current logic assumes the drop cap element's content to be a single glyph. It will not fail with several but was tested for single-glyph use.
- Dynamic content updates or document resizing are not automatically handled. It is up to the application to call
window.Dropcap.layout
when necessary. - Fonts are assumed to be loaded by the time dropcap.js computed the font-family property.
- The sizing and positioning of the drop cap are done using pixel lengths. A future update may use EMs.
Browser Support
We tested dropcap.js on Windows (IE10+, Firefox, Chrome) and OSX (Firefox, Chrome, Safari).
Feedback
Please let us know if you have any feedback. If you run into any problems, you can file a new issue. You can also reach us @adobeweb.