superhuman-squire-rte
Advanced tools
Squire is an HTML5 rich text editor, which provides powerful cross-browser normalisation, whilst being supremely lightweight and flexible.
Squire is an HTML5 rich text editor, which provides powerful cross-browser normalisation, whilst being supremely lightweight and flexible. It is built for the present and the future, and as such does not support truly ancient browsers. It should work fine back to around Opera 12, Firefox 3.5, Safari 5, Chrome 9 and IE9.
An example UI integration can be tried at http://neilj.github.io/Squire/.
Unlike other HTML5 rich text editors, Squire was written as a component for writing documents (emails, essays, etc.), not doing wysiwyg websites. If you are looking for support for inserting form controls or flash components or the like, you'll need to look elsewhere. However for many purposes, Squire may be just what you need, providing the power without the bloat. The key features are:
<textarea> and manipulate programatically.Squire provides an engine that handles the heavy work for you, making it easy to add extra features. With the changeFormat method you can easily add or remove any inline formatting you wish. And the modifyBlocks method can be used to make complicated block-level changes in a relatively easy manner.
If you need more commands than in the simple API, I suggest you check out the source code (it's not very long), and see how a lot of the other API methods are implemented in terms of these two methods.
The general philosophy of Squire is to allow the browser to do as much as it can (which unfortunately is not very much), but take control anywhere it deviates from what is required, or there are significant cross-browser differences. As such, the document.execCommand method is not used at all; instead all formatting is done via custom functions, and certain keys, such as 'enter' and 'backspace' are handled by the editor.
build/ directory onto your server.<style> block in document.html to add the default styles you
would like the editor to use (or link to an external stylesheet).<textarea>, use an
<iframe src="path/to/document.html">.load event of the iframe. When
this fires you can grab a reference to the editor object through
iframe.contentWindow.editor.editor object to set and get data and integrate
with your application or framework.Squire can also be used without an iframe for the document. To use it this way:
<script> tag to load in build/squire.js (or squire-raw.js for the debuggable unminified version).node = document.getElementById( 'editor-div' ).editor = new Squire( node ). This will instantiate a new Squire instance. Please note, this will remove any current children of the node; you must use the setHTML command after initialising to set any content.You can have multiple squire instances in a single page without issue. If you are using the editor as part of a long lived single-page app, be sure to call editor.destroy() once you have finished using an instance to ensure it doesn't leak resources.
If you load the library into a top-level document (rather than an iframe), or load it in an iframe without the data-squireinit="true" attribute on its <html> element, it will not turn the page into an editable document, but will instead add a constructor named Squire to the global scope.
You can also require the NPM package squire-rte to import Squire in a modular program without adding names to the global namespace.
Call new Squire( document ), with the document from an iframe to instantiate multiple rich text areas on the same page efficiently. Note, for compatibility with all browsers (particularly Firefox), you MUST wait for the iframe's onload event to fire before instantiating Squire.
By default, the editor will use a <div> for blank lines, as most users have been conditioned by Microsoft Word to expect Enter to act like pressing return on a typewriter. If you would like to use <p> tags (or anything else) for the default block type instead, you can pass a config object as the second parameter to the squire constructor. You can also
pass a set of attributes to apply to each default block:
var editor = new Squire( document, {
blockTag: 'P',
blockAttributes: { style: 'font-size: 16px;' }
})
If using the simple setup, call editor.setConfig(…); with your
config object instead. Be sure to do this before calling editor.setHTML().
If you are adding a UI to Squire, you'll probably want to show a button in different states depending on whether a particular style is active in the current selection or not. For example, a "Bold" button would be in a depressed state if the text under the cursor is already bold.
The efficient way to determine the state for most buttons is to monitor the "pathChange" event in the editor, and determine the state from the new path. If the selection goes across nodes, you will need to call the hasFormat method for each of your buttons to determine whether the styles are active. See the getPath and hasFormat documentation for more information.
Squire is released under the MIT license. See LICENSE for full license.
Attach an event listener to the editor. The handler can be either a function or an object with a handleEvent method. This function or method will be called whenever the event fires, with an event object as the sole argument. The following events may be observed:
editor.getHTML() will have changed.path property on the event object.canUndo and canRedo to let you know the new state.fragment property on the event object. You can modify this fragment in your event handler to change what will be pasted. You can also call the preventDefault on the event object to cancel the paste operation.The method takes two arguments:
Returns self (the Squire instance).
Remove an event listener attached via the addEventListener method.
The method takes two arguments:
Returns self (the Squire instance).
Adds or removes a keyboard shortcut. You can use this to override the default keyboard shortcuts (e.g. Ctrl-B for bold – see the bottom of KeyHandlers.js for the list).
This method takes two arguments:
"alt-ctrl-meta-shift-enter"null if removing a key handler. The function will be passed three arguments when called:
Returns self (the Squire instance).
Focuses the editor.
The method takes no arguments.
Returns self (the Squire instance).
Removes focus from the editor.
The method takes no arguments.
Returns self (the Squire instance).
Returns the document object of the editable area. May be useful to do transformations outside the realm of the API.
Returns the HTML value of the editor in its current state. This value is equivalent to the contents of the <body> tag and does not include any surrounding boilerplate.
Sets the HTML value for the editor. The value supplied should not contain <body> tags or anything outside of that.
The method takes one argument:
Returns self (the Squire instance).
Returns the text currently selected in the editor.
Inserts an image at the current cursor location.
The method takes one argument:
Returns a reference to the newly inserted image element.
Inserts an HTML fragment at the current cursor location, or replaces the selection if selected. The value supplied should not contain <body> tags or anything outside of that.
The method takes one argument:
Returns self (the Squire instance).
Returns the path through the DOM tree from the <body> element to the current current cursor position. This is a string consisting of the tag, id, class, font, and color names in CSS format. For example BODY>BLOCKQUOTE>DIV#id>STRONG>SPAN.font[fontFamily=Arial,sans-serif]>EM. If a selection has been made, so different parts of the selection may have different paths, the value will be (selection). The path is useful for efficiently determining the current formatting for bold, italic, underline etc, and thus determining button state. If a selection has been made, you can has the hasFormat method instead to get the current state for the properties you care about.
Returns an object containing the active font family, size, colour and background colour for the the current cursor position, if any are set. The property names are respectively family, size, color and backgroundColor. It looks at style attributes to detect this, so will not detect <FONT> tags or non-inline styles. If a selection across multiple elements has been made, it will return an empty object.
Returns a bounding client rect (top/left/right/bottom properties relative to the viewport) for the current selection/cursor.
Returns a W3C Range object representing the current selection/cursor position.
Changes the current selection/cursor position.
The method takes one argument:
Returns self (the Squire instance).
Removes any current selection and moves the cursor to the very beginning of the document.
Returns self (the Squire instance).
Removes any current selection and moves the cursor to the very end of the document.
Returns self (the Squire instance).
Saves an undo checkpoint with the current editor state. Methods that modify the state (e.g. bold/setHighlightColour/modifyBlocks) will automatically save undo checkpoints; you only need this method if you want to modify the DOM outside of one of these methods, and you want to save an undo checkpoint first.
Returns self (the Squire instance).
Undoes the most recent change.
Returns self (the Squire instance).
If the user has just undone a change, this will reapply that change.
Returns self (the Squire instance).
Queries the editor for whether a particular format is applied anywhere in the current selection.
The method takes two arguments:
Returns true if any of the selection is contained within an element with the specified tag and attributes, otherwise returns false.
Makes any non-bold currently selected text bold (by wrapping it in a <b> tag).
Returns self (the Squire instance).
Makes any non-italic currently selected text italic (by wrapping it in an <i> tag).
Returns self (the Squire instance).
Makes any non-underlined currently selected text underlined (by wrapping it in a <u> tag).
Returns self (the Squire instance).
Removes any bold formatting from the selected text.
Returns self (the Squire instance).
Removes any italic formatting from the selected text.
Returns self (the Squire instance).
Removes any underline formatting from the selected text.
Returns self (the Squire instance).
Makes the currently selected text a link. If no text is selected, the URL or email will be inserted as text at the current cursor point and made into a link.
This method takes two arguments:
<a> node. e.g. { target: '_blank' }. Any href attribute will be overwritten by the url given as the first argument.Returns self (the Squire instance).
Removes any link that is currently at least partially selected.
Returns self (the Squire instance).
Sets the font face for the selected text.
This method takes one argument:
Returns self (the Squire instance).
Sets the font size for the selected text.
This method takes one argument:
Returns self (the Squire instance).
Sets the colour of the selected text.
This method takes one argument:
Returns self (the Squire instance).
Sets the colour of the background of the selected text.
This method takes one argument:
Returns self (the Squire instance).
Sets the text alignment in all blocks at least partially contained by the selection.
This method takes one argument:
Returns self (the Squire instance).
Sets the text direction in all blocks at least partially contained by the selection.
This method takes one argument:
Returns self (the Squire instance).
Executes a function on each block in the current selection, or until the function returns a truthy value.
This method takes two arguments:
Returns self (the Squire instance).
Extracts a portion of the DOM tree (up to the block boundaries of the current selection), modifies it and then reinserts it and merges the edges. See the code for examples if you're interested in using this function.
This method takes one argument:
this is bound to the Squire instance. Should return the node or fragment to be reinserted in the DOM.Returns self (the Squire instance).
Increases by 1 the quote level (number of <blockquote> tags wrapping) all blocks at least partially selected.
Returns self (the Squire instance).
Decreases by 1 the quote level (number of <blockquote> tags wrapping) all blocks at least partially selected.
Returns self (the Squire instance).
Changes all at-least-partially selected blocks to be part of an unordered list.
Returns self (the Squire instance).
Changes all at-least-partially selected blocks to be part of an ordered list.
Returns self (the Squire instance).
Changes any at-least-partially selected blocks which are part of a list to no longer be part of a list.
Returns self (the Squire instance).
Increases by 1 the nesting level of any at-least-partially selected blocks which are part of a list.
Returns self (the Squire instance).
Decreases by 1 the nesting level of any at-least-partially selected blocks which are part of a list.
Returns self (the Squire instance).
Removes all formatting from the selection. Block elements (list items, table cells, etc.) are kept as separate blocks.
Returns self (the Squire instance).
Change the inline formatting of the current selection. This is a high-level method which is used to implement the bold, italic etc. helper methods. THIS METHOD IS ONLY FOR USE WITH INLINE TAGS, NOT BLOCK TAGS. It takes 4 arguments:
null if you only wish to remove formatting. If supplied, this object should have a tag property with the string name of the tag to wrap around the selected text (e.g. "STRONG") and optionally an attributes property, consisting of an object of attributes to apply to the tag (e.g. {"class": "bold"}).null if you only wish to add formatting.null/omit to apply to current selection).false if omitted). If true, any formatting nodes that cover at least part of the selected range will be removed entirely (so will potentially be removed from text outside the selected range as well). If false, the formatting nodes will continue to apply to any text outside the selection. This is useful, for example, when removing links. If any of the text in the selection is part of a link, the whole link is removed, rather than the link continuing to apply to bits of text outside the selection.Takes in a function that can modify the document without the modifications being treated as input.
This is useful when the document needs to be changed programmatically, but those changes should not raise input events or modify the undo state.
FAQs
Squire is an HTML5 rich text editor, which provides powerful cross-browser normalisation, whilst being supremely lightweight and flexible.
We found that superhuman-squire-rte demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.